halter-rust

halter

halter is a simple and configurable agent harness and SDK for building and operating thoroughbred agents.

[!CAUTION] halter is still a heavy work in progress. Proceed at your own risk.

Design Goals

• Cache friendliness
• Obsessive token optimization
• Best in class multi model support
• Best in class tool calling and hook support
• Simple and expressive API

What halter gives you

At a high level, halter combines:

• a typed protocol for sessions, turns, events, resources, and tool calls
• a configurable runtime for prompt assembly, context management, provider execution, hooks, and subagents
• a built-in tool harness for reading, editing, writing, shell execution, process control, and delegated work
• resource loading for repo-local skills and plugins
• policy enforcement around filesystem writes, shell usage, tool output size, and subagent fanout
• session persistence with memory and SQLite backends

---

Quickstart

Halter is designed to be plug and play in existing Rust code and services. The goal of the halter SDK is to abstract away the details of a harness, however there is still some small boilerplate:

• loading config
• compiling resources
• injecting custom tools or hooks
• selecting persistence strategy
• consuming session events programmatically

Basic example with config file

use futures::StreamExt;
use halter::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let harness = Halter::from_config_file("halter.toml").await?;
    let session = harness.new_session(SessionInit::default()).await?;

    let mut events = session
        .submit_turn(Turn::user("Summarize the session persistence design"))
        .await?;

    while let Some(event) = events.next().await {
        let event = event?;
        println!("{:?}", event.payload);
    }

    Ok(())
}

This code does all of the following:

• loads and validates config
• compiles resources
• builds providers, tools, hooks, policy, and session storage
• creates a runtime
• creates a session
• executes one turn and streams the resulting events

Detailed events

use futures::StreamExt;
use halter::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let harness = Halter::from_config_file("halter.toml").await?;

    let session = harness
        .new_session(SessionInit {
            working_dir: std::env::current_dir()?,
            ..SessionInit::default()
        })
        .await?;

    let mut stream = session.submit_turn(Turn::user("List the major crates in this repo")).await?;
    while let Some(event) = stream.next().await {
        let event = event?;
        match event.payload {
            SessionEventPayload::DeltaItem { delta } => print!("{}", delta.text),
            SessionEventPayload::TurnCompleted { usage, .. } => {
                println!("\nusage: in={} out={}", usage.input_tokens, usage.output_tokens);
            }
            SessionEventPayload::TurnFailed { error, .. } => {
                eprintln!("turn failed: {error}");
            }
            _ => {}
        }
    }

    Ok(())
}

Simple programmatic config with snapshot

use halter::prelude::*;
use halter_config::{
    ConfiguredProvider, ModelConfig, ModelsConfig, ProviderConfig, ProvidersConfig,
};
use halter_protocol::ReasoningEffort;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = HarnessConfig {
        providers: ProvidersConfig {
            openai: Some(ProviderConfig {
                api_key: Some(std::env::var("OPENAI_API_KEY")?),
                ..ProviderConfig::default()
            }),
            ..ProvidersConfig::default()
        },
        models: ModelsConfig {
            default: Some(ModelConfig {
                provider: ConfiguredProvider::OpenAi,
                model: "gpt-5".to_owned(),
                max_input_tokens: Some(200_000),
                max_output_tokens: Some(8_192),
                reasoning: Some(ReasoningEffort::Medium),
                tokens_per_minute: Some(500_000),
            }),
            ..ModelsConfig::default()
        },
        ..HarnessConfig::default()
    };
    let snapshot = ResourceSnapshot::empty();

    let harness = Halter::from_config(config, snapshot).await?;
    let _session = harness.new_session(SessionInit::default()).await?;
    Ok(())
}

Build from config + compiled resources

use halter::{HalterBuilder, ResourceCompiler};
use halter_config::load_path;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let config = load_path("halter.toml").await?;
    let resources = ResourceCompiler::from_config(&config).compile().await?;

    let harness = HalterBuilder::new()
        .with_config(config)
        .with_compiled_resources(resources)
        .build()
        .await?;

    println!("default model = {:?}", harness.config().default_model()?.model);
    Ok(())
}

Add a custom tool