Skip to content
pbdeuchlerPublic

About

Drive your clankers like a cowboy

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

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, mut events) = harness.new_session(SessionInit::default()).await?;

    let listener = tokio::spawn(async move {
        while let Some(event) = events.next().await {
            println!("{:?}", event?.payload);
        }
        Ok::<(), anyhow::Error>(())
    });

    session.submit(Message::user("Summarize the session persistence design")).await?;
    tokio::signal::ctrl_c().await?;
    session.shutdown(None).await?;
    listener.await??;

    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
  • durably accepts input and streams session events until shutdown

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, mut stream) = harness
        .new_session(SessionInit {
            working_dir: std::env::current_dir()?,
            ..SessionInit::default()
        })
        .await?;

    let listener = tokio::spawn(async move {
        while let Some(event) = stream.next().await {
            match event?.payload {
                SessionEventPayload::DeltaItem { delta } => print!("{}", delta.text),
                SessionEventPayload::ToolOutput { chunk, .. } => print!("{chunk}"),
                SessionEventPayload::InputDelivered { message_id } => {
                    println!("input {message_id} entered history");
                }
                SessionEventPayload::InputRejected { message_id, reason } => {
                    eprintln!("input {message_id} rejected: {reason}");
                }
                _ => {}
            }
        }
        Ok::<(), anyhow::Error>(())
    });

    session.submit(Message::user("List the major crates in this repo")).await?;
    tokio::signal::ctrl_c().await?;
    session.shutdown(None).await?;
    listener.await??;

    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, _events) = harness.new_session(SessionInit::default()).await?;
    session.shutdown(None).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

use std::sync::Arc;

use async_trait::async_trait;
use halter::HalterBuilder;
use halter_config::load_path;
use halter_protocol::{ToolCapabilities, ToolConcurrency, ToolName, ToolResult, ToolSpec};
use halter_tools::{Tool, ToolContext};
use serde_json::{json, Value};

#[derive(Debug)]
struct EchoTool;

#[async_trait]
impl Tool for EchoTool {
    fn spec(&self) -> ToolSpec {
        ToolSpec {
            name: ToolName::from("echo_json"),
            description: "Return the input JSON unchanged".to_owned(),
            input_schema: json!({
                "type": "object",
                "additionalProperties": true
            }),
            concurrency: ToolConcurrency::ParallelSafe,
            capabilities: ToolCapabilities::default(),
            provider_aliases: Default::default(),
        }
    }

    async fn execute(&self, _context: ToolContext, input: Value) -> anyhow::Result<ToolResult> {
        Ok(ToolResult::Json { value: input })
    }
}

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

    let _halter = HalterBuilder::new()
        .with_config(config)
        .with_compiled_resources(resources)
        .with_tool(Arc::new(EchoTool))
        .build()
        .await?;

    Ok(())
}

A ToolResult::Json reaches the model as compact JSON, so any text inside it is escaped. When a tool returns text the model should read as written, implement halter_tools::TypedTool instead: its Output serializes to the structured value and renders its own model text.

use halter_tools::ToolOutput;
use serde::Serialize;

#[derive(Serialize)]
struct BashOutput {
    exit_code: i32,
    output: String,
}

impl ToolOutput for BashOutput {
    fn to_model_string(&self) -> String {
        match self.exit_code {
            0 => self.output.clone(),
            code => format!("{}\n[exit code {code}]", self.output),
        }
    }
}

Whatever a tool returns, the runtime bounds the text that enters the context at [tools] max_output_bytes (default 50 KiB). A larger result keeps its head and tail, and the marker line between them names the file holding the full output. A tool still limits what it holds in memory: the built-in shell captures at most 1 MiB of a command's output.

Provide your own session store

use std::sync::Arc;

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 store = Arc::new(MyFancySessionStore::default());

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

    Ok(())
}

Default prompts and the built-in coding agent

halter ships three built-in prompts, all available to SDK users:

  • a general-purpose system prompt (the default for every session),
  • a batteries-included coding-agent prompt — a quick on-ramp for a working coding agent, and
  • the context-checkpoint instructions the default compaction strategy sends the model.

The two system prompts are assembled from a shared behavioral core plus a small role-specific intro, so common guidance (acting autonomously in headless runs, preferring the provided tools, honesty, safety) is defined in exactly one place.

Read or compose them through the halter::prompts module, and seed a session with one via SessionInit::with_system_prompt. Use SessionInit::append_system_prompt to add stable house rules without restating the base prompt:

use halter::prelude::*;
use halter::prompts;

// Spin up a coding agent in one line:
let (session, events) = harness
    .new_session(
        SessionInit::default()
            .with_system_prompt(prompts::default_coding_agent_prompt())
            .append_system_prompt("## House rules\n- Never touch files under vendor/."),
    )
    .await?;

Or select a built-in from config — prompts.preset picks the built-in prompt, prompts.system_prompt overrides it entirely, and prompts.append_system_prompt adds static instructions after whichever base wins:

[prompts]
preset = "coding"            # "general" (default) | "coding"
# system_prompt = "..."      # full override; wins over preset
append_system_prompt = """
## House rules
- Conventional Commits for every commit.
- Never touch files under vendor/.
"""

Base system-prompt precedence, most specific first: an explicit per-session prompt (SessionInit::with_system_prompt) > prompts.system_prompt > prompts.preset > the built-in general-purpose default. Appends are additive: config append applies after the resolved base, then per-session append_system_prompt calls apply after that. Appended text stays in the static, prefix-cacheable System block before skills.


Crates

  • halter — high-level SDK and builder
  • halter-config — config schema, loading, overrides, validation
  • halter-protocol — shared types and wire-format vocabulary
  • halter-runtime — session engine, prompt assembly, event bus, compaction, subagents
  • halter-providers — provider adapters and model registry
  • halter-tools — tool runtime, built-in tools, policy, subagent control tools
  • halter-hooks — event-driven hook and policy interception layer
  • halter-session — session persistence and replay

halter-config

halter-config defines the schema for:

  • providers
  • model roles (default, small, subagent), with default and subagent optionally backed by an experimental "model_judge" panel via [models.model_judge]
  • resource roots
  • prompts (a built-in preset plus a full system_prompt override)
  • context compaction settings
  • tool enablement
  • policy
  • network access
  • session persistence
  • runtime settings

It also handles:

  • file loading
  • environment overrides
  • layered merges
  • JSON Schema export
  • starter config generation

halter provides convenience functionality for consuming .toml config files where that makes sense operationally.

Note

.toml config file usage is a thin serialization veneer over the programmatic config. For full customization programmatic configuration should be used, and probably preferred in headless, automated, or dynamic environments.

Credentials and overrides

When using config files, halter resolves the effective config first, then resolves provider credentials.

Config value hierarchy:

  1. Built-in defaults.
  2. Layered config files, when using load_layered: user config, then project config, then the explicit config path. Later files replace earlier values, except skill and plugin root arrays append and dedupe.
  3. Supported HALTER_* environment overrides, such as HALTER_TOOLS_ENABLED or HALTER_POLICY_SHELL_ENABLED. These are applied after file loading, so they win over file values.

