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.