Glossary

Glossary

Agent. The thing that decides: one method, Decide, from a step input to a decision.

Ambiguous attempt. A model call whose outcome is unknown after dispatch; counted and charged conservatively.

Approval. A durable, hash-bound pause awaiting a human decision. Only a step's latest approval can be a grant.

Approver. The interface an operator surface decides approvals through (approver.Approver): show a run's pending approvals, approve or reject one bound to the hash that was shown, or cancel the run, every method addressing a run by id. approver.Local is the implementation over a store, and approver/webhook serves it over signed HTTP. It never resumes a run; that stays in the consumer's process. See Approval Channels.

Blocked. The proxy's answer (BLOCKED) to a mutating call to a tool while another request to that tool has an unknown outcome that no operator has resolved, or while max_pending approvals are already waiting. See MCP Proxy.

Canonical JSON. The form of a JSON value the runtime hashes: object keys in byte order, no insignificant whitespace, every number as its literal was written, and every string by its exact contents in one fixed escaping. agentrt.CanonicalJSON returns it and refuses what the runtime refuses where consumer JSON enters. Approval hashes are computed over it, and the proxy matches requests by it, so 10, 10.0, and 1e1 are three different requests.

Capability. The JSON in an approval describing exactly what would be authorized.

Chain. The events as a hash chain, from v0.5.0. Each event's hash is the SHA-256 of seven netstrings over the previous event's hash, by seq across every run, and the event's own fields as stored, computed in the transaction that writes it. Store.VerifyEvents and agentrt verify find the first event that does not chain. Against whoever can write the database it proves nothing unless a head is kept elsewhere. See Re-checking a Run.

Cursor. The Seq of the last event a follower delivered, from which export.Follower resumes. Seq is assigned in the transaction that commits the event, so it rises in commit order across every run in a database and is never reused. The Cursor interface persists it, in a file (FileCursor) or in memory (MemCursor). See Exporting Events.

Decision. The agent's output for a step: a tool call, completion, or failure.

Driver. The object that runs the loop and exposes start, approve, reject, cancel, and resume. It holds a lease on each run it is executing. Since v0.4.0 it runs on the same code as a gate.

Duplicate rule. The proxy's rule that an identical call to a tool that is not read-only, executed with a known outcome within the repeat window, is refused as DUPLICATE with the earlier outcome. It makes a host's blind retry after a lost response safe, and it also refuses a deliberate repeat. See MCP Proxy.

Event. One row of the append-only audit log.

Gate. The runtime's controls for a loop the runtime does not own (agentrt.Gate, from v0.4.0). 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. A Driver is a gate with an agent. See The Gate.

Grant. An approval that has been approved and not yet acted on. Resume executes it only if it is the step's latest approval, its hash still matches, the request still passes the tool's schema, and policy still agrees. Limits.GrantTTL bounds how long it may wait, and a gate judges it again at Execute.

Head. The newest event of the chain as a seq and its hash. Store.ChainHead reads it, export.Follower.Head gives the one the follower has delivered up to, and agentrt verify -head SEQ:HASH checks a database against one kept elsewhere. It shows the record unaltered only if it was kept where the database's writers cannot reach. See Re-checking a Run.

Hint mismatch. An MCP server annotation that contradicts the operator's classification of a tool. It refuses the tool unless the rule allows the mismatch, and the load report records the override. Annotations can only contradict a classification, never relax it.

Hold. How long the proxy keeps a call open waiting for its approval (hold, 15 seconds by default) before it answers PENDING_APPROVAL, so an operator who decides quickly answers it in the same call.

Interrupted. A step found in flight by a process that did not start it, or whose caller's context was cancelled while its tool ran.

Interrupted side effect. A call that was executing a tool that is not read-only when its process stopped, so whether it took effect is unknown. Without a reconciliation, the run pauses on an approval of kind interrupted_side_effect (agentrt.InterruptedSideEffect); approving runs the same request again, once, on the same step.

Lease. The record on a running run's row of which driver is executing it and until when: an owner (Config.LeaseOwner plus a random suffix) and an expiry, renewed by a heartbeat. Resume of a run leased live by another owner returns ErrRunLeased; a loop that loses its lease returns ErrLeaseLost.

Limit. A cap enforced by the driver with a named terminal reason.

Loop detection. Ending a run when the same tool call produces the same observation a set number of times in a row.

Manifest. What an MCP server presented when an operator pinned it: each tool's name, description, and canonical input schema, with a hash of the schema and of the description, and the server's annotations as received. The operator reviews it, stores it, and passes it to Load.

MCP host. The application that runs a model and gives it tools from MCP servers. The proxy is started by a host as one of its MCP servers.

MCP proxy. agentrt-proxy, a local program over stdio, in the nested module proxy, that connects to the real MCP servers through mcp and routes every tools/call a host makes through a gate, one run per call. It governs only calls that go through it. See MCP Proxy.

ModelCaller. The accounting wrapper that is the agent's only handle to a model.

Not re-checkable. What Recheck reports for an evaluation the record cannot rebuild: one made before v0.5.0, which recorded neither the spec nor the view; a policy error, which recorded no evaluation; or a step.policy event or step cut by the page reads because it is longer than MaxPageText. A report with any is not Complete. See Re-checking a Run.

Observation. What a step produced for the agent to consider next.

Observer. A function that receives every event after commit.

Origin. Decision.Origin: who proposed a step, one of model, plan, or operator. The runtime records it and attaches no behaviour to it, and policy does not see it. Empty is not stored. Nothing sets plan yet. See The Gate.

Outcome class. What a bench outcome means for safety: success, safe non-success, or unsafe. The class, not the outcome's name, decides whether a mode is disqualified; one unsafe outcome disqualifies it. See Measuring Agents.

