Crate clark_agent 

clark-agent

A small, typed, hookable agent loop. Provider-agnostic, sandbox-agnostic, tooling-agnostic.

Shape

context → LLM (StreamFn) → tool batch → results appended → repeat

Termination is a tool decision (ToolResult::terminate = true, unanimous across the batch). The runtime owns execution and event emission; tools own semantics; plugins own cross-cutting extension.

Layers

• types — AgentMessage, content blocks, StopReason. The conversation transcript is Vec<AgentMessage>. Apps extend via AgentMessage::Custom or by wrapping in their own enum.
• event — AgentEvent enum + EventSink trait. Single sink, typed events. Streamed and final delivery use the same enum.
• tool — AgentTool trait + ToolRegistry. Tools own their own state and validation; the loop only dispatches.
• stream — StreamFn trait. Swappable LLM transport: real provider, fixture replay, scripted scenario, remote proxy.
• plugin — Plugin + capability traits (BeforeToolCall, AfterToolCall, ContextTransform, EventObserver, SteeringSource). Cross-cutting concerns register here, not inline in the loop.
• protocol — ProtocolPolicy. The seam for product-specific tool vocabulary (recovery prose, tool-call alias repair, hidden-tool errors). The core ships a generic default that names no tools.
• config — LoopConfig + AgentBuilder for assembling everything.
• run — run() / run_continue() — the canonical loop. Pure functions.
• exec — tool execution: parallel + sequential dispatch, hook plumbing.
• budget — default token-budget context transform.
• error — typed error enums.

Re-exports

pub use budget::TokenBudget;

pub use config::AgentBuilder;

pub use config::LoopConfig;

pub use config::MaxTokensRecovery;

pub use config::PluginNames;

pub use config::TokenScaling;

pub use config::DEFAULT_GRACE_ITERATIONS;

pub use error::LoopError;

pub use error::StreamError;

pub use error::ToolError;

pub use error::ToolValidationError;

pub use event::ChannelSink;

pub use event::AgentEvent;

pub use event::EventSink;

pub use event::ProviderRequestSummary;

pub use plugin::PluginCapabilities;

pub use plugin::AfterToolCall;

pub use plugin::AfterToolDecision;

pub use plugin::BeforeToolCall;

pub use plugin::BeforeToolDecision;

pub use plugin::ContextTransform;

pub use plugin::EventObserver;

pub use plugin::FollowUpSource;

pub use plugin::Plugin;

pub use plugin::SteeringSource;

pub use plugin::TransformContext;

pub use plugins::GracefulTurnLimit;

pub use protocol::DefaultProtocolPolicy;

pub use protocol::HiddenToolContext;

pub use protocol::HiddenToolError;

pub use protocol::PlainTextRecoveryContext;

pub use protocol::ProtocolPolicy;

pub use protocol::DEFAULT_PLAIN_TEXT_RECOVERY_PROMPT;

pub use reasoning::audit_replay;

pub use reasoning::OpenRouterReasoningCodec;

pub use reasoning::ReasoningCodec;

pub use reasoning::ReasoningFormat;

pub use reasoning::ReasoningItem;

pub use reasoning::ReplayAudit;

pub use reasoning::ReplayContract;

pub use reasoning::ReplayViolation;

pub use run::run;

pub use run::run_continue;

pub use run::LoopOutcome;

pub use run::RunResult;

pub use stream::AssistantStreamChunk;

pub use stream::ReasoningEffort;

pub use stream::StreamEvent;

pub use stream::StreamFn;

pub use stream::StreamRequest;

pub use stream::StreamResponse;

pub use thinking_filter::strip_thinking_tags;

pub use thinking_filter::ThinkingTagStreamFilter;

pub use tokens::CharHeuristicEstimator;

pub use tokens::TokenEstimator;

pub use tokens::CHAR_HEURISTIC;

pub use tool::arg_parse_error_value;

pub use tool::detect_arg_parse_error;

pub use tool::AgentTool;

pub use tool::ExecutionMode;

pub use tool::ToolCall;

pub use tool::ToolHistoryPolicy;

pub use tool::ToolRegistry;

pub use tool::ToolResult;

pub use tool::ToolUpdateSink;

pub use tool::TypedAgentTool;

pub use tool::ARG_PARSE_ERROR_MARKER;

pub use tool::ARG_PARSE_RAW_MARKER;

pub use tool_identity::extract_args_key;

pub use tool_identity::extract_operation_key;

pub use tool_identity::extract_target;

pub use tool_identity::ArgsKeyFn;

pub use tool_identity::TargetExtractor;

pub use tool_identity::TargetFn;

pub use tool_identity::ToolIdentityPolicy;

pub use tool_result_budget::ToolResultBudget;

pub use tool_result_budget::DEFAULT_PER_TOOL_CHARS;

pub use trajectory::InMemoryTrajectorySink;

pub use trajectory::TrajectoryError;

pub use trajectory::TrajectoryPayload;

pub use trajectory::TrajectoryRecord;

pub use trajectory::TrajectoryRecorder;

pub use trajectory::TrajectorySink;

pub use trajectory::TRAJECTORY_SCHEMA_VERSION;

pub use types::AgentContext;

pub use types::AgentMessage;

pub use types::AssistantBlock;

pub use types::AssistantContent;

pub use types::ImageContent;

pub use types::ReasoningDetailsContent;

pub use types::RunIdentity;

pub use types::StopReason;

pub use types::TextContent;

pub use types::ToolResultBlock;

pub use types::ToolResultContent;

pub use types::UserBlock;

pub use types::UserContent;

Modules

budget

Default token-budget context transform.

config

Loop configuration + builder.

error

Typed error enums.

event

Typed events emitted by the loop.

exec

Tool batch execution.

plugin

Plugin extension points.

plugins

Built-in plugins shipped with clark-agent.

protocol

Conversation-protocol policy: the seam between the generic loop and a product’s tool vocabulary.

reasoning

Provider-agnostic reasoning replay.

run

The canonical agent loop.

stream

LLM transport extension point.

thinking_filter

Streaming filter that splits assistant text into a hidden <thought> channel and visible content.

tokens

Token estimation for budgeting and compaction.

tool

Tool surface.

tool_identity

ToolIdentityPolicy — typed declaration each tool gives the runtime about how to recognize “two calls of this tool that are the same operation on the same target”.

tool_result_budget

Per-tool-result content cap.

trajectory

Trajectory capture: ordered, failable, sequence-numbered run record.

types

Agent message shapes.