Provider credential hierarchy:

  1. [providers.<name>].api_key in the effective config wins when it is present and non-empty.
  2. For OpenAI only, [providers.openai].oauth may be configured instead of api_key. It must include client_id, access_token, id_token, and refresh_token; the provider sends access_token as the bearer token. OAuth traffic for /v1/responses, every path below that prefix, and /chat/completions rewrites to https://chatgpt.com/backend-api/codex/responses, so base_url is ignored for those paths. OAuth requests send the assembled system prompt as top-level instructions, omit the developer/system input item, and set store to false.
  3. If no explicit credential is configured, halter reads the provider-specific process environment variable: OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY.
  4. If no credential source is available for a selected provider, config loading fails.

OpenAI api_key and oauth config are mutually exclusive. If both are present in [providers.openai], validation fails.

OAuth config uses this shape:

[providers.openai.oauth]
client_id = "..."
access_token = "..."
id_token = "..."
refresh_token = "..."

Halter reads process environment variables. It does not parse .env files directly; if you use a .env file, load it into the process environment before starting the CLI or SDK process.

OpenRouter serves most models from several upstream providers and picks one per request. [providers.openrouter.routing] states which upstream to prefer; it is sent as the provider object of every OpenRouter request body, including compaction requests:

[providers.openrouter.routing]
# Most preferred upstream first. Slugs are OpenRouter's, not halter's.
order = ["anthropic", "google-vertex"]
# Omit to let OpenRouter fall back to any other upstream (its default).
# Set false to make `order` an exact allowlist: the request fails instead of
# routing elsewhere.
allow_fallbacks = false

routing is only accepted for [providers.openrouter]. Its order must name at least one upstream provider and its slugs must be non-empty and distinct; slugs are trimmed. allow_fallbacks alone is not a preference, because true is already OpenRouter's default and false would permit nothing. The same rules apply to a value handed straight to OpenRouterProvider, so nothing unchecked reaches a request body.

Provider request resilience is configured globally under [resilience] and can be partially overridden per provider. The same retry policy applies uniformly to Anthropic, OpenAI, and OpenRouter, and covers both streaming turns and compaction requests. Only failures classified retryable (rate limits, 5xx/overload, network faults) are retried — deterministic failures such as invalid requests fail immediately — and server-supplied backoff hints (Retry-After, "try again in …") are honored. Retry jitter is applied within max_backoff_secs; a computed delay never exceeds it. For streaming calls, request_secs bounds request setup through response headers and stream_idle_secs bounds the idle gap between stream items; it is not a total stream lifetime cap. Once a stream has emitted content, that request is never retried. max_attempts includes the initial request:

[resilience.timeouts]
connect_secs = 10
request_secs = 60
stream_idle_secs = 60

[resilience.request_retry]
max_attempts = 5
deadline_secs = 60
base_backoff_ms = 500
max_backoff_secs = 30
jitter_pct = 25

[providers.openrouter.resilience.request_retry]
max_attempts = 3

SDK users can override the effective provider policy for all configured providers with HalterBuilder::with_resilience_policy(...).

Disk resource parsing

ResourceCompiler::from_config(&config).compile() loads disk resources from [resources.skills].roots and [resources.plugins].roots. Halter::from_config_file(...) uses this path automatically.

Resource root paths expand a leading ~/ through $HOME. Other shell-style substitutions, such as $VAR, ${VAR}, and ~user, are not expanded. Missing resource roots are skipped.

Standalone skills are discovered recursively under each skill root:

  1. Each directory is scanned for child directories.
  2. A child directory containing SKILL.md is loaded as one skill.
  3. If a child directory does not contain SKILL.md, scanning continues inside it.

SKILL.md frontmatter is intentionally small. If the file starts with ---, halter reads key: value lines until the next ---. The loader currently uses name and description; missing name falls back to the directory name, and missing description becomes an empty string. The compiled snapshot stores the skill id, name, description, and full SKILL.md body. Files under a skill's immediate scripts/ directory are recorded on the loaded skill, but arbitrary supporting files are not loaded into the compiled snapshot today.

Skills load progressively. The system prompt lists each skill as - name: description under a # Skills heading, and bodies stay out of it. When the snapshot holds any skills, every request also offers a runtime-owned skill tool. When the model calls it with a skill name, the tool result is only an acknowledgement. The body, with its frontmatter stripped, is wrapped in <skill name="..."> with the skill's base directory. It is appended as a user message after all of that step's tool results, so the cached prefix is unchanged when a skill loads. The index and the tool both come from the live resource snapshot, so replace_resources adds or removes skills for later requests. With no skills, neither appears. tools.enabled does not control skill, and the builder rejects custom or strategy tools with that reserved name.

Note

Halter attempts to replicate Codex and Claude Code behavior when parsing plugins for all supported functionality. Right now this is a moving target, so minor bugs and differences may manifest. File an issue or PR to fix any inconsistencies.

Plugins are discovered one level below each plugin root. Each child directory is treated as a plugin only if it contains a manifest at one of these paths, checked in order:

  1. .codex-plugin/plugin.json
  2. .claude-plugin/plugin.json
  3. .agent-plugin/plugin.json
  4. plugin.json

The manifest must include non-empty string fields name and version. Optional manifest fields include skills, agents, hooks, mcpServers, lspServers, allowedHttpHosts, and allowedEnvVars. skills and agents may be a string path or an array of string paths. Skill and agent entries must be paths relative to the plugin root and must start with ./, unless they use a plugin alias. Supported aliases are ${CLAUDE_PLUGIN_ROOT}, ${PLUGIN_ROOT}, ${CLAUDE_PLUGIN_DATA}, and ${PLUGIN_DATA}. ${PLUGIN_ROOT} resolves to the enclosing plugin root (or the skill's own root for standalone skills), and ${PLUGIN_DATA} resolves to <root>/.data. These aliases are also rendered inside skill (SKILL.md) bodies and agent prompt files at load time. Parent-directory traversal is rejected, and resolved paths must stay inside the plugin root.

Plugin skills entries can point at a single skill directory containing SKILL.md or at a directory tree that should be searched recursively for skills. Plugin agents entries can point at one prompt file or a directory of prompt files; each file becomes an agent named after its file stem. Hooks are loaded from the manifest's hooks path, or from hooks/hooks.json when the manifest omits hooks. Hook parse failures are retained as hook warnings instead of aborting the whole resource compile. Command hooks with "shell": "bash" (the default) run in the same detected shell as the shell tool, as a login shell (-lc) when that is bash or zsh so profile PATH setup applies, and with -c for plain sh. "shell": "pwsh" runs pwsh -Command. Unlike the shell tool, command hooks inherit the full environment of the halter process, credentials included, plus hook variables such as PLUGIN_ROOT and SESSION_ID; see crates/halter-hooks/README.md.

Compiled resources use stable identifiers. Skill ids are based on the canonical skill path, plugin ids are based on plugin name, version, and canonical plugin path, and the final resource snapshot revision is a SHA-256 of the serialised snapshot plus hook file revisions, so any change to a stored field yields a new revision. Session stores key persisted snapshots by that revision. Skill bodies and agent prompts are rendered before hashing, so changing an alias expansion (e.g., loading the same plugin through a different absolute root) produces a different snapshot revision.

Bundled agent plugins

The repository ships a bundled plugin set under halter-agent-plugins/. Today it contains one plugin, halter-rust (0.1.0), described as "Rust engineering guidance for Halter." That plugin carries two skills: basic-rust and workflows-rust.

The two bundled skills cover different layers of using the halter SDK:

  • basic-rust — use when building, explaining, testing, or modifying Rust agent harnesses with the Halter library. It covers config-driven runners, the SDK builder, custom tools, hooks, policy, persistence, providers, subagents, and workspace Rust changes.
  • workflows-rust — use when building scripted, deterministic multi-agent workflows in Rust on top of the Halter SDK, such as fan-out/fan-in, staged pipelines, adversarial verification, judge panels, loop-until-budget loops, structured agent output, concurrency control, and resumable orchestration. It pairs with basic-rust, which covers harness construction.

To load the bundled plugin, add its plugin directory to your plugin roots. For example, with a config file:

[resources.plugins]
roots = ["./halter-agent-plugins/plugins"]

Remote GitHub plugins

The halter-config crate has an opt-in remote-plugins feature for SDKs that want to fetch GitHub-hosted plugins without installing them to a local cache. These plugins are downloaded and made available to the harness dynamically and purely in memory. At the moment only skills and agents are supported, commands and hooks are on the roadmap but are not currently planned. It returns the same LoadedPlugin values that ResourceCompiler::with_loaded_plugins(...) already accepts:

use halter::HalterBuilder;
use halter_config::github::{GithubPlugins, load_plugins};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let plugins = load_plugins([
        GithubPlugins::plugin("https://github.com/acme/rust-tools")?,
        GithubPlugins::marketplace("https://github.com/acme/agent-marketplace")?
            .only(["pairs-review", "sql-guard"]),
    ])
    .await?;

    let harness = HalterBuilder::new()
        .with_loaded_plugins(plugins)
        .build()
        .await?;

    Ok(())
}