Page read. A store read for a front end that may not trust the database (ListRunsPage, GetRunCapped, ListStepsPage, ListApprovalsPage, ListEventsPage, PendingApprovalIDsOf): at most the rows asked for, every text column capped at MaxPageText, and a total from COUNT.

Pin. Recording an MCP server's tool set in a manifest the operator reviews and stores, so that a later change to a schema or a description refuses that tool rather than reaching the model. The pin is computed from the raw bytes the server sent, with keys matched exactly, so no float64 rounding or case-insensitive match can hide a change.

Policy. Code that answers allow, deny, abort, or require approval for each validated tool request.

Policy form. PolicyJSON, the form of a JSON value a policy is handed for a request's arguments and its tool's schema, from v0.5.0: object keys sorted, no insignificant whitespace, numbers as written, and strings escaped only as JSON requires, so &, <, and > are left as they are. It is the canonical form without HTML escaping, and it is the same on the loop, on resume, through a gate, and in a re-check. agentrt.PolicyJSON returns it. Hashes are never computed over it. See Upgrading to v0.5.

Policy identity. What a policy with a PolicyID() string method (IdentifiedPolicy) calls itself, recorded on each step it evaluated and in that step.policy event, so a re-check can say whether the policy given is the one that decided. Empty for a policy without the method. The proxy's is Config.PolicyID.

Presentation. The JSON in an approval meant for the human reviewer.

Provider name. What an adapter's Name() reports, <provider>:<model>. It keys the price table and the recording directory, and Config.Name overrides it for a consumer whose recordings already use another name.

Pseudo decision kinds. truncated and no_tool_call: the kinds a model agent records when the model asked for nothing executable. They are deliberately not valid decisions, so the driver records an invalid_decision observation, the step counts against the failure limit, and the next render nudges the model.

Recheck. agentrt.Recheck: replaying each policy evaluation a run recorded through a policy, rebuilt as the policy saw it, and reporting which it answers differently. It proves the policy's answer, not the tool's behaviour or the record's integrity. testkit.Recheck does it in a test and agentrt-proxy recheck for the proxy's calls. See Re-checking a Run.

Reconciliation. The consumer's structured answer about an interrupted step.

Repeat window. The proxy's repeat_window, ten minutes by default, within which an identical executed call is a duplicate and a rejected or expired request is not asked for again. 0s turns both off.

Replay. Serving recorded model responses keyed by a hash of the exact request.

Request key. What the proxy matches calls by: the SHA-256 of the registered tool name and the canonical JSON of the arguments. Arguments the runtime refuses as JSON have none.

Rule. An operator's classification of one MCP server tool: its side-effect class, a call timeout, and optionally a description override, denied or fixed parameters, a rename, or permission to register despite a hint mismatch.

Run. One execution toward a goal under limits.

Sanitise. Escaping text a model or a server chose before it reaches a terminal (trace.Sanitize): control characters, bidirectional overrides, invisible characters, line and paragraph separators, and the tag block become visible escapes, and piles of combining marks are cut.

Served error. A ServedError from a model adapter: the provider served the request, and billed it, but the reply cannot be used. The accounting caller charges the usage it carries and does not retry.

Session. One hold on a run by a gate, from Begin or Attach until the run pauses or ends, the lease is lost, a call fails, or Close. It holds the run's lease, renewed by a heartbeat, and has at most one open step. In the proxy, "session" is also the name in its configuration that begins every run id, <session>.<suffix>. See The Gate.

Shown hash. The hash of an approval as the operator saw it, passed back with the decision (ApproveShown, RejectShown, approver.Decision.Hash). The decision is refused with ErrApprovalChanged if the stored approval no longer hashes to it, and the comparison is made inside the deciding transaction.

Side-effect class. Read-only, local mutation, remote mutation, or destructive.

Span. A unit of an OpenTelemetry trace. export/otel makes one for a run, each of its steps, each model attempt, and each approval wait, with ids derived from the run's own, so a restarted exporter or a run resumed later continues the same trace. See Exporting Events.

Spec hash. The hex SHA-256 of the canonical JSON of a whole ToolSpec, Timeout and Terminal included. A tool_call step records it (Step.SpecHash), the spec is stored once under it in tool_specs, and Store.ToolSpec reads it back. See Re-checking a Run.

Status tool. The one tool the proxy serves of its own, gate_status by default, which reports pending approvals and what came of an approved request. It executes, decides, and writes nothing.

Step. One turn of the loop: decide, validate, police, execute, observe.

Taxonomy. A consumer's closed set of outcomes for scoring an agent, in report order, each with a class and optionally the expectation its denominator is taken over. The names stay the consumer's. See Measuring Agents.

Terminal reason. Why a run ended: goal completed, a limit, an abort, a rejection, a conflict, or an error.

Terminal tool. A tool whose success completes the run with its result.

Transient error. A model error worth retrying, possibly carrying the provider's Retry-After.

Trial. One run of one scenario in one mode, for one model and repeat: a row of a bench result file, scored into exactly one outcome of the taxonomy or excluded with a reason, in which case it is in no denominator.

Unknown outcome. In the proxy, the state of a mutating call that was cut off by a crash while executing, timed out, or failed with no answer from the server, so it may have taken effect. It waits on an interrupted_side_effect approval and the call answers UNKNOWN_OUTCOME or INTERRUPTED; the identical request is never run again on the policy alone.

Unusable usage. Token counts a provider reported that cannot be charged: negative, too large to hold, not an integer, or more cached input than input. The attempt is charged the conservative estimate instead, the reply is not used, and the run fails as model_unavailable.

Verdict. What OpenStep.Propose answers with: VerdictAllowed, VerdictDenied, VerdictPending, or VerdictEnded. Attach returns one too, for the recorded request of an approved step. See The Gate.