Crate thndrs_agent 

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.

Use ToolPermissionHook when your application must approve a sensitive tool call, and ToolExecutionHook when it needs to take over execution. The application context and result types remain yours.

Re-exports

pub use accounting::ByteMeasurement;

pub use accounting::ContextItemSnapshot;

pub use accounting::ContextReductionReceipt;

pub use accounting::MeasurementProvenance;

pub use accounting::ModelProjectionMessage;

pub use accounting::ProviderRequestAccounting;

pub use accounting::ProviderUsage;

pub use accounting::ProviderUsageComponents;

pub use accounting::ProviderUsageRule;

pub use accounting::TOKEN_ESTIMATOR_VERSION;

pub use accounting::TokenMeasurement;

pub use accounting::USAGE_NORMALIZATION_VERSION;

pub use accounting::estimate_serialized_tokens;

pub use accounting::snapshot_context;

pub use adapters::ToolExecutionHook;

pub use adapters::ToolPermissionHook;

pub use budget::ToolBudgetDecision;

pub use budget::ToolIterationBudget;

pub use cancel::CancelToken;

pub use contracts::AgentEvent;

pub use contracts::AgentMessage;

pub use contracts::AgentTurn;

pub use contracts::RetryPolicy;

pub use contracts::ToolDefinition;

pub use contracts::ToolDisplayProjection;

pub use contracts::ToolEvidenceKind;

pub use contracts::ToolEvidenceMetadata;

pub use contracts::ToolModelProjection;

pub use contracts::ToolOutput;

pub use contracts::ToolPermissionDecision;

pub use contracts::ToolStatus;

pub use contracts::ToolUseRequest;

pub use replay::BaselinePolicy;

pub use replay::CandidatePolicy;

pub use replay::ProjectionReport;

pub use replay::RecordedProviderUsage;

pub use replay::RecoveryCase;

pub use replay::RecoveryOutcome;

pub use replay::ReplayComparison;

pub use replay::ReplayError;

pub use replay::ReplayEvaluator;

pub use replay::ReplayFixture;

pub use replay::ReplayItem;

pub use replay::ReplayItemKind;

pub use replay::ReplayPolicy;

pub use replay::ReplayProjection;

pub use replay::ReplayReceipt;

pub use replay::ReplayReport;

pub use replay::ReplayScenario;

pub use replay::ReplayTiming;

pub use replay::RequiredFact;

pub use replay::RequiredFactResult;

pub use replay::evaluate_fixture;

pub use replay::load_fixture;

pub use replay::project_fixture;

pub use replay::select_items;

pub use run::AgentRun;

Modules

accounting

Provider-neutral request size and usage accounting.

adapters

Application-owned tool policy and execution adapters.

budget

Provider-neutral tool-iteration budgeting for one agent turn.

cancel

Shared cooperative cancellation primitive.

context

Provider-neutral context control for agent turns.

contracts

Provider-neutral run contracts shared by application adapters.

replay

Deterministic replay fixtures and evaluation for context projections.

run

Provider-neutral background-run ownership.