Remote marketplace loading checks .agents/plugins/marketplace.json first and falls back to .claude-plugin/marketplace.json. Remote plugin directories check .codex-plugin/plugin.json first and falls back to .claude-plugin/plugin.json. If neither manifest exists, loading fails.

Config File Example (non-exhaustive)

version = 1

[models.default]
provider = "openai"
model = "gpt-5"
reasoning = "medium"

[models.small]
provider = "openai"
model = "gpt-5-mini"
reasoning = "low"

[models.subagent]
provider = "openai"
model = "gpt-5-mini"
reasoning = "medium"

[prompts]
preset = "general"   # "general" (default) | "coding"; system_prompt overrides either
# append_system_prompt = "stable extra instructions appended after the base prompt"

[resources.skills]
roots = ["./.agent/skills"]

[resources.plugins]
roots = ["./.agent/plugins"]

[tools]
enabled = [
  "read",
  "glob",
  "grep",
  "write",
  "edit",
  "shell",
  "process",
  "task",
  "wait_agent",
  "spawn_agent",
  "send_input",
  "close_agent",
]
# Largest tool result, in bytes of model-visible text, committed whole. Larger
# results keep their head and tail; the full text is written to
# <output_dir>/<sanitized session id>/<message id>.txt. 0 disables the bound.
max_output_bytes = 51200
# Default: halter-<user>/tool-output under the system temp dir, which the read
# tools reach by default. Anywhere else must be under [policy] allowed_read_roots.
# output_dir = "/tmp/halter-me/tool-output"

[context]
# Thresholds are optional. Unset, compaction_threshold is
# models.default.max_input_tokens minus 20_000 and max_tokens (a hard cap that
# fails the turn) is max_input_tokens itself.
compaction_threshold = 200_000
# max_tokens = 260_000
# "model_summary" (default): the model writes a context checkpoint and the next
# window starts from it. "provider_default": the provider's native compaction.
# "clean_window": recover through notes, task, and session_search after a wipe.
compaction = "model_summary"
# notes_root = "~/.local/share/halter/notes" # optional, for clean_window
# Without it, notes sit in a `notes` dir beside the sqlite database (the
# default one too). Memory sessions and custom stores get the temp dir, so a
# custom durable store should set notes_root.

[policy]
allowed_write_roots = ["./"]
# Optional. Empty keeps the built-in read roots (working directory + temp
# directory); an explicit list replaces them. Write roots stay readable either way.
# allowed_read_roots = ["/srv/checkouts"]
# Optional. Absent keeps the built-in globs denied to every file tool; an
# explicit list replaces them and `[]` disables the check entirely.
# sensitive_path_patterns = ["**/.ssh/**", "**/.aws/**", "**/.secrets", "/etc/shadow", "/etc/shadow.*"]
max_read_bytes = 1048576
max_subagent_depth = 3
max_concurrent_subagents = 8

[policy.network]
enabled = false
allowed_hosts = []

[policy.shell]
enabled = true
timeout_secs = 30

[sessions]
backend = "memory"

[runtime]
# Optional. When set, halter writes a `<session_id>.txt` JSONL trace per session
# into this directory: one header line followed by every committed SessionEvent,
# tailed live as the session runs (plus pre-commit `pending_event` preview lines).
# A resumed session keeps appending to the same file, and so do its restored
# subagents.
# The same committed-line view is always available after the fact from the
# session store via `session.export_trace()`, with or without this setting.
# traces_dir = "/tmp/halter/traces"

# Optional. Keep off unless the caller wants the parent session stream to include
# raw events from subagents spawned under that parent.
# subagent_event_forwarding = "off"
# subagent_event_forwarding = "all"
# subagent_event_forwarding_cap = 100_000 # 0 = unbounded

reasoning accepts none, minimal, low, medium, high, xhigh, and max. Provider/model support varies; Halter preserves explicit OpenAI-compatible values and maps them to the nearest supported Anthropic thinking mode where necessary.

Model Judge

Warning

This feature is very experimental and there is a good chance it goes away, do not rely on this.

The models.default and models.subagent slots accept either an inline model (the form above) or the string "model_judge", which references a shared [models.model_judge] block. A model-judge slot deliberates over a panel of models, judges their work with a synthesis model, and hands the result to the default model as advisory guidance — the default model always owns the visible answer and all real tool execution.

The mode field picks how deeply each panelist deliberates:

mode = "one_shot" (default). Each panelist answers with a single message (one inference, no tools), and the whole cycle runs on every model call within a turn:

  1. The context and user message are multiplexed to every model in panel in parallel (each receives the full context and the tool specs). A constant framing prefix is prepended as the first user message so each panelist answers as one advisory voice on a judged panel — comparable prose about what it would do and why, rather than executing or replying. The prefix is added only on the panel path, so it never reaches the synthesis or default model.
  2. The synthesis model is given the panel responses and a rank_responses tool. It first stack-ranks the responses (emitted as structured tracing telemetry), then writes a synthesis that judges, not merges, them (strengths, weaknesses, pros, cons, overall).
  3. The synthesis is handed to the default model as internal guidance for the same provider call; the guidance is not persisted to the transcript.

Cheap and fast — a fresh second opinion at each step. Expect N + 2 model calls per iteration.

