anvil · reference

Glossary

The course's canonical vocabulary. Each concept has one name, used consistently in every lesson. ← back to course ·

Revised contracts. Native filesystem tools enforce FileAccess grants; plan mode caps mutation authority; project executable config is trusted separately; every session mutation has a reducer record; unfinished side effects recover as unknown; required verifiers and eval graders are independent evidence. Provider switching is conditional on supported replay. See the matching course boundary exercises for the build contract.

Harness concepts

Harness: Everything around the model that turns its output into reliable work: loop, tools, context policy, safety, verification, UI. Avoid: framework, scaffold, wrapper
Agent loop: The cycle of sampling the model, running requested tools, and appending results until the model stops calling tools or a stop condition fires. Avoid: agentic loop, ReAct loop
Turn: One user input and everything the agent does in response, up to its final answer. Contains one or more steps.
Step: One model request inside a turn, plus the tool executions it triggers. Avoid: iteration, round
Guide: A feedforward control that steers the model before it acts: system prompt, AGENTS.md, tool descriptions, skills. (Böckeler)
Sensor: A feedback control that observes after the model acts and reports back: tool errors, hooks running checks, reviewer subagents.
Computational / inferential: Whether a guide or sensor is deterministic code (cargo check) or an LLM judgment (a reviewer agent).
Stop condition: A harness-enforced reason to end a turn regardless of the model: max steps, cost budget, cancellation.

Conversation model (crate `llm`)

Canonical model: The provider-neutral representation of conversations used everywhere above the llm crate. Avoid: internal format, universal schema
Message: A role (User or Assistant) plus an ordered list of content blocks.
Content block: One typed part of a message: Text, Image, Reasoning, ToolCall, ToolResult.
Tool call: A content block in which the model requests a tool by name with JSON arguments and a unique id. Avoid: function call, tool use (except when quoting a provider)
Tool result: A content block answering exactly one tool call by its call_id, optionally flagged is_error.
Transcript: The ordered list of messages in a session. The harness owns it. Avoid: history, chat log
Transcript integrity: The invariant that every tool call is answered by exactly one tool result in the next user message, roles alternate, and ids are unique.
Provider meta: Opaque provider-specific state (signatures, encrypted reasoning) attached to a block and replayed verbatim, but only to the same provider.
Provider: An endpoint + credentials + wire protocol, implementing the Provider trait. Avoid: backend, vendor
Adapter: The code that translates between the canonical model and one wire protocol (to_wire + a stream state machine).
Model alias: A user-facing name in config (sonnet, local) that resolves to a provider, a model id and limits.
Stream event: One normalized streaming event (TextDelta, ToolCallStart, ToolCallDelta, Usage, Finish…) emitted by every adapter.
Sans-IO: Protocol logic written as a pure state machine with no network access, fed by a thin I/O wrapper. Used for the SSE decoder and adapters.
Uncached input: anvil's canonical meaning of input_tokens: input tokens that were neither read from nor written to cache.

Agent (crate `agent`)

Tool: A capability the model can invoke: name, description, JSON schema, read-only flag, async call. Object-safe trait.
Typed tool: A tool whose arguments are a Rust type deriving JsonSchema, adapted to Tool by a blanket impl.
Dispatch: Turning a tool call into a tool result, never failing: unknown tools and bad args become error results.
Agent event: A UI-agnostic notification the agent emits (deltas, tool start/finish, usage, turn finished). Front ends consume them.
Permission subject: The string a tool call is judged by in permission rules: the command for bash, the path for file tools.
Permission mode: plan · default · accept-edits · bypass: the fallback decision when no rule matches.
Approver: The UI-implemented component that answers Ask decisions: allow once, allow always, deny with feedback.
Sandbox policy: OS-enforced limits for subprocesses: read-only, workspace-write (network on/off), full access.
Workspace: The directory tree the agent is working in. The default writable root.

Context

Context: All tokens sent in one request: tool definitions, system prompt, messages.
Project instructions: AGENTS.md (or CLAUDE.md) content merged into the system prompt. Avoid: memory file, rules file
Cache prefix: The stable leading part of the context that providers can cache: tools → system → earlier messages.
Compaction: Replacing a long transcript with a model-written handoff summary to free context. Avoid: summarization (as a feature name), pruning
Tool-result clearing: Replacing the content of old tool results with a placeholder while keeping the blocks for integrity.
Session: A persisted transcript plus metadata, stored as an append-only JSONL log and resumable.
Checkpoint: A snapshot of workspace files in a shadow git repo, restorable with /undo.

Extensibility

MCP server: An external process exposing tools, resources or prompts over the Model Context Protocol. anvil is an MCP client.
Hook: A user-configured command run at a lifecycle event (session_start, user_prompt_submit, pre_tool_use, post_tool_use, stop). Exit 2 means block or feed back.
Skill: A directory with SKILL.md (frontmatter + instructions) and optional files, loaded by progressive disclosure.
Progressive disclosure: Loading context in levels: metadata always, body on activation, files on demand.
Subagent: A child agent with fresh context, a filtered toolset and its own budget, run by the task tool, which returns only its final report.
Agent definition: A Markdown file (frontmatter: name, description, tools, model) whose body is a subagent's system prompt.

Quality

Scripted provider: A test double returning pre-written stream events in order and recording requests. Avoid: mock LLM, fake model
Golden transcript: A snapshot of exactly what the model was sent in a scripted scenario. It catches harness drift.
Task eval: A real task run against a real model in a fresh repo copy and graded by a check script, repeated k times.
pass@k: Probability that at least one of k trials succeeds.
pass^k: Probability that all k trials succeed. The reliability metric.
Conformance suite: One shared set of live scenarios every provider adapter must pass.