open-multi-agent/docs/glossary.md

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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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 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.
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.
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.