mode = "full_turn". Each panelist runs a complete agentic turn (inference + tool loop to completion) on the user's message, once per turn. The synthesis model judges the outcomes of those turns (using the same rank_responses + judge flow), and the synthesis is injected as advisory guidance on the default model's opening inference of the turn. The default model then runs its own full turn, owning the real, user-visible execution. Heavier, but each panelist actually investigates the task rather than only describing what it would do. Panelists are advisory — their work is scratch exploration that feeds the judge, not the shipped result. Each panelist turn is stored as a child session of the parent. The synthesis reply and the guidance built from it go into the parent's log as MessageRecorded (logged, not part of the transcript), and the synthesis usage counts toward the parent's turn.

panel_isolation controls how FullTurn panelist sub-sessions are sandboxed (ignored under one_shot):

  • read_only (default) — panelists share the working directory but get a tool set with every mutating tool (write/edit/shell/process/task) filtered out. Safe under concurrency.
  • shared_full — panelists share the working directory with the full tool set. Maximum fidelity, but concurrent panelists can clobber each other's writes.
  • worktree — each panelist runs in its own git worktree with the full tool set, so it can mutate freely without colliding. Requires a git repository; falls back to shared_full (with a warning) otherwise.
[models]
default = "model_judge"
subagent = "model_judge"   # optional; subagents can fan out too

[models.model_judge]
mode = "one_shot"            # "one_shot" (default) | "full_turn"
panel_isolation = "read_only"  # full_turn only: "read_only" (default) | "shared_full" | "worktree"

[models.model_judge.default]
provider = "anthropic"
model = "claude-opus-4-8"
reasoning = "high"

[models.model_judge.synthesis]
provider = "openai"
model = "gpt-5"
reasoning = "high"

[[models.model_judge.panel]]
provider = "openai"
model = "gpt-5"

[[models.model_judge.panel]]
provider = "openrouter"
model = "z-ai/glm-5.1"

[[models.model_judge.panel]]
provider = "anthropic"
model = "claude-sonnet-4-6"

Rankings, panel responses/outcomes, and the synthesis message are all logged via tracing (target halter::model_judge); set RUST_LOG=halter::model_judge=info to capture the quality telemetry.

Programmatic Example (non-exhaustive)

use std::path::PathBuf;
use std::sync::Arc;

use halter::session::InMemorySessionStore;
use halter::{HalterBuilder, LoadedSkill};
use halter_config::{
    CompactionStrategyKind, ConfiguredProvider, ContextConfig, HarnessConfig, ModelConfig,
    ModelsConfig, NetworkPolicyConfig, PolicyConfig, PromptsConfig, ProviderConfig,
    ProvidersConfig, ResourcesConfig, RuntimeConfig, SearchRoots, SessionBackend,
    SessionsConfig, ShellPolicyConfig, ToolsConfig,
};
use futures::StreamExt;
use halter::prelude::*;
use halter_protocol::{ReasoningEffort, SkillId};

use halter_runtime::SessionInit;

const SYSTEM_PROMPT: &str =
    "You are a careful local coding agent. Prefer concrete, verifiable answers.";
const REPO_REVIEW_SKILL: &str = r#"When asked to review a codebase:
1. Start with correctness risks.
2. Then call out maintainability issues.
3. End with the smallest high-leverage next steps.
"#;

fn build_config() -> anyhow::Result<HarnessConfig> {
    let working_dir = std::env::current_dir()?;
    let temp_write_root = std::env::temp_dir().join("halter");

    Ok(HarnessConfig {
        version: 1,
        providers: ProvidersConfig {
            openai: Some(ProviderConfig {
                base_url: Some("https://api.openai.com".to_owned()),
                api_key: Some(std::env::var("OPENAI_API_KEY")?),
                ..ProviderConfig::default()
            }),
            anthropic: None,
            openrouter: None,
        },
        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::High),
                tokens_per_minute: Some(500_000),
            }),
            small: Some(ModelConfig {
                provider: ConfiguredProvider::OpenAi,
                model: "gpt-5-mini".to_owned(),
                max_input_tokens: Some(200_000),
                max_output_tokens: Some(4_096),
                reasoning: Some(ReasoningEffort::Low),
                tokens_per_minute: Some(1_000_000),
            }),
            subagent: Some(ModelConfig {
                provider: ConfiguredProvider::OpenAi,
                model: "gpt-5-mini".to_owned(),
                max_input_tokens: Some(200_000),
                max_output_tokens: Some(4_096),
                reasoning: Some(ReasoningEffort::Medium),
                tokens_per_minute: Some(750_000),
            }),
        },
        resources: ResourcesConfig {
            skills: SearchRoots { roots: Vec::new() },
            plugins: SearchRoots { roots: Vec::new() },
        },
        prompts: PromptsConfig {
            system_prompt: Some(SYSTEM_PROMPT.to_owned()),
            ..PromptsConfig::default()
        },
        context: ContextConfig {
            compaction_threshold: Some(200_000),
            max_tokens: None,
            compaction: CompactionStrategyKind::ModelSummary,
            notes_root: None,
        },
        tools: ToolsConfig {
            enabled: vec![
                "read".to_owned(),
                "glob".to_owned(),
                "grep".to_owned(),
                "write".to_owned(),
                "edit".to_owned(),
                "shell".to_owned(),
                "process".to_owned(),
                "spawn_agent".to_owned(),
                "send_input".to_owned(),
                "wait_agent".to_owned(),
                "close_agent".to_owned(),
            ],
        },
        policy: PolicyConfig {
            allowed_write_roots: vec![working_dir.clone(), temp_write_root],
            max_read_bytes: 1_048_576,
            max_subagent_depth: 3,
            max_concurrent_subagents: 8,
            shell: ShellPolicyConfig {
                enabled: true,
                allow: vec![
                    "git".to_owned(),
                    "cargo".to_owned(),
                    "rg".to_owned(),
                    "ls".to_owned(),
                    "find".to_owned(),
                    "python".to_owned(),
                    "pwd".to_owned(),
                    "echo".to_owned(),
                ],
                timeout_secs: 30,
            },
            network: NetworkPolicyConfig {
                enabled: false,
                allowed_hosts: Vec::new(),
                allowed_loopback: Vec::new(),
            },
        },
        sessions: SessionsConfig {
            backend: SessionBackend::Memory,
            sqlite_path: None,
        },
        runtime: RuntimeConfig {
            working_dir: Some(working_dir),
            ..RuntimeConfig::default()
        },
    })
}

fn inline_skills() -> Vec<LoadedSkill> {
    vec![LoadedSkill {
        id: SkillId::from("repo-review"),
        name: "repo-review".to_owned(),
        description: "Review a repository for correctness, maintainability, and next steps."
            .to_owned(),
        root: PathBuf::from("inline-skills/repo-review"),
        body: REPO_REVIEW_SKILL.to_owned(),
        supporting_files: Vec::new(),
        scripts: Vec::new(),
        revision: "repo-review-v1".to_owned(),
    }]
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let harness = HalterBuilder::new()
        .with_config(build_config()?)
        .with_loaded_skills(inline_skills())
        .with_session_store(Arc::new(InMemorySessionStore::default()))
        .build()
        .await?;

    let (session, mut events) = harness.new_session(SessionInit::default()).await?;
    let listener = tokio::spawn(async move {
        while let Some(event) = events.next().await {
            println!("{:?}", event?.payload);
        }
        Ok::<(), anyhow::Error>(())
    });

    session.submit(Message::user("Describe the active runtime and available skills")).await?;
    tokio::signal::ctrl_c().await?;
    session.shutdown(None).await?;
    listener.await??;

    Ok(())
}

