clark_agent/
lib.rs

1//! # clark-agent
2//!
3//! A small, typed, hookable agent loop. Provider-agnostic, sandbox-agnostic,
4//! tooling-agnostic.
5//!
6//! ## Shape
7//!
8//! ```text
9//! context → LLM (StreamFn) → tool batch → results appended → repeat
10//! ```
11//!
12//! Termination is a tool decision (`ToolResult::terminate = true`, unanimous
13//! across the batch). The runtime owns execution and event emission; tools
14//! own semantics; plugins own cross-cutting extension.
15//!
16//! ## Layers
17//!
18//! - [`types`] — `AgentMessage`, content blocks, `StopReason`. The conversation
19//!   transcript is `Vec<AgentMessage>`. Apps extend via `AgentMessage::Custom`
20//!   or by wrapping in their own enum.
21//! - [`event`] — `AgentEvent` enum + `EventSink` trait. Single sink, typed
22//!   events. Streamed and final delivery use the same enum.
23//! - [`tool`] — `AgentTool` trait + `ToolRegistry`. Tools own their own state
24//!   and validation; the loop only dispatches.
25//! - [`stream`] — `StreamFn` trait. Swappable LLM transport: real provider,
26//!   fixture replay, scripted scenario, remote proxy.
27//! - [`plugin`] — `Plugin` + capability traits (`BeforeToolCall`,
28//!   `AfterToolCall`, `ContextTransform`, `EventObserver`, `SteeringSource`).
29//!   Cross-cutting concerns register here, not inline in the loop.
30//! - [`protocol`] — `ProtocolPolicy`. The seam for product-specific tool
31//!   vocabulary (recovery prose, tool-call alias repair, hidden-tool errors).
32//!   The core ships a generic default that names no tools.
33//! - [`config`] — `LoopConfig` + `AgentBuilder` for assembling everything.
34//! - [`mod@run`] — [`run()`] / [`run_continue()`] — the canonical loop. Pure functions.
35//! - [`exec`] — tool execution: parallel + sequential dispatch, hook plumbing.
36//! - [`budget`] — default token-budget context transform.
37//! - [`error`] — typed error enums.
38
39pub mod budget;
40pub mod config;
41pub mod error;
42pub mod event;
43pub mod exec;
44pub mod plugin;
45pub mod plugins;
46pub mod protocol;
47pub mod reasoning;
48pub mod run;
49pub mod stream;
50pub mod thinking_filter;
51pub mod tokens;
52pub mod tool;
53pub mod tool_identity;
54pub mod tool_result_budget;
55pub mod trajectory;
56pub mod types;
57
58pub use budget::TokenBudget;
59pub use config::{
60    AgentBuilder, LoopConfig, MaxTokensRecovery, PluginNames, TokenScaling,
61    DEFAULT_GRACE_ITERATIONS,
62};
63pub use error::{LoopError, StreamError, ToolError, ToolValidationError};
64pub use event::ChannelSink;
65pub use event::{AgentEvent, EventSink, ProviderRequestSummary};
66pub use plugin::PluginCapabilities;
67pub use plugin::{
68    AfterToolCall, AfterToolDecision, BeforeToolCall, BeforeToolDecision, ContextTransform,
69    EventObserver, FollowUpSource, Plugin, SteeringSource, TransformContext,
70};
71pub use plugins::GracefulTurnLimit;
72pub use protocol::{
73    DefaultProtocolPolicy, HiddenToolContext, HiddenToolError, PlainTextRecoveryContext,
74    ProtocolPolicy, DEFAULT_PLAIN_TEXT_RECOVERY_PROMPT,
75};
76pub use reasoning::{
77    audit_replay, OpenRouterReasoningCodec, ReasoningCodec, ReasoningFormat, ReasoningItem,
78    ReplayAudit, ReplayContract, ReplayViolation,
79};
80pub use run::{run, run_continue, LoopOutcome, RunResult};
81pub use stream::{
82    AssistantStreamChunk, ReasoningEffort, StreamEvent, StreamFn, StreamRequest, StreamResponse,
83};
84pub use thinking_filter::{strip_thinking_tags, ThinkingTagStreamFilter};
85pub use tokens::{CharHeuristicEstimator, TokenEstimator, CHAR_HEURISTIC};
86pub use tool::{
87    arg_parse_error_value, detect_arg_parse_error, AgentTool, ExecutionMode, ToolCall,
88    ToolHistoryPolicy, ToolRegistry, ToolResult, ToolUpdateSink, TypedAgentTool,
89    ARG_PARSE_ERROR_MARKER, ARG_PARSE_RAW_MARKER,
90};
91pub use tool_identity::{
92    extract_args_key, extract_operation_key, extract_target, ArgsKeyFn, TargetExtractor, TargetFn,
93    ToolIdentityPolicy,
94};
95pub use tool_result_budget::{ToolResultBudget, DEFAULT_PER_TOOL_CHARS};
96pub use trajectory::{
97    InMemoryTrajectorySink, TrajectoryError, TrajectoryPayload, TrajectoryRecord,
98    TrajectoryRecorder, TrajectorySink, TRAJECTORY_SCHEMA_VERSION,
99};
100pub use types::{
101    AgentContext, AgentMessage, AssistantBlock, AssistantContent, ImageContent,
102    ReasoningDetailsContent, RunIdentity, StopReason, TextContent, ToolResultBlock,
103    ToolResultContent, UserBlock, UserContent,
104};
clark_agent/lib.rs

clark_agent/
lib.rs
