# Glossary

OMA's documentation uses a handful of terms in a specific, narrow sense. This page defines them in one or two sentences each and points at the page that owns the full behavior. Definitions here never add meaning: if this page and a linked page disagree, the linked page wins.

| Term | Definition |
|---|---|
| **Adaptive recovery** | Opt-in runtime plan repair. With `recovery: { mode: 'repairable' }`, an application-owned policy (`onTaskOutcome`, or a `Replanner` object with a `replan()` method) is called at each task-outcome barrier and may return an append-only `PlanPatch`; bounded by `maxPlanRevisions` and `maxAddedTasks`. See [adaptive recovery](adaptive-recovery.md). |
| **Checkpoint** | An opt-in durable snapshot of run state written at safe in-flight agent boundaries and after each completed task, through any `MemoryStore`. `restore()` reads one back and continues the same logical run with a new attempt. See [checkpoint and resume](checkpoint.md). |
| **Consensus** | A proposer-and-judge refutation loop: judges try to refute a proposed answer over up to `maxRounds`, and the answer is accepted once `quorum` judges accept (default `ceil(judges.length / 2)`). Available as `runConsensus()` and as the per-task `verify` hook. See [consensus](consensus.md). |
| **Consequential tool** | A tool whose author declared `consequential: true`, meaning the grant permits real side effects. Exactly three built-ins carry it: `bash`, `file_write`, and `file_edit`. OMA never infers it from prompts or arguments. See [tool configuration](tool-configuration.md#consequential-tools-on-undeclared-runs). |
| **Context strategy** | The `AgentConfig.contextStrategy` policy that shrinks a growing conversation before it hits a token ceiling: `sliding-window`, `summarize`, `compact`, or `custom`. See [context management](context-management.md). |
| **Coordinator** | The temporary agent `runTeam()` builds to decompose a goal into a task DAG, assign tasks to roster agents, and afterwards synthesize the final answer. It plans once and never chooses runtime execution order. See [coordinator](coordinator.md). |
| **Declared governance roles** | A structural `runTeam()` declaration (`governanceIntent` plus `requiredRoles` and optional `requiredOrder`) that replaces coordinator decomposition with one task per named roster role. The goal text is never inspected to pick the topology. See [tool configuration](tool-configuration.md#declared-governance-roles-in-runteam). |
| **Delegation** | One agent handing a sub-task to another roster agent through the built-in `delegate_to_agent` tool and receiving that agent's final text as a tool result. It is registered only during orchestration and still requires an explicit grant. See [tool configuration](tool-configuration.md#delegation-with-delegate_to_agent). |
| **Durable approval** | An approval boundary that suspends a checkpointed run, returns an immutable request to the application, and resumes from the same reviewed content after a process restart. Triggered by returning `{ action: 'suspend' }` from an approval gate. See [durable approvals](durable-approvals.md). |
| **Egress policy** | `egressPolicy`, a declarative restriction on the network requests OMA can identify and guard before a built-in LLM adapter opens them. It is an application configuration control, not a process sandbox or host firewall. See [egress policy](egress-policy.md). |
| **EvalSet** | A named, versioned collection of evaluation cases built with `defineEvalSet()` and executed by `runEvalSet()`. Case ids must be unique and the returned set is deeply frozen. See [evaluation](evaluation.md#load-evalsets-and-write-reports). |
| **Evaluation gate** | A pass/fail rule applied to an evaluation report so CI can block a change. It is separate from a run's own verification: low scores alone do not fail a run unless a gate is configured. See [evaluation in CI](evaluation-ci.md#gate-quality-in-ci). |
| **Execution receipt** | A compact record of what the runtime actually executed, derived by `buildExecutionReceipt(result, trace?)`: mode, roles executed, execution order, dependency edges, independent-review facts, usage, and duration. It performs no I/O. See [observability](observability.md#execution-receipts). |
| **Execution routing** | The decision of whether a `runTeam()` goal runs as a single agent or a coordinator-planned team. Deterministic by default; `strategy: 'hybrid'` adds one semantic profiling call. Orthogonal to model routing. See [execution routing](execution-routing.md). |
| **External backend** | An agent whose work is performed by a local subprocess instead of OMA's LLM runner: `process` for a generic command, `acp` for an Agent Client Protocol coding agent. It is a full team member in the task DAG but the runner's tool loop and sandbox do not apply to it. See [external agents](external-agents.md). |
| **Governance conclusion** | The post-execution verdict `satisfied`, `unsatisfied`, or `not-applicable` on `TeamRunResult.governanceConclusion`, computed by comparing a `required` declaration against the execution receipt. It does not rewrite `success`, so governance-sensitive callers must read it explicitly. See [observability](observability.md#post-execution-governance-conclusion). |
| **Model routing** | Opt-in `modelRouting` rules that send different phases of one orchestration (coordinator, synthesis, worker, delegated, and more) to different models without mutating the team config. See [model routing](model-routing.md). |
| **Plan artifact** | The serializable `PlanArtifact` produced by `createPlanArtifact()` from a plan-only result: plain JSON you can diff, edit, and replay through `runFromPlan()` without calling the coordinator again. See [plan replay](plan-replay.md#what-the-artifact-contains). |
| **Run identity** | The `{ runId, attempt, traceId, rootSpanId, links? }` object every top-level execution returns. `runId` is a caller-supplyable logical identifier; each attempt gets fresh trace ids. It travels with `status`, whose `code` is one of `ok`, `error`, `cancelled`, `timeout`, `budget_exhausted`, `rejected`, `suspended`, or `skipped`. See [observability](observability.md#run-identity-and-outcome). |
| **Run journal** | An opt-in, append-only log of what happened inside one run, including which content blocks the model actually saw and what a context strategy replaced. It is an audit trail, not the recovery mechanism. See [run journal](run-journal.md). |
| **Run Viewer** | A self-contained static HTML page rendered by `renderRunViewer()` from a finished run: a task DAG plus a span waterfall. A developer inspection artifact, not a live dashboard or a store of run state. See [run viewer](run-viewer.md). |
| **Sandbox root** | The per-agent working directory (`AgentConfig.cwd`, else `OrchestratorConfig.defaultCwd`, else `<process.cwd()>/.agent-workspace`) that built-in filesystem tools resolve every path inside, symlinks included. `bash` is not covered by it. See [sandbox and shell](sandbox-and-shell.md#filesystem-working-directory). |
| **Scheduler** | The component that decides which ready task goes to which agent at runtime, after the plan is fixed. Its assignment strategy (`round-robin`, `least-busy`, `capability-match`, `dependency-first`, or `composite`) ranks only within the set of agents that already satisfy the task's hard requirements. See [task scheduling](task-scheduling.md#assignment-strategies). |
| **Scorer** | A named, versioned function that grades one output and returns a finite score from 0 through 1, optionally with `pass`. A scorer that throws or times out produces `status: 'scorer_error'` and is excluded from aggregates rather than scored zero. Scorers also run against a sampled share of live runs when online sampling is configured. See [evaluation](evaluation.md#scorers). |
| **Shared memory** | An optional team-wide key-value store so later agents can read earlier agents' findings. Keys are namespaced as `<agentName>/<key>` before reaching the backing `MemoryStore`. See [shared memory](shared-memory.md). |
| **Shell executor** | The `ShellExecutor` implementation the granted `bash` built-in delegates to, defaulting to `LocalShellExecutor` on the host. Swapping it changes where a command runs; it does not grant the tool. See [sandbox and shell](sandbox-and-shell.md#shell-executors). |
| **Simple-goal short circuit** | The `runTeam()` path that skips coordinator decomposition and synthesis and dispatches straight to one agent when the routed topology is Single. It also skips `delegate_to_agent` registration and `onPlanReady`. See [coordinator](coordinator.md#the-simple-goal-short-circuit). |
| **Structured handoff** | A task opting into `dependencyPayload: 'structured'` (or `'both'`) so its prompt receives canonical JSON derived from a dependency's validated `structured` result instead of, or alongside, raw narrative output. A missing or non-serializable value fails the dependent task rather than falling back. See [task scheduling](task-scheduling.md#task-results-and-dependency-payloads). |
| **Structured input** | Passing an `LLMMessage[]` or `ContentBlock[]` to an agent instead of a plain string, so a turn can carry images, files, and tool results. A content block is one element of that array, typed by its `type` field. Text-only external backends reject it. See [structured input](structured-input.md). |
| **Task DAG** | The directed acyclic graph of tasks a run executes, with edges from each task's `dependsOn`. It is produced by the coordinator, supplied explicitly to `runTasks()`, replayed from a plan artifact, or declared by governance roles. A failed task cascades to its dependents while independent branches continue. See [task scheduling](task-scheduling.md#event-driven-execution). |
| **Tool gate** | The optional `onToolCall` middleware that decides one specific invocation after Zod validation and before execution, returning `allow`, `deny`, or `suspend`. A denial becomes an error `ToolResult`, and a throwing or invalid gate fails closed. It is a coordination layer, not a sandbox. See [tool configuration](tool-configuration.md#per-call-gating-with-ontoolcall). |
| **Tool grant** | Permission for one agent to call one tool. Built-in tools are default-deny and are granted only through `tools`, `toolPreset`, or `defaultToolPreset`; registering a custom or runtime tool is itself the grant. An ungranted call returns an error result instead of executing. See [tool configuration](tool-configuration.md#built-in-tools-are-opt-in-default-deny). |
| **Tool preset** | A named bundle of built-in tool grants: `readonly`, `readwrite`, or `full`. It is a shorthand for an allowlist, not a separate permission layer. See [tool configuration](tool-configuration.md#tool-presets). |
| **Trace sink** | A destination for `TraceRecord` objects, the immutable span-start, span-event, and span-end rows a run emits. A sink such as `BatchingTraceSink` batches records and hands them to an exporter, which delivers them elsewhere and reports how much of the batch landed. The application owns their flush and shutdown lifecycle. See [observability](observability.md#sinks-exporters-and-ownership). |
| **TraceStore** | A queryable store of completed runs built from trace records, with `getRun()`, `queryRuns()`, retention, and opaque cursors. `InMemoryTraceStore` and `FileTraceStore` ship with the framework. Losing it must never roll back a durable run. See [observability](observability.md#tracestore-query-and-reference-storage). |