To use OpenAI OAuth in programmatic config, set oauth instead of api_key:

use halter_config::{OpenAiOAuthConfig, ProviderConfig};

ProviderConfig {
    oauth: Some(OpenAiOAuthConfig {
        client_id,
        access_token,
        id_token,
        refresh_token,
    }),
    ..ProviderConfig::default()
}

halter-protocol

halter-protocol defines the shared vocabulary used by the rest of the workspace.

That includes types for:

  • turns
  • messages
  • session events
  • tool calls and tool results
  • resources and compiled artifacts
  • provider-facing request/response chunks

If you are building integrations or parsing structured output, this crate matters a lot.

halter-providers

halter-providers adapts concrete model backends into halter's normalized provider interface.

Built-in providers include:

  • OpenAI
  • Anthropic
  • OpenRouter
  • Fake/test provider
  • Unsupported placeholder for builds where a transport is not wired in

Important operational differences:

  • OpenAI supports streaming, prompt caching, and dedicated Responses compaction
  • OpenRouter supports streaming, prompt caching, and inline Responses compaction
  • Anthropic supports streaming, prompt caching, interleaved thinking, and inline Messages compaction
  • capability differences are explicit and should be handled intentionally

halter-tools

Note

Many of the original ideas (and code) in this crate are taken from other FOSS projects, namely pi-mono and oh-my-pi's native Rust tool.

Built-in tools include:

  • read
  • glob
  • grep
  • write
  • edit
  • shell
  • process
  • task (todo list scoped to the session; rebuilt from the session log on resume)

Optional feature-gated tools include:

  • pty
  • ast_grep
  • image
  • browser
  • profile

Subagent tools include:

  • spawn_agent
  • send_input
  • wait_agent
  • close_agent

This crate also enforces policy boundaries such as:

  • the shell on/off switch
  • write-root restrictions
  • network host and loopback restrictions
  • read/output size limits
  • subagent depth and concurrency limits

halter-hooks

halter-hooks lets you observe and influence runtime behavior by reacting to lifecycle events.

Hooks can:

  • approve or block actions
  • request or deny permissions
  • add system messages
  • attach additional context
  • rewrite inputs and outputs
  • suppress output visibility
  • stop execution

Example

use halter::HalterBuilder;
use halter_hooks::{Hook, HookEventName, HookResponse, RegisteredHookPriority};
use halter_protocol::PluginId;

let hook = Hook::callback(HookEventName::PreToolUse, |input| async move {
    if input.tool_name() == Some("shell") {
        Ok(HookResponse::passthrough().with_system_message(
            "Shell usage was requested; verify the command is minimal and necessary.",
        ))
    } else {
        Ok(HookResponse::passthrough())
    }
});

let _builder = HalterBuilder::new()
    .with_plugin_hook_priority(
        PluginId::from("example-tool-id"),
        RegisteredHookPriority::BeforePlugins,
        hook,
    );

halter-session

halter-session provides persistence and replay.

Sessions are stored log-first: every committed SessionEvent lands in an append-only, per-session sequenced log, and the persisted SessionState is a checkpoint of that log stamped with the sequence it reflects. Loaders fold any log tail past the checkpoint back onto it (halter::session::fold), the store's optimistic concurrency is an expected-head-sequence check, and session.export_trace() serializes the log (including subagent sessions) in the trace-file format — no traces_dir required.

Built-in backends:

  • InMemorySessionStore
  • SqliteSessionStore (behind the sqlite feature)

Use memory for:

  • tests
  • ephemeral local runs
  • simplest setup

Use SQLite for:

  • resumable local agents
  • durable transcripts
  • replay after process restart

halter-runtime

halter-runtime executes sessions.

It owns:

  • session lifecycle
  • prompt assembly
  • context management and compaction
  • event publication
  • hook dispatch
  • tool execution orchestration
  • subagent lineage and coordination
  • session replay/resume

The SDK returns a cloneable SessionHandle and one continuous SessionEventStream. HalterSession aliases this handle in the SDK prelude. Internal execution IDs remain in diagnostic events; clients submit messages and control the session.

Input, interruption, and reopening

submit(Message::user(...)).await returns a submission receipt after the session store has committed the input. While idle, submission starts execution. While a provider or foreground tool is running, input queues and is delivered at the next safe conversation boundary. A MessageItem event confirms delivery into history. Acceptance is durable only as far as the configured store: use SQLite for recovery after process exit. An in-memory store lasts only as long as the process.

let (session, mut events) = harness.new_session(SessionInit::default()).await?;
let session_id = session.id().clone();
session.submit(Message::user("Refactor the parser")).await?;
session.submit(Message::user("Keep its public API unchanged")).await?;
session.interrupt(None).await?;
session.shutdown(None).await?;

// A fresh driver starts idle with the stored conversation and pending input.
let (session, events) = harness.resume_session(&session_id).await?;
session.submit(Message::user("Continue with the parser tests")).await?;

interrupt(None) waits for cancellation, foreground-tool cleanup, and final state commits. Earlier accepted input remains recorded but does not restart execution until a later submission. Cancellation cannot undo effects already performed by a tool. Custom tools must honor the cancellation token and clean up their resources.

shutdown(None) closes the driver, its handles, and its stream, and cleans up owned resources. The stored conversation can be reopened; old handles stay closed. Reopening restores history and pending input without rerunning tools or launching old processes. Dropping an event stream does not stop execution.

Keep a session handle to submit more input across idle periods. Dropping its last clone releases the driver after foreground work, runnable queued input, background jobs, and subagents finish. Active work continues normally. Event streams and status receivers do not retain the driver. Release runs cleanup and the SessionEnd hook with reason session_released; history and deferred input remain available for resume.

Release also closes child agents, including completed ones. After reopening the parent, spawn new child agents; the previous children's conversations remain stored and can be reopened separately by session ID.

A persistent PTY, shell job such as sleep infinity &, or managed background process can keep a session open indefinitely after its last handle is dropped. Retain a handle when you need to stop that work explicitly. Otherwise, runtime shutdown is the remaining way to close it.

The stream stays open through idle periods and interruptions. Read session.status() for current foreground activity or use session.subscribe_status() to watch Running, Idle, and Closed. This status belongs to the live handle and is not persisted in the log. A watch receiver starts with the current value and may coalesce changes. An idle session may still own background processes. Provider deltas and tool output retain their existing buffering behavior.

When a live stream closes cleanly, it emits one transient SessionStatusChanged { status: Closed } after its final committed event, then ends. This notification has sequence zero and does not appear in replay.

let mut activity = session.subscribe_status();
loop {
    let current = *activity.borrow_and_update();
    println!("session activity: {current:?}");
    if current == SessionStatus::Closed || activity.changed().await.is_err() {
        break;
    }
}

