# 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`. Conversation
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. `ChannelSink`,
`FanOutSink`, `NoopSink` provided.
- **`tool`** — `AgentTool` trait + `ToolRegistry`. Tools own their schema,
validation, and execution. 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`,
`FollowUpSource`, `ToolGate`). 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,
terminal-tool classification). Default is generic and 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.
## Plugin extension points
| `BeforeToolCall` | After argument validation, before `tool.execute`. May block with reason. |
| `AfterToolCall` | After `tool.execute`. May override result, mark error, vote terminate. |
| `ContextTransform` | Before each LLM call. Window management, redaction. |
| `EventObserver` | On every `AgentEvent`. Logging, telemetry, persistence. |
| `SteeringSource` | Between batches. Inject extra messages mid-run. |
| `FollowUpSource` | After natural stop. Re-start the agent if more is queued. |
A single struct can implement multiple capability traits — declare the
set via `Plugin::capabilities()` and register once with
`AgentBuilder::plugin()`.
## Quick start
```rust
use std::sync::Arc;
use clark_agent::{AgentBuilder, AgentContext, AgentMessage, ToolRegistry, UserContent};
use tokio_util::sync::CancellationToken;
let registry = ToolRegistry::new()
.with(Arc::new(my_shell_tool()))
.with(Arc::new(my_file_tool()));
let config = AgentBuilder::new()
.stream(Arc::new(my_provider()))
.tools(registry)
.before_tool_call(my_security_gate())
.after_tool_call(my_repeat_detector())
.context_transform(clark_agent::budget::TokenBudget::default())
.max_iterations(50)
.build()?;
let outcome = clark_agent::run(
vec![AgentMessage::User {
content: UserContent::Text("List files in /tmp".into()),
timestamp: None,
}],
AgentContext::new("You are a helpful assistant."),
&config,
CancellationToken::new(),
).await?;
```
## Examples
Run the smallest possible loop with a scripted transport:
```sh
cargo run --example minimal
```
Run a two-turn loop where the model calls a typed `echo` tool:
```sh
cargo run --example tool_call
```
Real integrations provide their own `StreamFn` implementation for an LLM
provider and register application tools through `AgentTool` or
`TypedAgentTool`.
## Mid-run steering (`steer()`)
```rust
let (steering, handle) = clark_agent::plugin::ChannelSteering::new();
let config = AgentBuilder::new()
.stream(provider)
.tools(registry)
.steering_arc(steering)
.build()?;
// In another task: inject a message between batches.
handle.steer(AgentMessage::User {
content: UserContent::Text("actually, focus on /etc instead".into()),
timestamp: None,
})?;
```
## Design rules
- **One canonical core.** `run` / `run_continue` are pure functions, not
methods on a god-class.
- **Hooks are typed, narrow, side-effect-free.** No I/O in `BeforeToolCall`
or `AfterToolCall` — those belong to the tool's own `execute`.
- **Failure is a context event.** Tool errors become tool result content
with `is_error: true`. The loop appends and continues. Only `LoopError`
(stream transport unrecoverable / aborted) ends the run.
- **Termination requires unanimity.** A batch ends the run only when
every finalized tool result votes `terminate: true`. One tool wanting
to stop does not stop the batch.
- **Strongly typed contracts.** Discriminators are enums; payloads are
typed structs; field-name string lookups (`obj["role"]`) are forbidden
in primary contracts. `serde_json::Value` only at open-by-design leaves
(provider extras, custom message payloads, tool arguments).
## Open-source boundary
`clark-agent` is the reusable loop crate: typed history, tool dispatch,
provider transport traits, events, and extension hooks. Product wiring
belongs in downstream crates.
The core knows **no product tool names**. The three places that once needed
product vocabulary — plain-text recovery prose, model tool-call alias repair,
and hidden-tool error messages — now go through a single seam, the
[`ProtocolPolicy`] trait:
```rust
pub trait ProtocolPolicy: Send + Sync + 'static {
fn terminal_tool_names(&self) -> HashSet<String> { ... }
fn plain_text_recovery_prompt(&self, ctx: PlainTextRecoveryContext<'_>) -> Option<String> { ... }
fn normalize_tool_calls(&self, calls: &mut [ToolCall], registry: &ToolRegistry) -> usize { ... }
fn hidden_tool_error(&self, ctx: HiddenToolContext<'_>) -> Option<HiddenToolError> { ... }
}
```
The core ships `DefaultProtocolPolicy` (generic, names no tools). A downstream
product installs its own via `AgentBuilder::protocol_policy(...)` to inject its
delivery/ask/plan vocabulary, tool-call aliases, and recovery prose — none of
which lives in this crate. New product-specific behavior should be implemented
as a `ProtocolPolicy`, a plugin (`ToolGate`, `ContextTransform`, …), or a tool
definition rather than added to the core loop.
[`ProtocolPolicy`]: https://docs.rs/clark-agent/latest/clark_agent/protocol/trait.ProtocolPolicy.html
## Release checks
```sh
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps
cargo publish --dry-run
```
## Citation
Citation authorship: Stanislav Kirdey, Clark Labs Inc. See
[`CITATION.cff`](CITATION.cff) for machine-readable citation metadata.
## License
Apache-2.0 © Stanislav Kirdey, [Clark Labs Inc.](https://github.com/clark-labs-inc)
---
Built by **Stanislav Kirdey, Clark Labs Inc.** — the team behind
[Clark](https://www.clarkchat.com), AI-powered web automation and research.
If clark-agent is useful to you, a ⭐ on
[GitHub](https://github.com/clark-labs-inc/clark-agent) helps others discover it.