thndrs-agent

thndrs-agent is an experimental, provider-neutral Rust library for authors of coding-agent applications.

It provides a small vocabulary for iterations of agent loops, namely messages in, semantic events out, tool requests, permission decisions, and cooperative cancellation.

Use it when your application owns the model client and tool policy but you want the rest of the agent loop to speak small, typed Rust values.

A terminal UI, web service, or editor integration can all consume the same events without importing a provider's wire types.

Installation

Add it to your crate or workspace's Cargo.toml:

[dependencies]
thndrs-agent = "0.1"
serde_json = "1"

Describe a Turn

Build an AgentTurn from your application's conversation and tool catalog, then lower it in your provider adapter.

The provider adapter returns AgentEvent values as work progresses.

use thndrs_agent::{AgentMessage, AgentTurn, ToolDefinition};

let turn = AgentTurn::new(
    vec![AgentMessage::User("Summarize the README".into())],
    vec![ToolDefinition::new(
        "read_file",
        "Read a workspace file",
        serde_json::json!({"type": "object"}),
    )],
);

assert_eq!(turn.messages.len(), 1);
assert_eq!(turn.tools[0].name, "read_file");

AgentRun is a small helper for a background run. Give it a closure that sends your event type and checks the supplied CancelToken. Then, consume the receiver in the UI or transport that owns presentation.

Control Context

context provides pure, deterministic context control for agent turns:

typed candidate items
token budgets
selection
compact ledgers
compaction policy.

Hosts supply project instructions, transcript entries, skills, and pins.

Modules

adapters contains application-owned permission and execution callbacks.
budget bounds tool batches and continuation segments.
cancel provides a shared cooperative cancellation token.
context contains pure selection, control, and compaction policy.
contracts defines provider-neutral messages, events, tools, and retry values.
run owns a background run's event channel and cancellation handle.

Keep Policy in your application

This crate does not read files, run processes, or contact a model provider.