submit returns Submission { message_id, sequence } after acceptance commits. InputDelivered records when accepted input enters conversation history. InputRejected records removal without delivery; InputDeferred records input that remains queued. These events describe what happened to the input, without promising a final reply or completion of background work. Several steering messages can influence the same foreground execution.

An input deferred with ExecutionFailed requires an explicit same-ID retry; unrelated new messages skip it. ExecutionStopped marks untouched followers, which remain eligible when a later submission starts foreground work.

When retrying a queued message with the same ID, the receipt identifies its fresh InputAccepted sequence. Ignore earlier events on a retained stream. Retry preserves the original contents and does not duplicate the inbox entry. Submitting an already delivered or rejected ID starts no new work; read its records with replay(). To remove queued input, call session.discard(&message_id) while idle. It records InputRejected and returns whether an entry was removed. Use interrupt(None) first if foreground work is active. Retained deferred entries count toward inbox capacity; discarding unwanted input releases its slot. Pass Some(duration) to interrupt or shutdown to set a cooperative cleanup deadline; None waits without a deadline. Expiry returns SessionError::TimedOut and requests forced recovery. Call the control method again with None to await settlement. In-flight storage writes or blocking code may delay settlement; a shutting-down session stays fenced until cleanup finishes.

Note

halter implements its own compaction strategy. This can be less token efficient than managed compaction from inference providers or frontier harnesses. The goal is a higher-quality context window, which can reduce overall token use throughout the turn and gives halter a consistent baseline across providers and models.

Compaction

