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.
- Cache friendliness
- Obsessive token optimization
- Best in class multi model support
- Best in class tool calling and hook support
- Simple and expressive API
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
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
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
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(())
}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(())
}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(())
}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.
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(())
}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.
halter— high-level SDK and builderhalter-config— config schema, loading, overrides, validationhalter-protocol— shared types and wire-format vocabularyhalter-runtime— session engine, prompt assembly, event bus, compaction, subagentshalter-providers— provider adapters and model registryhalter-tools— tool runtime, built-in tools, policy, subagent control toolshalter-hooks— event-driven hook and policy interception layerhalter-session— session persistence and replay
halter-config defines the schema for:
- providers
- model roles (
default,small,subagent), withdefaultandsubagentoptionally backed by an experimental"model_judge"panel via[models.model_judge] - resource roots
- prompts (a built-in
presetplus a fullsystem_promptoverride) - 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.
When using config files, halter resolves the effective config first, then resolves provider credentials.
Config value hierarchy:
- Built-in defaults.
- 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. - Supported
HALTER_*environment overrides, such asHALTER_TOOLS_ENABLEDorHALTER_POLICY_SHELL_ENABLED. These are applied after file loading, so they win over file values.
Provider credential hierarchy:
[providers.<name>].api_keyin the effective config wins when it is present and non-empty.- For OpenAI only,
[providers.openai].oauthmay be configured instead ofapi_key. It must includeclient_id,access_token,id_token, andrefresh_token; the provider sendsaccess_tokenas the bearer token. OAuth traffic for/v1/responses, every path below that prefix, and/chat/completionsrewrites tohttps://chatgpt.com/backend-api/codex/responses, sobase_urlis ignored for those paths. OAuth requests send the assembled system prompt as top-levelinstructions, omit the developer/system input item, and setstoretofalse. - If no explicit credential is configured, halter reads the provider-specific process environment variable:
OPENAI_API_KEY,ANTHROPIC_API_KEY, orOPENROUTER_API_KEY. - 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 = falserouting 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 = 3SDK users can override the effective provider policy for all configured
providers with HalterBuilder::with_resilience_policy(...).
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:
- Each directory is scanned for child directories.
- A child directory containing
SKILL.mdis loaded as one skill. - 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:
.codex-plugin/plugin.json.claude-plugin/plugin.json.agent-plugin/plugin.jsonplugin.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.
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 withbasic-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"]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.
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 = unboundedreasoning 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.
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:
- The context and user message are multiplexed to every model in
panelin 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. - The
synthesismodel is given the panel responses and arank_responsestool. It first stack-ranks the responses (emitted as structuredtracingtelemetry), then writes a synthesis that judges, not merges, them (strengths, weaknesses, pros, cons, overall). - The synthesis is handed to the
defaultmodel 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 toshared_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.
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 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 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
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:
readglobgrepwriteeditshellprocesstask(todo list scoped to the session; rebuilt from the session log on resume)
Optional feature-gated tools include:
ptyast_grepimagebrowserprofile
Subagent tools include:
spawn_agentsend_inputwait_agentclose_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 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
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 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:
InMemorySessionStoreSqliteSessionStore(behind thesqlitefeature)
Use memory for:
- tests
- ephemeral local runs
- simplest setup
Use SQLite for:
- resumable local agents
- durable transcripts
- replay after process restart
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.
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.
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_thresholddefaults tomodels.default.max_input_tokensminus 20,000; one of the two must be set or loading the config and building the harness fail.context.max_tokens(defaultmax_input_tokens) is a hard cap checked before each provider request, after compaction has had its chance: a turn that would exceed it fails withhalter::compaction::ContextCapExceededinstead of blowing the provider window.- Automatic compaction is best-effort: a strategy that cannot run degrades the
turn to an uncompacted context with a
Warningevent, 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/PostCompacthooks fire on both paths, with triggerautofor the automatic one.PostCompactfires only after a compaction replaced the context, and a pass the strategy rules out up front (CompactionStrategy::needs_compaction) fires neither hook. context.compactionpicks the strategy."model_summary"(the default) asks the session's own model for a context checkpoint: when thetasktool is registered it first nudges the model to persist its remaining work there (onlytaskcalls 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 itscontext_boundaryhook 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 theCompactionContextthe 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?;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.
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
The following can all be implemented in custom hooks:
- approvals
- denials
- stop conditions
- input/output rewriting
- extra context or warnings
- audit annotations
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.
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.
- Targets are the default module paths (
halter_runtime::session, ...). Don't invent custom targets. - Levels:
error/warnfor actionable problems;infofor lifecycle and policy outcomes;debugfor details and decisions;tracefor 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 asanthropic/openai/openrouter),model(upstream model),model_id(halter model id),attempt,outcome,error_kind, and theUsagetoken names. - Use structured fields instead of values interpolated into the message.
- Never log secrets, full tool inputs, prompts, or hook payloads at
infoor 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 anEnteredguard across.await. Tasks that are part of the current operation carry its span. Detached or long-lived tasks useparent: Noneplusfollows_from. - Token usage is recorded only on
turn, so span-derived metrics never double count. - Hooks:
halter-hooksemitshooks.matched(debug) when handlers match andhooks.decisionafter merging. Decisions that block, stop, deny, or ask log atinfo; others atdebug. Hook-authored reasons appear only in a separatedebugevent,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.
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.
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. |
The config crate supports a focused set of environment overrides, including:
HALTER_SESSION_BACKENDHALTER_POLICY_SHELL_ENABLEDHALTER_POLICY_NETWORK_ENABLEDHALTER_SKILL_ROOTSHALTER_PLUGIN_ROOTSHALTER_POLICY_ALLOWED_HOSTSHALTER_TOOLS_ENABLED
These are useful for CI, local overrides, or environment-specific deployment adjustments without duplicating full config files.
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.