Glossary

Definitions of the core terms used throughout the mono-agent docs and config. Each entry is one to three sentences; most link to the page that covers the concept in depth. Where a term maps to a config key, the exact key and MONO_AGENT_* env var are shown.

A2A

The Agent-to-Agent protocol: a JSON-RPC + REST wire format (with optional streaming and bearer auth) for one agent to discover and call another over HTTP. mono-agent can act as an A2A provider (config.provider.* under the @mono-agent/a2a-adapter plugin entry) and as an A2A consumer (config.consumer.* under the same plugin entry). See A2A channel and the A2A consumer (programmatic).

Adapter

A package that bridges one transport (Slack, Telegram, WhatsApp, etc.) to the responder. @mono-agent/*-adapter packages are composed by @mono-agent/agent-app and own their own per-conversation admission, attachment downloads, and outbound delivery. See Channels.

Agent Card

The discovery document an A2A provider publishes describing its name, version, provider org, and advertised skill. It is populated from plugin config.agent.* and config.skill.* and is what remote consumers fetch before calling you. See A2A channel.

Backend

The Pi runtime that actually runs the model. mono-agent is Pi-only: every provider (openai-codex, anthropic, opencode-go, local Ollama/LM Studio, and the rest of the Pi catalog) runs through the same SDK runtime and provider bridge, selected through the model reference. See Providers.

Bloat guard

The automatic 256KB truncation of oversized tool output. Text-only overflow retains a UTF-8-safe head/tail sample inside balanced untrusted framing; image, binary, and mixed overflow remains summary-only. Each original block is also offered to a best-effort per-run sink under artifacts.dir/tool-output/<runId>/. The hourly artifact sweep bounds those raw, access-controlled run directories with artifacts.retention, while active, uncertain, or recently modified runs are kept. See Tools and guards.

BuJo

The richest memory tier (memory.mode: "bujo"), modeled on the Bullet Journal method: a raw audit outside recall, bounded LLM curation (one extraction plus at most one batch reconcile), an entity graph, scheduled lightweight consolidation, a living index.md, and a retired empty future-log.md stub. It strictly requires an embeddings provider and a chat model. See Capture and recall.

Channel driver

The composable factory behind an adapter (e.g. createTelegramChannelDriver, or a package-root createChannelDriver() loaded from channels.plugins[]) that wires a transport’s streaming, message texts, and activity indicators to the responder. Stream/message tuning is configured here (coverage: code), while external channel packages can be loaded by config. See Write your own channel adapter.

Context compaction

When a turn approaches the model’s context window, the pi bridge drives AgentHarness.compact() — proactively at a model-window-derived trigger and reactively with one re-prompt only after a preview proves positive reduction. Rejected previews and empty or output-truncated summaries are not persisted. Summary preparation preserves bounded tool-result tails, confirmed built-in file operations and a supplemental focus on active constraints and unfinished work. Operation accounting separates summary cost from assistant requests. Pi supports native checkpoint/overflow compaction, which mono-agent deliberately disables. Configure the adaptive policy through runtime.compaction.*; numeric and generic provider overflows lower a learned process-local ceiling. Runs report request estimates and before/after effectiveness. Persistent overflow is context_limit and may advance to the next configured fallback. See Tools and guards.

Entity graph

A BuJo-tier structure that tracks the people, projects, and things explicitly associated with individual curated memories and their relationships. Explicit MemoryRecall may expand one deterministic hop; automatic recall stays direct-only. It is built only in memory.mode: "bujo". See Capture and recall.

Fail-closed

The default-deny posture. It survives in two places: the programmatic harness default for code-defined agents (failClosedToolPolicy() — a harness built with no policy exposes no tools; coverage: auto), and the sandbox stance (sandbox.fallback: "fail-closed" refuses to run rather than falling back to the host). Note the config default is the opposite — an omitted tools.allowedTools allows every tool (tool-policy.allow-all); a deliberate chat-only agent uses an explicit tools.allowedTools: []. See Tool policy and Sandbox.

Fallback router

The retry layer that walks ordered canonical {model, effort?} routes after fallback-eligible provider/auth failures. It records failover history and keeps provider sessions only on the primary’s first attempt. Retries and backups use bounded transcript snapshots; on warm failover they lack earlier conversation history. A retry/backup answer rotates the coordinated durable epoch and the next turn cold-reseeds; see fallback sessions. Configured via runtime.fallbacks (MONO_AGENT_FALLBACKS_JSON); the legacy runtime.fallbackModels CSV form is retired and is now rejected at load, each surface naming its own repair: the JSON key fails with `runtime.fallbackModels` was replaced by `runtime.fallbacks: [{ "model": "..." }]`, and MONO_AGENT_FALLBACK_MODELS fails with `MONO_AGENT_FALLBACK_MODELS` was replaced by `MONO_AGENT_FALLBACKS_JSON`.

{
  "runtime": {
    "model": "openai-codex:gpt-5.6-terra",
    "fallbacks": [
      { "model": "anthropic:claude-sonnet-4-6", "effort": "xhigh" },
      { "model": "ollama:gemma4:31b" }
    ]
  }
}

See Fallback.

Harness

The execution engine (@mono-agent/agent-harness) that runs a single turn against a provider, applies tool policy and guards, drives compaction, and returns an explicit result or failure object (it never fakes success). The run path begins at responder.respond. See Tools and guards.

Model reference

The string that names a provider and model together, in the form <provider>:<model>. Examples: openai-codex:gpt-5.6-terra, opencode-go:kimi-k2.6, anthropic:claude-sonnet-4-6, ollama:gemma4:31b. A legacy pi: prefix is canonicalized away. Set via runtime.model (MONO_AGENT_MODEL). See Providers.

OpenInference

The semantic-convention vocabulary mono-agent uses when exporting traces (openinference.span.kind AGENT/LLM/TOOL/CHAIN, input.value/output.value, openinference.project.name). It is what makes Phoenix render runs as a semantic timeline. See Phoenix and backfill.

Provider session

A continuous, per-conversation session against the provider, kept warm and evicted after idle time so follow-up turns resume without re-sending full history. Configured via runtime.session.mode and runtime.session.idleTimeoutMs (MONO_AGENT_SESSION_MODE, MONO_AGENT_SESSION_IDLE_TIMEOUT_MS); pi-native sessions can be persisted to JSONL via providers.piNative.piSessionsRoot. See Sessions and concurrency.

Rapid-log

The deterministic single-line host observation written after a completed turn. Lite/Journal store it in the canonical daily log (Journal hash-deduplicates and embeds in the background); BuJo stores it in a separate raw audit outside recall, before optional bounded curation. Controlled by memory.writeMode (MONO_AGENT_MEMORY_WRITE_MODE). See Capture and recall.

Responder

The top-level entry point that takes an inbound request and produces a reply, delegating to the harness for execution. It is what channels and cron call (responder.respond), and what you build programmatically with createConfiguredAgentResponder. See Composition.

Consolidation

A scheduled, projection-only BuJo maintenance pass run by the in-app scheduler (no external cron needed): it refreshes index.md, keeps the retired future-log.md stub empty, and reports exact-normalized duplicate groups. It never decays static canonical salience or automatically supersedes, deletes, or rewrites canonical memories. Tune it via memory.consolidation.*; the default cron is 0 */2 * * *. See Consolidation.

RRF

Reciprocal Rank Fusion — the method the journal and BuJo tiers use to combine BM25 keyword results with vector results into one hybrid recall ranking (memory.mode: "journal" and above; requires an embeddings provider). See Capture and recall.

Runtime bridge

The provider-specific glue (the pi-native bridge) that translates harness operations into a provider’s API: it drives compaction, applies retry/session behavior, and emits the provider_bridge_latency event separating provider/tool/IO time from harness overhead. See Providers.

Salience

Static 0..1 importance metadata stored with canonical journal and BuJo memories. Recall uses salience only as a small tie-breaker after RRF and evidence strength; age, last access, and access counts do not decay or otherwise alter it. See Capture and recall.

srt

The sandbox runtime that wraps executed commands when sandbox.mode: "native" is set. On macOS, mono-agent sandbox setup installs the pinned runtime into a private user cache; sandbox check proves real enforcement. Missing or corrupt SRT follows sandbox.fallback (default fail-closed); a corrupt managed install never falls back to PATH.

{
  "sandbox": { "mode": "native", "fallback": "fail-closed" }
}

Env: MONO_AGENT_SANDBOX_MODE, MONO_AGENT_SANDBOX_FALLBACK. See Sandbox.

The native srt contract applies to Pi-owned mono-agent tools, which is every route. A route that cannot enforce those scopes is rejected rather than run with SRT silently not covering it.

Trace source

The label/id identifying where a run originated (which channel or cron job), used to name the destination project on export (openinference.project.name defaults to the trace source). See Artifacts and traces.

Related references

• Feature matrix — every capability and its coverage type
• Config blueprint — annotated mono-agent.config.json
• Environment variables — every MONO_AGENT_* override