The runtime decides when to compact; a compaction strategy decides what happens.

  • Every session keeps a token ledger (SessionState::token_ledger): the last completed response's provider-reported context size plus inferred transcript growth and the current request base (system/skill/hook prompt segments and tool declarations). Media-only messages have a non-zero estimate. Each usable report replaces the transcript anchor; compaction and legacy snapshots safely rebuild it.
  • Compaction has two trigger points, both Halter-side: immediately after an assistant response that requested no tools, and before every provider request once the appends since the last one (user message, tool results, hook messages) have landed. A tool call is never separated from its result. Server-side auto-compaction is never used; a strategy must not enable a provider's own.
  • context.compaction_threshold defaults to models.default.max_input_tokens minus 20,000; one of the two must be set or loading the config and building the harness fail. context.max_tokens (default max_input_tokens) is a hard cap checked before each provider request, after compaction has had its chance: a turn that would exceed it fails with halter::compaction::ContextCapExceeded instead of blowing the provider window.
  • Automatic compaction is best-effort: a strategy that cannot run degrades the turn to an uncompacted context with a Warning event, and the turn does not try again until the ledger has grown by half the threshold, so a refused request is not resent at every boundary. session.compact(..) propagates failures. PreCompact/PostCompact hooks fire on both paths, with trigger auto for the automatic one. PostCompact fires only after a compaction replaced the context, and a pass the strategy rules out up front (CompactionStrategy::needs_compaction) fires neither hook.
  • context.compaction picks the strategy. "model_summary" (the default) asks the session's own model for a context checkpoint: when the task tool is registered it first nudges the model to persist its remaining work there (only task calls from that reply run; nothing else reaches the next request), then sends the built-in checkpoint instructions, and the reply becomes the next window as a single user-role message after the static prefix. No tail of old messages is kept, which is also the one client-side shape that survives preserved-thinking checks. "provider_default" delegates the rewrite to the provider's native compaction (OpenAI's /v1/responses/compact; inline summarization requests for Anthropic and OpenRouter), and the harness fails to build if the default model's provider cannot compact. Either way the trigger is Halter's ledger, never the provider's own auto-compaction.
  • Install your own strategy with HalterBuilder::with_compaction(...); it may also contribute tools and system-prompt segments, and its context_boundary hook can deliver exactly-once, per-window reminders as the context fills. The runtime alone decides when compaction runs. A strategy can drive the model and tools through the CompactionContext the runtime hands it; if its pass fails, the window goes back to what it was while everything the pass did stays in the event log.
use std::sync::Arc;

use halter::HalterBuilder;
use halter::compaction::{
    CompactionContext, CompactionEffects, CompactionStrategy, CompactionTrigger,
};
use halter_protocol::{ProviderCapabilities, SessionState};

struct KeepEverything;

#[async_trait::async_trait]
impl CompactionStrategy for KeepEverything {
    // Asked before any hook. `false` skips the pass: no `PreCompact`, no
    // `compact` call, no `PostCompact`. The default is `true`.
    fn needs_compaction(
        &self,
        state: &SessionState,
        _capabilities: &ProviderCapabilities,
        _trigger: CompactionTrigger<'_>,
    ) -> bool {
        !state.messages.is_empty()
    }

    async fn compact(
        &self,
        ctx: CompactionContext<'_>,
    ) -> anyhow::Result<Option<CompactionEffects>> {
        // `ctx.state()` (messages, `token_ledger`), `ctx.prompt_segments()`,
        // `ctx.tool_specs()`, `ctx.model()`, and `ctx.provider()` are readable.
        // `Ok(None)` means there was nothing to compact after all:
        // `PreCompact` has fired, `PostCompact` will not.
        let _ = ctx;
        Ok(None)
    }
}

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

Security model

Halter does its best to operate in a sane and safe way, but does not provide hard security boundaries. Run sensitive workloads in fully sandboxed environments with defense in depth beyond process-level safeguards.

Tool boundaries

Enforced mechanically, best effort, by tool policy:

  • where writes may occur
  • whether the shell tool may run at all (there is no per-command allowlist)
  • which network hosts may be reached; loopback requires a separate allowlist
  • how much can be read or emitted
  • how many subagents may be active
  • how deep delegation may go

Semantic/runtime boundaries

The following can all be implemented in custom hooks:

  • approvals
  • denials
  • stop conditions
  • input/output rewriting
  • extra context or warnings
  • audit annotations

Observability

Halter's library crates emit tracing events and spans only. None of them installs a subscriber. To get output, either install halter's default subscriber through the opt-in telemetry feature or bring your own.

halter = { version = "0.9", features = ["telemetry"] }
use halter::telemetry::{LogFormat, TelemetryConfig};

// Reads RUST_LOG (default `warn`), applies the noisy-target suppression,
// and writes compact lines to stderr.
TelemetryConfig::new().try_init()?;

// Or JSON, with explicit directives instead of RUST_LOG:
// TelemetryConfig::new().with_format(LogFormat::Json).with_directives("info").try_init()?;

TelemetryConfig::try_init_with(layer) adds one extra layer (for example an exporter) to the same stack. The composed EnvFilter filters the whole stack in that case. If the extra layer needs its own filter, compose the pieces yourself. env_filter() and fmt_layer() build the parts without installing anything:

use halter::telemetry::TelemetryConfig;
use halter::telemetry::tracing_subscriber::{self, EnvFilter, Layer, layer::SubscriberExt};

let config = TelemetryConfig::new();
let exporter = tracing_subscriber::fmt::layer() // stand-in for any extra layer
    .with_filter(EnvFilter::try_new("halter_runtime=info,halter_providers=info")?);
let subscriber = tracing_subscriber::registry()
    .with(exporter)
    .with(config.fmt_layer().with_filter(config.env_filter()?));
tracing::subscriber::set_global_default(subscriber)?;

To use your own subscriber, leave the feature off and install it as usual. With the feature on, halter::telemetry::compose_directives gives you halter's suppression list for your own filter.

CLI. halter uses this helper. It reads RUST_LOG, defaults to warn, and quiets per-token shell parser and HTTP connection-pool targets (tokenize, parse, hyper, reqwest, h2, ...) even under RUST_LOG=debug. An explicit per-target directive such as RUST_LOG=hyper=trace still wins. Logs go to stderr: compact by default, JSON when --output-file is set.

Spans

Span names are the stable contract; identifiers are fields. Each field is recorded at most once: the compact formatter repeats a re-recorded field on every line, so totals (tokens, provider_iterations, attempt) are recorded when the operation ends. All spans except hook_dispatch are info level, so RUST_LOG=info (or halter_runtime=info,halter_providers=info) enables them.

Span Target Fields at creation Fields recorded later
turn halter_runtime session_id, turn_id provider, model, model_id (at the first provider request; fixed for the turn), provider_iterations, input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens, outcome (completed/failed/cancelled/aborted)
tool_call halter_runtime session_id, turn_id, tool_name, tool_call_id outcome (ok/error/blocked/aborted), is_error
provider_request halter_providers provider, provider_kind, model, model_id, session_id, turn_id attempt (final attempt number), outcome (completed/error/cancelled), error_kind
provider_compaction halter_providers provider, provider_kind, model, model_id, session_id attempt, outcome, error_kind
subagent halter_runtime agent_id, session_id, parent_session_id, agent_type, generation outcome (completed/failed/cancelled/aborted/...)
hook_dispatch halter_runtime event (debug level) matched_handlers

aborted means the operation ended without reporting a result: its task was aborted (for example by shutdown or close_agent), its future was dropped, or it panicked. Runtime spans always close with an outcome.

tool_call and provider_request nest under turn. provider_request comes from ResilientProvider, which wraps every built-in provider. Custom Provider implementations get no provider span unless they add one.

A subagent span is a root span. It links to the span that started it with follows_from (an OpenTelemetry span link) and shares parent_session_id for correlation. Subagents outlive the tool call that spawns them, and a child span would keep the parent turn and tool_call open. The subagent's own turn spans nest under subagent.

Conventions

  • Targets are the default module paths (halter_runtime::session, ...). Don't invent custom targets.
  • Levels: error/warn for actionable problems; info for lifecycle and policy outcomes; debug for details and decisions; trace for payloads.
  • Field names: session_id, turn_id, parent_session_id, agent_id, tool_name, tool_call_id, provider (configured provider name), provider_kind (adapter label such as anthropic/openai/openrouter), model (upstream model), model_id (halter model id), attempt, outcome, error_kind, and the Usage token names.
  • Use structured fields instead of values interpolated into the message.
  • Never log secrets, full tool inputs, prompts, or hook payloads at info or above. Never put payloads in span fields: the JSON format repeats span fields on every line.
  • Async: instrument futures with .instrument(span) or .in_current_span(). Never hold an Entered guard across .await. Tasks that are part of the current operation carry its span. Detached or long-lived tasks use parent: None plus follows_from.
  • Token usage is recorded only on turn, so span-derived metrics never double count.
  • Hooks: halter-hooks emits hooks.matched (debug) when handlers match and hooks.decision after merging. Decisions that block, stop, deny, or ask log at info; others at debug. Hook-authored reasons appear only in a separate debug event, hooks.decision_reasons.

tracing diagnostics are separate from session transcript traces: the JSONL files that TraceRecorder writes to traces_dir and that halter::session::export_session_trace produces. Transcript traces record committed session events. The telemetry feature does not read or write them.

OpenTelemetry

The otel feature (implies telemetry) adds halter::telemetry::otel: an OTLP trace and metric exporter built on top of the span contract above. It is entirely opt-in — enabling the feature adds no behavior. Nothing is exported, and no OTel exporter, provider, or layer is constructed, until the embedder calls OtelConfig::build() explicitly. halter::telemetry::otel never calls opentelemetry::global::set_tracer_provider (or the meter/ propagator equivalents): the Tracer/Meter are threaded directly into the returned layers, so no OTel state becomes globally ambient either.

halter = { version = "0.9", features = ["otel"] }
use halter::telemetry::TelemetryConfig;
use halter::telemetry::otel::OtelConfig;

fn main() -> anyhow::Result<()> {
    let (layers, _otel_guard) = OtelConfig::new().build()?;
    // `try_init_with_otel` composes the console formatter and the OTel
    // layers as *siblings*, each with its own per-layer filter — see
    // "Filtering" below for why this matters.
    TelemetryConfig::new().try_init_with_otel(layers)?;
    // ... run the application ...
    // `_otel_guard` flushes and shuts down the tracer/meter providers when
    // dropped; call `_otel_guard.shutdown()` explicitly for a deterministic
    // flush before the process exits.
    Ok(())
}

OtelLayers holds the trace layer (tracing-opentelemetry, wired to an OTLP span exporter) and the metrics layer (a custom tracing_subscriber::Layer that derives OTel instruments from the spans and events above — see the table below) as two separate Layer<Registry>s, each already carrying its own per-layer filter (see "Filtering" below). The subagent span's follows_from link (see the span table) is exported as a real OTel span link. Shutdown can never hang forever on either provider, but OtelConfig::with_shutdown_timeout's configured bound is only honored precisely by the tracer: opentelemetry_sdk 0.33's meter provider ignores its timeout argument and always uses an internal hardcoded ~5s bound instead.

Filtering. The turn/tool_call/provider_request/provider_compaction/ subagent spans this feature exports are all created at info. By default halter::telemetry's console formatter only shows warn and above (RUST_LOG unset), and TelemetryConfig::try_init_with composes the console and any extra layer under one shared filter — so naively calling TelemetryConfig::new().try_init_with(layers.combined()) with RUST_LOG unset silently exports nothing, because the spans are never created in the first place. OtelConfig::build() avoids this by giving both OTel layers their own per-layer filter (halter_runtime=info,halter_providers=info by default — see OtelConfig::with_filter_directives to override), and TelemetryConfig::try_init_with_otel(layers) composes them as siblings of the console formatter instead of nesting them under one shared filter — so OTel exports info-level halter spans regardless of RUST_LOG, while the console itself still defaults to warn. Use try_init_with_otel, not try_init_with(layers.combined()), unless you've independently confirmed your composition keeps the OTel layers' filtering decoupled from the console's.

Transport. Export uses OTLP over HTTP/protobuf against the workspace's existing reqwest 0.12 client, not opentelemetry-otlp's bundled reqwest-client (which pulls reqwest ^0.13, a second major version) or grpc-tonic (which pulls tonic). This keeps cargo tree -e normal --features otel to exactly one extra dependency family (opentelemetry*, tracing-opentelemetry) with a single reqwest version; no library crate (halter-runtime, halter-providers, halter-hooks, halter-tools) ever gains an OTel or second-reqwest dependency, with or without --all-features. The SDK exports from its own background threads, so OtelConfig::build() also starts one small dedicated Tokio worker thread (halter-otlp-http) that performs the HTTP requests. Export does not depend on, or need, the application's runtime, and keeps working while that runtime shuts down.

Env vars, honored by the underlying OTel SDK (not re-implemented here):

Variable Effect
OTEL_EXPORTER_OTLP_ENDPOINT Base OTLP/HTTP endpoint; /v1/traces and /v1/metrics are appended.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT / _METRICS_ENDPOINT Per-signal endpoint override, used verbatim.
OTEL_SERVICE_NAME service.name resource attribute. Defaults to halter if unset.
OTEL_RESOURCE_ATTRIBUTES Additional key=value,... resource attributes.
OTEL_TRACES_SAMPLER / _ARG always_on / always_off / traceidratio (+ ratio) / parentbased_*. Defaults to parentbased_always_on.

OtelConfig::with_endpoint, with_service_name, with_resource_attributes, and with_sampler override the corresponding env var when set. OTEL_EXPORTER_OTLP_PROTOCOL has no effect: this module only ever speaks OTLP HTTP/protobuf (see "Transport" above).

Metrics. Derived from the span/event contract, not emitted directly by library crates, so halter-runtime/halter-providers/etc. stay free of an OTel dependency. Every attribute is low-cardinality: metrics never carry session_id, turn_id, tool_call_id, or agent_id (spans do carry them — see the span table above).

Metric Kind Unit Attributes Source
gen_ai.client.token.usage Counter<u64> {token} gen_ai.system, gen_ai.request.model, gen_ai.token.type (input/output/cache_read/cache_creation) turn close, one add() per non-zero token field
halter.turn.duration Histogram<f64> s outcome turn close
halter.tool_call.duration Histogram<f64> s tool_name, outcome tool_call close
halter.tool_call.errors Counter<u64> {error} tool_name, outcome tool_call close, when outcome != "ok"
gen_ai.client.operation.duration Histogram<f64> s gen_ai.system (= provider_kind), gen_ai.request.model, outcome, halter.operation (request/compaction) provider_request/provider_compaction close
halter.provider.retries Counter<u64> {retry} provider_kind, error_kind ResilientProvider retry events
halter.provider.rate_limited Counter<u64> {retry} provider_kind retry events where error_kind is RateLimited
halter.subagents.in_flight UpDownCounter<i64> {subagent} agent_type subagent open (+1) / close (-1)

The gen_ai.* names follow OpenTelemetry's GenAI semantic conventions in spirit; the installed opentelemetry-semantic-conventions crate marks the matching constants (GEN_AI_SYSTEM, GEN_AI_REQUEST_MODEL, GEN_AI_TOKEN_TYPE) deprecated in favor of newer, still-in-flux names, so this module uses the plain string literals directly rather than depending on constants that might rename across patch releases.

Local collector example, using the OpenTelemetry Collector's debug exporter on OTLP/HTTP:

cat > /tmp/otel-collector-debug.yaml <<'EOF'
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [debug]
    metrics:
      receivers: [otlp]
      exporters: [debug]
EOF

docker run --rm -p 4318:4318 \
  -v /tmp/otel-collector-debug.yaml:/etc/otelcol/config.yaml \
  otel/opentelemetry-collector:latest

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 halter run "..."

The CLI (built with cargo build --features otel) only exports when OTEL_EXPORTER_OTLP_ENDPOINT is set; it never exports by default, even when compiled with the feature. The CLI composes its OTel layers with TelemetryConfig::try_init_with_otel (see "Filtering" above), so this works as shown — exporting info-level turn/tool_call/provider_request/ subagent spans and metrics — without setting RUST_LOG; the console log output itself still defaults to warn unless you set RUST_LOG separately.


Features

The halter crate keeps optional capabilities out of the default build. No feature is enabled by default. Enable the feature at compile time, then make sure the corresponding tool or session backend is enabled by config and policy.

Feature What it enables Extra dependencies Runtime notes
advanced-tools Enables the advanced grep execution path: parallel content searches when possible and memmap2-backed reads for larger regular files. rayon, memmap2 Applies to the existing grep tool. It does not register a new tool name.
ast-tools Adds the syntax-aware ast_grep built-in tool for code search and rewrites. ast-grep-core, ast-grep-language Tool name: ast_grep. Actions: find, replace.
browser-tools Adds the browser built-in tool for remote browser automation over Chrome DevTools Protocol (CDP). playwright-rs, reqwest Tool name: browser. Requires provider configuration, currently BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID, plus Playwright runtime setup. Network policy still applies.
image-tools Adds the image built-in tool for local image inspection and transforms. image Tool name: image. Actions: info, resize, convert. File reads and writes remain subject to tool policy.
pty Adds the pty built-in tool for bounded interactive terminal sessions. portable-pty Tool name: pty. Actions: start, write, resize, kill. Use this when a plain shell command is not enough.
profiling Adds the profile built-in tool for profiling and instrumentation workflows. inferno Tool name exposed to the model: profile.
full Convenience rollup for the optional built-in tool families. Same extra dependencies as advanced-tools, ast-tools, browser-tools, image-tools, pty, and profiling. Does not include sqlite; enable sqlite separately when persistent session storage is needed.
sqlite Enables SQLite-backed session persistence and the matching config schema. rusqlite Allows sessions.backend = "sqlite" and exposes halter::session::SqliteSessionStore. The default backend remains memory unless config selects SQLite.
telemetry Adds halter::telemetry, the opt-in tracing subscriber helper the CLI uses (env filter, noisy-target suppression, compact/JSON output). tracing-subscriber No subscriber is installed unless try_init/try_init_with is called. See Observability.
otel Adds halter::telemetry::otel: OTLP trace and metric export (builds on telemetry). opentelemetry, opentelemetry_sdk, opentelemetry-otlp, opentelemetry-http, opentelemetry-semantic-conventions, tracing-opentelemetry Implies telemetry. Nothing is exported, and no OTel exporter/provider/layer is constructed, unless the embedder calls OtelConfig::build() explicitly. See OpenTelemetry.

Environment overrides

The config crate supports a focused set of environment overrides, including:

  • HALTER_SESSION_BACKEND
  • HALTER_POLICY_SHELL_ENABLED
  • HALTER_POLICY_NETWORK_ENABLED
  • HALTER_SKILL_ROOTS
  • HALTER_PLUGIN_ROOTS
  • HALTER_POLICY_ALLOWED_HOSTS
  • HALTER_TOOLS_ENABLED

These are useful for CI, local overrides, or environment-specific deployment adjustments without duplicating full config files.


Releasing

Releases are cut from a clean main that matches origin/main, by a repository admin (the rulesets only let admins push to main and create tags):

bin/release 0.9.0                            # releases the [Unreleased] section
bin/release --title "Short name" 0.9.0 notes.md   # or a changelog file ("-" for stdin)

The script moves every crate under crates/ to the new version and writes the changelog into ## [0.9.0] - <date> in CHANGELOG.md. It runs cargo check, then shows you the diff and the release notes. Nothing is committed until you confirm. After you confirm, it commits Bump crate versions for v0.9.0, pushes main and the v0.9.0 tag together, and creates the GitHub release. The tag push runs publish.yml, which publishes the changed crates to crates.io. Pass --yes to skip the prompt.

About

Drive your clankers like a cowboy

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages