Concepts

Run

One execution of an agent toward a goal, under limits, with a status: RUNNING, WAITING_FOR_APPROVAL, COMPLETED, FAILED, or CANCELLED. The last three are terminal. A terminal run carries a reason such as goal_completed, limit_steps, policy_abort, model_unavailable, operator_cancelled, approval_expired, reconcile_conflict, or internal_error, and a result when it completed. Runs also accumulate totals: steps, model calls, tokens, cost, and active time.

A run is created already RUNNING; there is no separate created state. A run interrupted by a crash also stays RUNNING until Resume finds it by its lease. INTERRUPTED remains a defined status that Resume and Cancel accept, but the runtime does not write it.

Step

One turn of the loop. A step moves through deciding, then awaiting_approval or executing, then done or failed; a step found in flight by a later process becomes interrupted. Each step records the decision, the policy verdict, and the observation.

Decision

What the agent asked for: a tool_call with a name and arguments, complete with a result, or fail with a message. It is recorded verbatim before validation, so the audit log shows what the agent wanted even when the request was invalid. The agent's stated reason is stored as data.

Since v0.4.0 a decision also carries an optional Origin: model, plan, or operator, recording who proposed the step. The runtime records it and attaches no behaviour to it, and policy does not see it. See The Gate.

Observation

What the agent sees next: a tool_result, a tool_error, a policy_denied, an invalid_decision, or an interrupted. Anything other than a tool result counts as a failure for the consecutive-failure limit. Each observation carries a hash of its content for loop detection.

Tool

A named capability with a description, a JSON schema for its arguments, a side-effect class, a timeout, and optionally the terminal flag. The runtime validates arguments against the schema and asks the policy before calling it. A terminal tool's success completes the run with its result.

Side-effect class

read_only, local_mutation, remote_mutation, or destructive. The default policy allows the first two, requires approval for the third, and denies the fourth. The class is declared by the tool author and is what a policy reasons about first.

Policy

Code that sees every validated tool request together with a read-only view of the run, and answers allow, deny, abort, or require_approval. The agent has no handle to it.

Approval

A durable pause. The policy's require_approval answer stores a kind, a capability, a presentation for the human, and the exact request, hashed together. A human approves or rejects it out of band; the runtime resumes by re-checking the request against the tool's schema, re-evaluating policy, and executing only the recorded request. The runtime raises one approval of its own: interrupted_side_effect, when a crash left a side effect's outcome unknown and the consumer has no reconciliation.

Event

One row in the append-only audit log, written in the same transaction as the state change it describes. Types cover run lifecycle, each stage of a step, approvals, limits, loops, interruption, and model calls.

Limits

Caps the driver enforces before each step and before each model call: steps, consecutive failures, loop repetitions, model calls, output tokens per call, total tokens, estimated cost, active time, elapsed time, how long an approval may stay pending, and how long a grant may wait for resume.

Model and ModelCaller

Model is the interface a provider adapter implements. ModelCaller is the accounting wrapper the agent receives: it records every attempt, enforces the model-related limits before dispatch, and retries transient errors when the consumer configured retries.

Reconciliation

The consumer's answer when a run is found mid-step: continue, completed with a result, waiting with the approval to pause on, or conflict with a detail. Without a reconciliation, an interrupted side effect waits for an operator. See Interruption and Reconciliation.

Lease

The record, on a RUNNING run's row, of which driver is executing it and until when. It is taken when the run starts or resumes, renewed by a heartbeat, and released when the run pauses or finishes. A Resume of a run whose lease is live and held by someone else is refused with ErrRunLeased. See Run Lease.

Gate and Session

A Gate is the runtime's controls for a loop the runtime does not own. The caller's loop proposes each action, and the gate records it, validates it, evaluates policy, pauses on a hash-bound approval, enforces the limits, executes the tool itself, and records the outcome. Begin or Attach returns a Session, one hold on a run with its lease, with at most one open step. Propose answers with a verdict: allowed, denied, pending, or ended. The Driver runs on the same code. See The Gate, and MCP Proxy for the gate in front of an MCP host.

Store

One SQLite file holding runs, steps, model calls, approvals, events, and a migrations table, readable and writable by its owner only. A consumer may keep its own tables in the same file.