anvil · reference

Architecture & core types

Where everything lives and what each piece is responsible for. Names and responsibilities only, with no implementations, so you still write the code. ← course ·

Crate map & dependency rule

llm: types

Type	Responsibility	Ch
`Role`	User · Assistant	01
`ContentBlock`	Text · Image · Reasoning · ToolCall · ToolResult	01
`ProviderMeta`	opaque {provider, data}, replayed only to its own provider	01
`Message`, `ToolSpec`, `ChatRequest`	canonical conversation + request	01
`validate_transcript`	machine-checked integrity	01
`StreamEvent`, `Usage`, `FinishReason`	normalized stream vocabulary	02
`LlmError`	Http · Transport · Api · Decode · UnexpectedEof · Config, with `is_retryable`	02
`Provider` trait	`name()`, `stream(&ChatRequest) → Result<EventStream>`	02
`SseDecoder`	sans-IO bytes → SSE events	02
`MessageBuilder`, `Completion`	events → Message + Usage + Finish	03
`Registry`, `Retry`	alias → provider · backoff decorator	06
`ScriptedProvider`	deterministic test double	08

agent: types

Type	Responsibility	Ch
`Tool` / `TypedTool`	runtime contract / typed convenience	07
`ToolRegistry`	sorted specs, never-failing dispatch, truncation	07
`Agent`, `AgentEvent`, `TurnOutcome`	the loop, its event stream, why a turn ended	08
`FileTracker`	read-before-write freshness	10
`Policy`, `Decision`, `Approver`	rules + modes → allow/ask/deny → human	11
`SandboxPolicy`	OS-enforced limits for subprocesses	12
`PromptBuilder`, `ContextBudget`	layered prompt · token accounting	13
`SessionWriter`, `Record`	append-only JSONL, resume	14
`McpTool`	remote tool as a `Tool`	15
`HookRunner`, skills loader	sensors & guides from config	16
`TaskTool`, todo tool	subagents · planning	17
`SessionMeter`, `Pricing`	cost & budgets	18
`Checkpoints`	shadow-git snapshots, /undo	20

One step of a turn (data flow)

Invariants (put these in tests)

validate_transcript holds after every step, interruption, compaction and resume.
No provider type or provider name appears outside crates/llm.
dispatch never returns Err. Every failure is an is_error result.
Tool specs and system prompt are byte-identical between steps of a session (cache stability).
Nothing is printed to stdout except the answer (headless) or rendered events (interactive).
Deny rules win in every permission mode. Bash always runs through the sandbox unless the user explicitly approved escalation.
No subprocess inherits API keys. No transcript contains known secret values.