Configuration Reference

Authoritative reference for every YAML configuration key recognized by the Nexus engine and its plugins. Tables are derived from each plugin’s Init() (and any parser helpers it calls) — not from prose docs. If you change a config key in source, update this page in the same commit.

Maintenance rule. Any addition, removal, rename, default change, or type change to a configuration key — at the engine level or in any plugin — must be reflected in this file. Per-plugin pages may add narrative, but this page is the single source of truth.

Conventions

• Type column uses YAML-native names (string, int, bool, float, duration, list, map). duration is parsed by Go’s time.ParseDuration (e.g. 30s, 1m, 5m).
• Default column shows the value used when the key is absent. *(none)* means no value is set; *(required)* means the plugin will fail to start without it; *(env)* means the value is read from an environment variable.
• Path expansion. Every filesystem path supplied via configuration — engine sessions.root, plugin path, dir, file, cache_dir, scan_paths, system_prompt_file, schema_file, patterns_file, word_files, base_dir, working_dir, path_dirs, ingest watch[].path, etc. — is funneled through engine.ExpandPath. Bare ~ resolves to the user’s home directory; ~/foo resolves to <home>/foo. Relative paths are resolved against the engine’s working directory and not modified.

Validation

Configuration is validated strictly at boot, after YAML loading and before any plugin’s Init() runs. The engine compiles the top-level schema plus every active plugin’s schema (when the plugin advertises one) and validates each config block against it. Validation errors abort boot — they are aggregated across every plugin so a single boot attempt surfaces every issue at once, sorted, with the offending key path on each line:

config validation failed:
  - plugins.nexus.gate.token_budget.warning_threshold: unknown key "warning_threshold"
  - plugins.nexus.tool.web.timeoutt: unknown key "timeoutt" (did you mean "timeout"?)
2 errors; aborting boot

Unknown keys fail boot. Plugin schemas declare additionalProperties: false at every object level, so a typo in a key name is a hard error rather than a silently-ignored value. The validator emits a “did you mean” suggestion when a close match exists in the schema’s declared keys (Levenshtein distance ≤ 3 and strictly less than half the candidate’s length). This guarantees that the only keys you can write in YAML are the ones the engine actually reads — silent typos are not possible for plugins that ship a schema.

Deprecated keys log a warning but do not fail boot. Schemas mark these with deprecated: true. Move off the key when convenient; deprecation warnings are the engine’s signal that a future minor release may delete the shim.

Plugins without a schema (legacy or third-party) are skipped with a debug log. They are not blocked from booting. The engine’s own top-level keys (core, engine, capabilities, plugins.active, journal) are always validated against the engine schema.

Schema authoring

Plugins expose their schema by implementing the optional engine.ConfigSchemaProvider interface (defined in pkg/engine/config_validation.go). Conventions:

• The schema lives at plugins/<id>/schema.json and is //go:embed-ed by a small schema.go in the same package; the plugin’s ConfigSchema() method returns the embedded bytes.
• Schemas declare "$schema": "https://json-schema.org/draft/2020-12/schema" and must set "additionalProperties": false on every object level so unknown keys are caught.
• Mark deprecated keys with "deprecated": true (a sibling of type, description, etc.). The validator walks the schema once and warns when a deprecated key is present in the user’s config.
• The schema is canonical for the plugin’s config map — what Init() actually reads. Schema drift from real consumption is a bug; the smoke test in pkg/engine/configs_smoke_test.go validates every shipped YAML against every active plugin’s schema and is the canary for that drift.

Top-level structure

core:           # engine-level settings
engine:         # engine resilience knobs (shutdown drain, ...)
capabilities:   # capability → plugin-ID pinning (optional)
journal:        # durable per-session event log (always on; tunables only)
plugins:
  active: []    # plugin IDs (with optional /instance suffix)
  <plugin.id>:  # per-plugin config map
    key: value

Core engine

core

core.models

Maps role names → model configurations. Roles can be:

• single model — map with provider, model, max_tokens,
• fallback chain — list of single-model maps (tried in order on non-retryable error or exhausted retries; coordinated by nexus.provider.fallback),
• fanout role — map with fanout: true and a providers: list (dispatched in parallel by nexus.provider.fanout).

Example:

core:
  models:
    default: balanced
    reasoning:
      provider: nexus.llm.anthropic
      model: claude-opus-4-7
      max_tokens: 16384
    balanced:
      - provider: nexus.llm.anthropic
        model: claude-sonnet-4-6
        max_tokens: 8192
      - provider: nexus.llm.openai           # fallback
        model: gpt-4o
        max_tokens: 8192
    panel:
      fanout: true
      providers:
        - provider: nexus.llm.anthropic
          model: claude-sonnet-4-6
        - provider: nexus.llm.gemini
          model: gemini-2.5-pro

A role missing from core.models whose name contains a hyphen is treated as a raw model ID with no provider (backward-compat). Otherwise resolution fails.

Engine

Engine-level resilience knobs that don’t belong under core (which is for runtime settings like log level and tick interval) and aren’t journal-specific.

engine:
  shutdown:
    drain_timeout: 30s
  config_watch:
    enabled: false      # opt in to fsnotify hot-reload
    debounce: 1s

Hot reload

The engine supports applying a new config to a running process without restarting any unaffected plugins. The flow is two-phase:

1. Validate phase (atomic). The new config is run through the same schema validation as boot; capability provider identity is pinned (a plugin advertising memory.history cannot be replaced by another provider mid-flight); the diff between current and new active sets is computed. Any failure here returns an error and leaves the engine untouched.
2. Apply phase (best-effort). The diff is walked: removed plugins shut down, in-place reloaders accept their new config, restart-only plugins are torn down and re-initialized, and added plugins run the full lifecycle. Engine-level fields (drain_timeout, config_watch) are swapped atomically before per-plugin work.

A reload that fails midway through the apply phase logs the error and surfaces it to the caller; the engine is left in a best-effort consistent state. True rollback is not attempted because “undoing” a Shutdown is not generally possible.

Triggers:

• SIGHUP to the CLI process re-reads the original -config path and applies the result. (SIGINT and SIGTERM continue to terminate the engine.)
• POST /admin/reload-config on the browser plugin’s HTTP server. Body is empty (re-read original path) or {"path": "/abs/path/to/new.yaml"} for ad-hoc paths. No auth layer yet — alpha-only; front with a reverse proxy if exposed.
• fsnotify watcher on the original path. Off by default; opt in via engine.config_watch.enabled: true. Debounced by engine.config_watch.debounce to absorb editor save bursts.

Plugin opt-in: ConfigReloader. A plugin that implements

type ConfigReloader interface {
    ReloadConfig(old, new map[string]any) error
}

receives the in-place hook on a config-only change instead of going through Shutdown → Init → Ready. Implementations must be transactional from the bus’s perspective: returning an error must leave the plugin in its prior state. Plugins that don’t implement the interface go through the full restart path; both work, the in-place hook is just an optimization for plugins where a restart would drop in-progress work (active streams, bound listeners) the operator would notice.

Capability provider identity is pinned. Hot-reload rejects any config change that would resolve a currently-bound capability (e.g. memory.history) to a different concrete provider. The session has in-flight state bound to the existing provider; a silent swap would strip the operator’s history. Restart the engine to change capability providers.

Journal

The journal is the engine’s always-on durable event log. Every dispatched bus event lands as a JSONL envelope at <sessions.root>/<session_id>/journal/events.jsonl with a monotonic per- session sequence number, the parent dispatch’s seq (best-effort), and the veto outcome for before:* events. The journal cannot be disabled — it is core infrastructure underpinning crash recovery, deterministic replay, and observability projections.

journal:
  fsync: turn-boundary       # turn-boundary | every-event | none
  retain_days: 30
  rotate_size_mb: 4
  exclude_events:            # event types the journal must not record
    - core.tick

Disk layout

~/.nexus/sessions/<id>/journal/
  header.json                 # schema_version, created_at, fsync_mode, session_id
  events.jsonl                # active segment (append-only)
  events-001.jsonl.zst        # rotated, zstd-compressed
  events-002.jsonl.zst
  cache/                      # args-keyed tool result cache
    <tool_id>/
      <sha256>.json           # one file per (tool, canonical_args) pair

Tool result cache

Every tool.invoke / tool.result pair is recorded under journal/cache/ keyed by sha256(tool_id || canonical_args). During replay, the short-circuit helper consults the cache first — same args produce the same result regardless of dispatch order, so replay survives memory-state divergence between the original and replay runs. On cache miss, the helper falls back to the FIFO stash seeded by the coordinator from the journal’s tool.result events.

The canonical args hash sorts keys recursively, so two semantically equivalent argument maps with different key iteration order map to the same cache file.

Journal projections

Plugins that need to derive files from event streams register a projection via Journal.SubscribeProjection(types, handler). The handler fires on the writer’s drain goroutine after the envelope lands on disk, so derived files always lag the durable record by zero envelopes. Projections also drive post-mortem regeneration: journal.ProjectFile(dir, types, handler) walks an existing journal and feeds the same handler — a derived file deleted between runs will rebuild from the journal at the next boot.

The shipped nexus.observe.thinking plugin no longer uses this hook itself: its thinking.step and plan.progress events are already in the journal alongside every other event, so the plugin acts purely as a UI feature flag for shells that want to surface thinking. Custom plugins that need their own derived view should adopt the projection pattern.

Deterministic replay

bin/nexus -config <path> -replay <session-id> re-runs a journaled session without external calls. The Anthropic / OpenAI / Gemini providers and the side-effecting tools (shell, file, code_exec, web, pdf, ask_user), along with the nexus.control.hitl plugin’s hitl.responded events, detect replay mode and emit the next journaled llm.response / tool.result from a FIFO stash seeded from the source journal in seq order. The replay coordinator drives io.input events; the live agent loop reacts as if the inputs were fresh.

Replay produces functional equivalence (same final assistant outputs, same memory state) rather than byte-identical event re-emission. Side- effecting plugins expose a LiveCalls() counter that stays at zero during replay — tests assert this to catch regressions.

Crash recovery

bin/nexus -config <path> -recall <session-id> resumes a session whose journal ended mid-turn. The engine detects the partial turn via coord.IsPartialTurn(), restores conversational memory from context/conversation.jsonl, and re-emits the io.input that started the unfinished turn so the live ReAct loop restarts it.

Phase 3 minimum: the partial turn restarts from scratch rather than mid-step resume. Mid-step resume (replay-stash-short-circuit the completed prefix, then live-fire the unanswered tool.invoke) is a future PR. Re-firing the input after a crash mints fresh seqs that append to the same journal alongside the orphaned partial-turn events; a subsequent --replay of a crash-resumed session sees both the orphaned and the re-fired io.input.

Plugin activation

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.agent.subagent/researcher   # multi-instance suffix
    - nexus.agent.subagent/writer

Each entry in active may be followed by /<instance> to register a second copy of a multi-instance plugin (e.g. subagents). The base plugin ID + instance suffix forms the full ID used for per-plugin config:

plugins:
  nexus.agent.subagent/researcher:
    model_role: reasoning
    tool_name: spawn_researcher

A plugin with no configuration still parses cleanly without an explicit entry, but you may declare an empty map for clarity:

plugins:
  nexus.tool.file: {}
  nexus.observe.thinking: {}

Agents

nexus.agent.react

Source: plugins/agents/react/plugin.go.

Iteration limits are not an agent setting — enforce them with nexus.gate.endless_loop. ReAct’s required capabilities (memory.history, control.cancel, tool.catalog) are auto-activated by Requires() when no provider for those capabilities is already in plugins.active.

Tool choice

tool_choice accepts:

• a string shorthand — tool_choice: required (or auto, any, none),
• a map — tool_choice: { mode: tool, name: read_file },
• a sequence — tool_choice: { sequence: [{ mode: required }, { mode: auto }] } applied per iteration; the last entry sticks.

Dynamic overrides arrive via agent.tool_choice events with duration: once (consumed after one iteration) or sticky (until cleared).

nexus.agent.planexec

Source: plugins/agents/planexec/plugin.go.

Step iteration and step counts are managed internally by the planner plugin that emits plan.result; they are not configured here.

nexus.agent.subagent

Source: plugins/agents/subagent/plugin.go. Multi-instance: register multiple copies via nexus.agent.subagent/<suffix>.

Depends on nexus.agent.react.

nexus.agent.orchestrator

Source: plugins/agents/orchestrator/plugin.go.

Depends on nexus.agent.subagent.

nexus.agent.postures

Source: plugins/agents/postures/plugin.go. Loads AgentPosture YAML files from the configured directories and advertises the posture.registry capability consumed by nexus.agent.delegate. fsnotify watches each directory for live edits; active sub-sessions keep their old posture, new invocations resolve the new one. See Postures for the AgentPosture schema.

nexus.agent.delegate

Source: plugins/agents/delegate/plugin.go. Exposes the delegate tool that the LLM calls to invoke a registered posture. Requires the posture.registry capability (typically provided by nexus.agent.postures). Enforces budgets and recursion depth defined on each posture; results cached by posture version + task + context hash so posture edits invalidate stale entries. See Sub-agent delegation.

nexus.agent.agui_remote

Source: plugins/agents/aguiremote/plugin.go. Surfaces one or more remote AG-UI agents as delegate/subagent targets. Each configured agent registers an LLM-facing tool (default delegate_agui_<name>); when the parent agent calls it, the plugin builds an AG-UI RunAgentInput from the delegated task, runs the remote agent over the AG-UI wire (HTTP POST + SSE) via the reusable AG-UI client, maps the remote run’s event stream onto the Nexus bus (text deltas → io.output; tool activity + message boundaries → subagent.*), and returns the remote run’s terminal outcome as the tool result. Failures (remote RunError, timeout, transport error, auth rejection, unresolved interrupt) surface as a clean tool error. Per-call timeout enforces budget; results are cached by endpoint + task + context hash. See Sub-agent delegation.

Each agents[] entry:

nexus.scene

Source: plugins/scene/plugin.go. Owns the per-session Scene store and registers the scene_create / scene_patch / scene_get / scene_list / scene_delete tools. Every patch is journaled to <session>/plugins/nexus.scene/scenes.jsonl so the replay primitive can reconstruct historical scene state. See Scenes.

No config keys today; activate the plugin in plugins.active and the default tools register at boot.

LLM providers

All providers share the same retry block schema (see “Retry” subtable below).

nexus.llm.anthropic

Source: plugins/providers/anthropic/plugin.go + auth.go, pricing.go, cache.go, thinking.go, multimodal.go, citations.go, structured_outputs.go, files.go, retry.go.

Retry block (shared by all providers)

Pricing override

nexus.llm.openai

Source: plugins/providers/openai/plugin.go.

nexus.llm.gemini

Source: plugins/providers/gemini/plugin.go.

nexus.provider.fallback

Source: plugins/providers/fallback/plugin.go. No plugin-level config — the fallback chain is defined by listing multiple providers under a single role in core.models. This plugin coordinates the re-emission to the next provider on non-retryable errors.

nexus.provider.fanout

Source: plugins/providers/fanout/plugin.go.

A role becomes a fanout role when its core.models entry sets fanout: true; the fanout plugin watches before:llm.request for those roles. For strategy: user, the plugin emits provider.fanout.choose and waits for provider.fanout.chosen from the IO layer.

Search providers (search.provider capability)

Each search-provider plugin handles search.request events and writes results back into the payload. They share the same shape:

Provider defaults:

If multiple providers register the search.provider capability, pin one explicitly via the top-level capabilities: block.

Tools

nexus.tool.shell

Source: plugins/tools/shell/plugin.go. Routes commands through pkg/engine/sandbox so the kernel surface is a single audited boundary.

nexus.tool.file

Source: plugins/tools/fileio/plugin.go. Registers read_file, write_file, check_file_size, list_files, read_image, read_document.

read_image and read_document return a MessagePart on ToolResult.OutputParts; the memory plugin copies parts onto the resulting tool-role Message.Parts so the next LLM request sees the multimodal content. Provider plugins resolve MessagePart.URI = "nexus-blob:<sha>" references from the per-session blob store at ~/.nexus/sessions/<id>/blobs/ when the payload was stored, or use the inline MessagePart.Data when it was inlined.

nexus.tool.catalog

Source: plugins/tools/catalog/plugin.go. No configuration. Provides the tool.catalog capability — a shared registry queried via tool.catalog.query. Required by nexus.agent.react.

nexus.tool.web

Source: plugins/tools/web/plugin.go. Registers web_search, web_fetch, and fetch_page_image. Requires the search.provider capability for web_search. fetch_page_image requires screenshot_provider config — without it, the tool surfaces a clear error at invoke time.

nexus.tool.knowledge_search

Source: plugins/tools/knowledge_search/plugin.go. Requires embeddings.provider and vector.store.

The active embeddings.provider plugin owns the model choice — there is no consumer-side override. Configure the model once on the provider plugin (e.g. nexus.embeddings.openai.model).

nexus.tool.pdf

Source: plugins/tools/pdf/plugin.go. Registers read_pdf. Two modes selectable per call via mode argument or default_mode config:

• text (default) — extract text via pdftotext (poppler-utils). Requires pdftotext on PATH (or pdftotext_bin config).
• document — return the raw PDF bytes as a file MessagePart on ToolResult.OutputParts for native multimodal providers (Anthropic, Gemini). No poppler call. first_page, last_page, and layout arguments are ignored in this mode.

If default_mode is document and pdftotext is missing, the plugin boots; text mode then surfaces an actionable error per call.

nexus.tool.screenshot

Source: plugins/tools/screenshot/plugin.go. Registers take_screenshot. Captures the full screen as PNG and emits an image MessagePart on ToolResult.OutputParts. Capture path is platform-specific:

• darwin: screencapture -t png -x <tmpfile>
• linux: gnome-screenshot -f <tmpfile>, then grim <tmpfile>, then ImageMagick’s import -window root <tmpfile> as fallbacks
• other platforms: emits ToolResult.Error: "screenshot not supported on this platform"

nexus.tool.opener

Source: plugins/tools/opener/plugin.go. Registers open_path.

nexus.control.hitl

Source: plugins/control/hitl/plugin.go. The unified human-in-the-loop primitive. Registers the LLM-facing ask_user tool with an extended schema (prompt, mode, choices, default_choice_id, deadline_seconds) and routes hitl.requested / hitl.responded events between requesters (the tool, gates, memory plugins) and IO surfaces. Replaces the prior nexus.tool.ask. See Human-in-the-Loop plugin docs.

nexus.control.hitl_synthesizer

Source: plugins/control/hitl_synthesizer/plugin.go. Optional companion to nexus.control.hitl that renders context-aware approval prompts via a small/cheap LLM. Advertises the hitl.prompt_synthesizer capability; emitters opt in by setting HITLRequest.PromptSynthesizer = "hitl.prompt_synthesizer" and leaving Prompt empty. Subscribes to before:hitl.requested (canonical vetoable entry point, pointer payload — every in-tree HITL emitter publishes here first) and to hitl.requested as a backward compat fallback for out-of-tree emitters that publish a *HITLRequest pointer directly, ahead of every IO plugin so the rendered text is in place before the operator sees the prompt. Synthesised prompts are cached on disk under <session>/plugins/nexus.control.hitl_synthesizer/cache.jsonl, keyed by (action_kind, sha256(action_ref)). See HITL Prompt Synthesizer docs.

nexus.tool.code_exec

Source: plugins/tools/codeexec/plugin.go. Registers run_code (Go). Two compilers selected via compiler:

• yaegi-host (default) — in-process Yaegi interpreter. Full dynamic bindings (tools.*, parallel.*, skill helpers); no kernel isolation.
• yaegi-wasm — embedded Yaegi runner inside a wazero-managed Wasm sandbox. Capability-gated I/O via nexus_sdk/{http,fs,exec,env}. v1 forfeits tools.*, parallel.*, and skill helpers — the bridge SDK does not surface them.

Multimodal helper (host compiler only): scripts may import "nexus" and call nexus.ReturnImage(data []byte, mimeType string) to attach images to the resulting tool.result (alongside main.Run’s JSON return). Multiple calls stack in script order; the routing follows the same inline / blob-store threshold pattern used by other multimodal tools.

The engine substitutes ${session_id} in any string under the sandbox: block at session start, so per-session host paths can be hard-coded: host: ~/.nexus/sessions/${session_id}/files.

Memory

nexus.memory.simple

Source: plugins/memory/simple/plugin.go. No configuration. Provides memory.history. Unbounded, in-memory, no persistence.

nexus.memory.capped

Source: plugins/memory/capped/plugin.go. Provides memory.history. This is the default memory.history provider auto-activated by nexus.agent.react.

nexus.memory.summary_buffer

Source: plugins/memory/summary_buffer/plugin.go. Provides both memory.history and memory.compaction.

nexus.memory.compaction

Source: plugins/memory/compaction/plugin.go. Provides memory.compaction as an external coordinator (separate from history buffers).

nexus.memory.longterm

Source: plugins/memory/longterm/plugin.go. Provides memory.longterm. Registers LLM tools: memory_write, memory_read, memory_list, memory_delete.

nexus.memory.vector

Source: plugins/memory/vector/plugin.go. Provides memory.vector. Requires embeddings.provider and vector.store.

nexus.memory.tool_result_clear

Source: plugins/memory/tool_result_clear/plugin.go. Live curator that replaces stale tool-result bodies in outgoing LLMRequest.Messages with an inline <tool_result … cleared="true" …/> envelope. The original call/result pairing stays in history so the agent retains the fact of the call. Runs at priority 12 on before:llm.request (after nexus.discovery.progressive).

Emits memory.tool_result_cleared (per cleared call) and memory.curated (stability descriptor for the cache-aware prompt builder).

nexus.memory.tool_def_pruner

Source: plugins/memory/tool_def_pruner/plugin.go. Drops individual tool definitions from outgoing LLMRequest.Tools when they have been idle past unused_turns_threshold. Pairs with nexus.discovery.progressive — progressive scopes by class, this scopes per tool. Runs at priority 14 on before:llm.request.

Emits memory.tool_def_pruned and memory.curated. The MemoryCurated event marks cache_invalidates: true because the tool list is part of the session-cached prefix.

nexus.memory.topic_pruner

Source: plugins/memory/topic_pruner/plugin.go. Detects topic boundaries in user input and emits memory.topic_shift_detected. Two signals are combined:

• Explicit-phrase matching (“different question”, “new topic”, “let’s move on”, …) — cheap, deterministic.
• Embedding similarity drop against the rolling topic centroid — runs only when an embeddings.provider is active.

The plugin does not itself rewrite history; it surfaces the shift so other plugins (summary buffer, compaction) can react. Topic boundaries are journalled for replay determinism.

Emits memory.topic_shift_detected and memory.curated. Same-turn duplicate signals are debounced.

Embeddings

nexus.embeddings.openai

Source: plugins/embeddings/openai/plugin.go. Provides embeddings.provider.

nexus.embeddings.mock

Source: plugins/embeddings/mock/plugin.go. Provides embeddings.provider. Deterministic hash-based vectors; opt-in via plugins.active.

nexus.embeddings.cohere_multimodal

Source: plugins/embeddings/cohere_multimodal/plugin.go. Provides embeddings.provider via Cohere Embed v3 (POST /v2/embed). Multimodal: accepts text and image inputs in a single batch through EmbeddingsRequest.Inputs. Opt-in: registered but not in the default plugins.active list — wire it explicitly when image embeddings are required (e.g. nexus.memory.vector with store_images: true).

For an EmbeddingsInput carrying ImageURI with the nexus-blob: scheme, the plugin resolves bytes via the per-session blob store. When the engine boots without a session (rare, mostly tests), the plugin errors clearly — callers must inline bytes via EmbeddingsInput.Image instead.

Vector store

nexus.vectorstore.chromem

Source: plugins/vectorstore/chromem/plugin.go. Provides vector.store.

Lexical store

nexus.vectorstore.sqlite_fts

Source: plugins/vectorstore/sqlite_fts/plugin.go. Provides search.lexical. BM25 ranking via SQLite FTS5 — pure Go, no CGO. Backing storage comes from the engine’s per-plugin storage capability; the scope: knob picks where the underlying store.db lands.

Each namespace becomes a separate FTS5 virtual table (lex_<safe_namespace>) inside the scoped store.db. The provider auto-creates tables on first upsert; missing-namespace queries return zero results without error.

RAG

nexus.rag.hybrid

Source: plugins/rag/hybrid/plugin.go. Provides search.hybrid — a fusion orchestrator that runs vector + lexical retrieval in parallel and combines results via Reciprocal Rank Fusion or weighted score combination.

Requires embeddings.provider, vector.store, and search.lexical. Per-query LexicalBias (range -1..1) on the hybrid.query event tilts fusion weights without rewriting config — positive favors lexical, negative favors vector.

When search.hybrid is active, nexus.tool.knowledge_search automatically routes through it instead of querying the vector store directly. nexus.memory.vector opts in via recall_via_hybrid: true (off by default because the lexical leg adds latency on every user input).

Rerankers (search.reranker capability)

Three providers ship; activate one (rarely more than one). The hybrid orchestrator’s reranker.enabled: true knob switches them on; without that, plugins can still emit reranker.rerank events directly.

nexus.rag.reranker.cohere

Source: plugins/rag/reranker/cohere/plugin.go. Cohere Rerank v2 API.

nexus.rag.reranker.jina

Source: plugins/rag/reranker/jina/plugin.go. Jina AI Reranker API.

nexus.rag.reranker.local

Source: plugins/rag/reranker/local/plugin.go. Pure-Go TF-IDF cosine reranker. No API calls, no model files, no extra dependencies. Quality is materially below a real cross-encoder; use it for offline / cost-sensitive deployments and as the zero-dep fallback. Future phase will add an ONNX- backed BGE Reranker behind a build tag.

nexus.rag.citations

Source: plugins/rag/citations/plugin.go. Provides rag.citations. Parses citation tags or Anthropic-native source attributions out of LLM responses and emits the structured llm.response.cited event for IO renderers to footnote.

Subscribes to rag.retrieved (emitted by nexus.tool.knowledge_search and nexus.memory.vector) to build the per-turn validation set, then to llm.response to do the parsing. Emits llm.response.cited.

nexus.rag.ingest

Source: plugins/rag/ingest/plugin.go. Backs the nexus ingest CLI subcommand and the rag.ingest event handler.

Requires embeddings.provider and vector.store. When search.lexical is also active, ingest dual-writes each chunk into the lexical store with the same (namespace, doc_id) pair the vector store uses.

To migrate an existing chromem-only corpus to dual-mode: add nexus.vectorstore.sqlite_fts to plugins.active and re-run nexus ingest --lexical=true PATH. The embedding cache short-circuits the vector pass while the lexical store is freshly populated.

I/O

nexus.io.tui

Source: plugins/io/tui/plugin.go. No configuration. Bubble Tea terminal UI.

nexus.io.browser

Source: plugins/io/browser/plugin.go.

nexus.io.agui

Source: plugins/io/agui/plugin.go. AG-UI (“Agent-User Interaction”) serve transport. Clients POST a RunAgentInput to /agui and receive a text/event-stream SSE response (one stream per run), using the pkg/agui wire format rather than the browser/wails Envelope. Safe by default: binds loopback, optional bearer-token auth, and configurable CORS for browser AG-UI clients.

Round-trip: a POST /agui maps the request messages to a Nexus io.input (the trailing user message drives the turn; earlier messages ride as PreloadMessages; threadId is recorded as the session id, runId identifies the turn). The plugin subscribes to the same bus events as the browser transport and translates them to canonical AG-UI SSE: agent.turn.start→StepStarted, llm.stream.chunk→TextMessage*, tool.call/tool.result→ToolCall*, thinking.step→Reasoning*, agent.turn.end→StepFinished/RunFinished. The stream flushes incrementally and terminates at RunFinished (or RunError on failure/disconnect).

Non-canonical events: Nexus bus events with no canonical AG-UI equivalent (workflow.progress, subagent.started/iteration/complete, code.exec.stdout) consistently ride the AG-UI Custom event, with name set to the bus event type and value the JSON-encoded payload. This is a documented superset — conformance clients that only understand canonical events can ignore Custom without losing the run’s canonical lifecycle.

Scope: one in-flight run per listener (single engine/session per listener, mirroring nexus.io.browser). A second POST while a run is active receives a terminal RunStarted+RunError stream rather than interleaving.

Shared state (emit_state: true): the transport tracks the scene store’s scene.created / scene.patched / scene.deleted bus events (each carrying the scene’s full post-mutation content) into a shared-state document keyed by scene_id. A StateSnapshot of the current document is emitted immediately after RunStarted; each subsequent scene mutation during the run emits a StateDelta whose delta is an RFC 6902 JSON Patch from the prior document to the new one, so a client applying the deltas in order reconstructs the snapshot. The document is session-scoped and persists across runs on the listener (a later run’s snapshot reflects scenes created earlier). Inbound state (RunAgentInput.state, same scene-keyed shape) is applied at run start — and on a resume/continuation run — before the initial StateSnapshot, seeding the scene store via a scene_create tool.invoke per scene so the agent observes it through scene_get / scene_list. Conflict semantics are client-state-seeds-then-agent-wins: the client seed lands before the agent’s first turn, then agent-side scene_patch mutations are last-writer and flow back out as StateDelta. See Shared state.

nexus.io.realtime

Source: plugins/io/realtime/plugin.go. WebSocket bidirectional transport for low-latency clients (browser front-ends, native voice clients) that want raw stream.delta deltas, tool previews, voice audio chunks, and cancel envelopes without going through the nexus.io.browser UI hub.

Outbound envelopes (server → client, JSON): stream.delta, stream.end, tool.preview, audio.chunk, cancel.complete, hitl.request.

Inbound envelopes (client → server, JSON): input, audio.chunk, cancel, approval.

No auth in v1. Origin checks and bearer-token validation are tracked follow-ups; operators running this on a public network must front it with a reverse proxy that does its own authentication.

nexus.io.broker

Source: plugins/io/broker/plugin.go. Dial-back IO transport for Nexus instances spawned by the session broker (cmd/nexus-broker). Unlike nexus.io.browser / nexus.io.realtime, which LISTEN, this plugin DIALS OUT to the broker’s instance gateway over WebSocket — the broker is the only listening socket. On Ready it dials broker_addr, sends a register frame keyed by lease_id, announces readiness, and reports the engine session id (for later -recall resume) before bridging IO frames in both directions.

Config keys fall back to environment variables the broker injects at spawn, so operators normally set neither by hand:

Outbound IO messages (instance → broker → client, JSON inside the frame payload): output, stream.delta, stream.end, status, approval.request, hitl.request, cancel.complete.

Inbound IO messages (client → broker → instance): input, approval.response, hitl.response, cancel.

The connection reconnects with exponential backoff until shutdown. On an inbound shutdown frame (sent by the broker for POST /release and later idle/crash teardown) the plugin emits io.session.end, which drives a clean engine Stop that flushes and persists the session before the process exits; the reconnect loop is latched off so the graceful teardown is not undone. There is no auth in the plugin itself — the broker gateway owns lease validation and any transport-level authentication.

nexus.io.voice

Source: plugins/io/voice/plugin.go. Bus-driven voice IO bridge: consumes voice.audio.input.chunk events (typically from nexus.io.realtime), runs simple energy-based VAD plus ASR via the OpenAI Whisper API, and emits io.input. Consumes llm.response, runs TTS via the OpenAI /audio/speech endpoint, and emits voice.audio.output.chunk frames back. Implements barge-in: a speech-energy input chunk arriving while a TTS turn is in flight emits cancel.request{Source: "voice"}.

Local-model providers (local_whisper, faster_whisper, distil_whisper for ASR; kokoro, local_*, *_local for TTS) are recognized by the schema but rejected at Init with a clear error pointing at issue #92, where the local-model bootstrapping work is tracked separately.

VAD energy is computed as RMS over little-endian PCM int16 samples for audio/wav / audio/pcm / audio/l16. For compressed containers (webm/opus, mpeg/mp3) the bytes are not PCM and we fall back to a byte-level energy heuristic until a proper decode is added — flagged with a TODO(#91) in plugins/io/voice/vad.go.

nexus.io.test

Source: plugins/io/test/plugin.go. Non-interactive testing transport.

nexus.io.wails

Source: plugins/io/wails/plugin.go. Wails-native transport. The runtime is installed by the embedder via Hub().SetRuntime() before engine.Boot; this plugin only configures event bridging.

nexus.io.oneshot

Source: plugins/io/oneshot/plugin.go. Scripting/batch mode with JSON transcript output.

Prompt resolution precedence: NEXUS_ONESHOT_PROMPT env > input > input_file

stdin.

Native Realtime API integration — deferred

OpenAI Realtime and Gemini Multimodal Live are entire new wire protocols separate from the standard chat/generate endpoints. They are not part of the multimodal-foundation PR (#93) and are tracked as a follow-up under issue #91. Until they land, voice-mode use the ASR → LLM → TTS pipeline implemented in plugins/io/voice/. See Native Realtime API integration — deferred for the full rationale and follow-up scope.

Observers

nexus.observe.thinking

Source: plugins/observe/thinking/plugin.go. No configuration. Marker plugin: presence in plugins.active lets terminal and browser shells enable thinking-related UI. The events themselves are journaled automatically and can be read live via journal.Writer.SubscribeProjection or post-mortem via journal.ProjectFile.

nexus.observe.otel

Source: plugins/observe/otel/plugin.go. OTLP exporter (one root span per session, one span per event).

nexus.observe.sampler

Source: plugins/observe/sampler/plugin.go. Off by default. Captures a fraction of live session journals (and every failed session when failure_capture is on) into a local directory so the eval pipeline can score them later. The plugin must be both registered (it is — automatically via pkg/engine/allplugins) and listed in plugins.active and configured with enabled: true for any capture to happen. Omitting the config block, or setting enabled: false, makes the plugin a no-op: Subscriptions() returns empty, no bus traffic, no disk writes.

plugins:
  active:
    - nexus.observe.sampler

  nexus.observe.sampler:
    enabled: false
    rate: 0.0
    failure_capture: true
    out_dir: ~/.nexus/eval/samples

The plugin emits an eval.candidate event per capture (payload defined in plugins/observe/sampler/events.go) so downstream tooling — for example, nexus eval list-candidates once it lands — can enumerate fresh samples.

The pluggable Redactor interface (plugins/observe/sampler/redact.go) is the hook for future PII scrubbing. v1 ships only the IdentityRedactor (byte-pass-through). Tests inject custom redactors via the package-private Plugin.SetRedactor API; production runs leave it on the default.

Caveat: rotated journal segments. When a non-identity redactor is configured, the active events.jsonl segment is rewritten line-by-line through it. Compressed *.jsonl.zst rotated segments are byte-copied as-is in v1 — handling them transparently requires zstd round-trips that are deferred to a follow-up.

Planners

nexus.planner.dynamic

Source: plugins/planners/dynamic/plugin.go.

nexus.planner.static

Source: plugins/planners/static/plugin.go. Approval auto-defaults to never (static plans don’t call an LLM).

Workflows

Generic workflow surface

Workflow plugins (currently nexus.workflows.icm; planned to extend to other multi-stage runners) emit a workflow-agnostic event class so IO plugins can render a dedicated progress surface (a sticky panel in the TUI right rail; a status indicator chip in the browser) without subscribing to plugin-specific event taxonomies.

Event: workflow.progress — payload events.WorkflowProgress (pkg/events/workflow.go).

ICM emits workflow.progress alongside its detailed icm.* events: the icm.* family feeds scrollback audit rows; workflow.progress feeds the dedicated status surface. Future workflow plugins can emit only the generic event and inherit the same UI treatment without per-plugin subscriptions.

The TUI (nexus.io.tui) and browser (nexus.io.browser) subscribe to workflow.progress automatically when active.

nexus.workflows.icm

Source: plugins/workflows/icm/plugin.go. File-driven multi-stage workflow runner. A workspace is a folder containing operator.md, workspace.md, and a stages/ tree of contracts; each stage runs as a sub-agent dispatched via the posture registry. Multi-instance: pin distinct workspaces per instance via the nexus.workflows.icm/<suffix> form (e.g. nexus.workflows.icm/script). See docs/src/plugins/workflows-icm.md for the full plugin guide.

Requires the posture.registry capability (provided by nexus.agent.postures). Strongly recommended companions: nexus.control.hitl (human gates + judge approvals), nexus.skills (workspace skills authoring tooling).

Events

Subscribes:

• io.input — entry point. Each input begins a new workflow run.
• hitl.responded — resumes a run paused at a human gate or type: human predicate.

Emits (workflow lifecycle):

• icm.run.started / icm.run.completed / icm.run.halted — overall run boundaries.
• icm.stage.started / icm.stage.completed / icm.stage.failed — per-stage transitions.
• icm.stage.iteration — fires once per loop iteration with the prior iteration’s exit_failures.
• icm.turn — fires once per inner turn with the turn’s validator failures.
• icm.fanout.item — per-item lifecycle in a fan-out stage (active, completed, failed).
• icm.predicate.failed — fires for every predicate evaluation whose verdict is fail.
• plan.created / plan.progress — generic plan surface mirrored for any UI that already renders ReAct plans.
• workflow.progress — engine-generic structured progress (see Generic workflow surface below).
• hitl.requested — human gates and type: human predicates dispatch through HITL.

nexus.skills

Source: plugins/skills/plugin.go. Registers the activate_skill LLM tool.

System

nexus.system.dynvars

Source: plugins/system/dynvars/plugin.go. Registers a system-prompt section at priority 100 that lists runtime variables. Each flag defaults to false — opt-in only.

Control

nexus.control.cancel

Source: plugins/control/cancel/plugin.go. No configuration. Provides the control.cancel capability used by ReAct and other agents to interrupt in-flight work; also handles the /resume slash command via io.input at priority 5 (ahead of memory plugins).

Routers

Plugins that subscribe before:llm.request and rewrite request.Model based on the request’s metadata, tags, or an LLM-classifier judgment. Routers run at priority 50 (metadata) / 45 (classifier) — above gates, below the engine’s tag seeder. Both stand down when the request already carries _target_provider (a fallback retry) or _routed_by (an upstream rule already chose a model).

nexus.router.metadata

Source: plugins/router/metadata/plugin.go. Declarative rules over the request’s Metadata (_source, task_kind, iteration) and Tags (tenant, project, source_plugin, …). First matching rule wins; the terminal default_model / default_role fires when no rule matches.

Each entry under rules:

nexus.router.classifier

Source: plugins/router/classifier/plugin.go. Small LLM judges the difficulty of the user’s most recent prompt and picks one of candidate_roles. The decision is cached by prompt-prefix hash (LRU). Cache hits rewrite LLMRequest.Role synchronously; misses route to fallback_role immediately and warm the cache asynchronously via a probe llm.request tagged _source: nexus.router.classifier.

Discovery

nexus.discovery.progressive

Source: plugins/discovery/progressive/plugin.go. Hierarchical tool discovery — the LLM sees class-level summaries and drills into specific classes via a discover meta-tool. Intercepts before:llm.request (priority 8) and tool.invoke (priority 40).

LLM batch

nexus.llm.batch

Source: plugins/llm/batch/plugin.go. Cross-provider batch coordinator (Anthropic Messages Batches, OpenAI Batch API). Subscribes llm.batch.submit; emits llm.batch.status and llm.batch.results.

v1 limitations (intentional): direct-API auth only (no Bedrock/Vertex/Azure); text-only requests (no multimodal/thinking/caching/citations); single-provider per submit; no cancellation API.

MCP integration

nexus.mcp.client

Source: plugins/mcp/client/. Bridges one or more external Model Context Protocol (MCP) servers into Nexus. Tools land in the catalog under mcp__<server>__<tool>, static resources auto-register as no-arg tools, resource templates become parameterised tools, and prompts surface as slash commands. See docs/src/plugins/mcp-client.md for the user-facing guide.

Top-level keys:

defaults

servers[]

Events

Subscribes:

• tool.invoke — dispatches MCP tool calls for any registered mcp__<server>__* name.
• before:io.input — intercepts slash commands; vetoes the original input, then re-emits a fresh io.input whose PreloadMessages carry the expanded prompt.
• io.session.start / io.session.end — drive lifecycle: session connections.
• mcp.prompts.list — synchronous query that fills events.MCPPromptsList.Prompts so IO plugins can render /help-style listings.

Emits:

• tool.register, tool.result, before:tool.result — the catalog projection.
• io.input — replacement input carrying PreloadMessages after a prompt expansion.
• io.output — system-role error messages when a slash command fails to parse or dispatch.
• mcp.resource.updated — fired when a subscribed static resource changes.
• mcp.tools.refreshed, mcp.prompts.refreshed — bookkeeping events emitted after each per-server reconcile.

Deferred for phase 2 (see issue #98):

• MCP sampling (server-initiated LLM calls).
• OAuth dynamic client registration for the HTTP transport.
• SSE legacy transport.
• Roots beyond the session files directory.

Apps

nexus.app.helloworld

Source: plugins/apps/helloworld/plugin.go. Built-in placeholder agent / proof-of-concept for the bus-bridge pattern.

Gates

Gates are vetoable handlers that subscribe to before:* events and may block or transform them. See .claude/docs/gates.md for the underlying veto mechanics.

Pipeline ordering on before:* events

Handlers on a before:* event run in ascending Priority (lower runs first); dispatch breaks at the first veto. Handlers that share a priority fall back to subscription order — the first Subscribe call runs first, and the bus uses a stable sort so this tiebreak is deterministic across rebuilds and reorders of plugins.active. The engine logs one WARN at boot for every (before:*, priority) tuple shared by two or more handlers — re-space the priorities or accept the registration-order tiebreak knowingly.

The shipped gates encode an explicit policy in their priorities so safety outcomes don’t depend on activation order. The values below are the authoritative pipeline; treat them as a contract when adding a new gate.

before:io.output — mutate-then-veto pipeline:

before:llm.request — cheap-structural → mutators → input-scanners → HITL:

nexus.gate.endless_loop

Source: plugins/gates/endless_loop/plugin.go.

nexus.gate.stop_words

Source: plugins/gates/stop_words/plugin.go. Gates both before:llm.request (user messages) and before:io.output.

nexus.gate.token_budget

Source: plugins/gates/token_budget/plugin.go. Multi-dimensional ceilings (session / tenant / source_plugin) with block, warn, or downgrade-model actions. The legacy single-ceiling shape (max_tokens) still works as a session total-token ceiling.

Each entry under ceilings:

Tenant ceilings persist via app-scope SQLite (~/.nexus/plugins/nexus.gate.token_budget/store.db). Other dimensions are in-memory per session.

nexus.gate.rate_limiter

Source: plugins/gates/rate_limiter/plugin.go. Vetoes before:llm.request when the per-window budget is exhausted; the agent’s gate.llm.retry subscriber re-issues the request after the limiter signals the budget has freed up. The pre-Phase-3 time.Sleep behavior was removed in alpha — there is no compat shim.

nexus.gate.tool_timeout

Source: plugins/gates/tool_timeout/plugin.go. Per-call deadline gate. On tool.invoke it starts a timer; on expiry it emits a tool.timeout observability event plus a synthetic tool.result carrying an error message that names the exact override key. A before:tool.result veto suppresses any late real result for the same call ID so the agent’s pendingToolCalls counter stays consistent. Note: Go cancellation is cooperative — the original tool goroutine may keep running until it honors its own context. The gate’s job is to unblock the agent, not preempt the tool.

Per-tool override keys may be exact tool names (web_fetch) or path.Match-style globs (mcp.*). Resolution: an exact key wins; among glob matches the longest pattern wins; otherwise default_timeout applies.

The synthetic error message format is fixed and intended to be read by operators:

tool <name> exceeded timeout <duration>; raise via gates.tool_timeout.per_tool.<name>: <duration>

nexus.gate.prompt_injection

Source: plugins/gates/prompt_injection/plugin.go. Regex-only — no LLM.

nexus.gate.json_schema

Source: plugins/gates/json_schema/plugin.go. Validates before:io.output against a JSON Schema; on failure, asks the LLM to retry.

nexus.gate.output_length

Source: plugins/gates/output_length/plugin.go. Asks the LLM to retry with a shorter response; allows through after exhausted retries (with a warning).

nexus.gate.content_safety

Source: plugins/gates/content_safety/plugin.go. Built-in checks all default to enabled.

nexus.gate.context_window

Source: plugins/gates/context_window/plugin.go. Triggers compaction via memory.compact.request when the estimated context approaches the limit.

nexus.gate.tool_filter

Source: plugins/gates/tool_filter/plugin.go. Modifies request.ToolFilter on before:llm.request. include takes precedence over exclude.

nexus.gate.approval_policy

Source: plugins/gates/approval_policy/plugin.go. Policy-driven approvals on before:tool.invoke and before:llm.request. The gate evaluates a config-supplied list of rules, and on first match emits a hitl.requested event and blocks waiting on hitl.responded. The operator’s choice resolves to passthrough (allow), veto (reject), or passthrough-with-edits.

Each rule is a map with the following keys:

Match keys recognized by the runtime payload:

• action_kind — tool.invoke or llm.request.
• tool — the tool name (only meaningful for tool.invoke).
• args.<dotted> — any nested key inside the tool’s argument map.
• model — the LLM model id (only meaningful for llm.request).
• role — the LLM model role (only meaningful for llm.request).

Example:

nexus.gate.approval_policy:
  rules:
    - match: { action_kind: tool.invoke, tool: shell, args.command: "rm*" }
      mode: choices
      choices: [allow, reject]
      timeout: 5m
      default_choice: reject
    - match: { action_kind: llm.request, model: "claude-opus-*" }
      mode: choices
      prompt: "About to call expensive model {{ .model }}. Approve?"

Eval harness

The eval: block configures the offline eval harness invoked via the nexus eval subcommand. The engine itself ignores this block — only cmd/nexus/eval.go reads it. Per-flag overrides on the CLI take precedence over config values, which take precedence over built-in defaults.

eval:
  cases_dir: tests/eval/cases
  reports_dir: tests/eval/reports
  judge:
    model: claude-haiku-4-5
    temperature: 0
    n_samples: 1
    cache: true
  baseline:
    fail_on_score_drop: 0.05
    fail_on_latency_p95_drop: 0.20

Subcommand overview

Environment variables

Cost CLI

nexus cost report aggregates cost-attribution data from session journals (idea 09). Costs come from llm.response.cost_usd which providers emit using pkg/engine/pricing — the CLI is provider-agnostic.

Flags:

• --session <id> — limit to one session id. Default: every session under sessions.root.
• --tenant <t> — only Tags["tenant"] == t.
• --group-by <dim> — one of session_id (default), tenant, project, user, source_plugin, model, task_kind.
• --since <duration> — only events newer than now - <duration> (e.g. 24h, 7d).
• --json — emit JSON instead of the default table.

Tags are populated by:

• The engine’s before:llm.request seeder (session_id, plus tenant/project/user from SessionMeta.Labels).
• Each llm.request-emitting plugin (source_plugin, plus task_kind on req.Metadata).
• Plugins routing decisions (_routed_by, _routed_rule, _downgraded_by, _downgraded_from on req.Metadata).

Session broker (nexus-broker)

The nexus-broker binary (cmd/nexus-broker) is a standalone service, not an engine plugin. It reads its own YAML config file (default path broker.yaml, override with -config <path>) and fronts OS-isolated Nexus instances behind an HTTP/WebSocket gateway.

# broker.yaml
listen_addr: ":8080"
nexus_binary_path: "nexus"
max_concurrent: 8
idle_timeout: 5m
queue_wait_timeout: 30s
release_grace: 10s

The spawned-instance side is configured by the nexus.io.broker plugin (broker_addr, lease_id) — see nexus.io.broker in the I/O section. Both keys fall back to the NEXUS_BROKER_ADDR / NEXUS_BROKER_LEASE_ID environment variables the broker injects at spawn (defined as brokerframe.EnvBrokerAddr / brokerframe.EnvLeaseID).

POST /claim (HTTP API, not YAML)

POST /claim mints a lease, spawns an instance with the supplied config, waits for it to dial back and signal ready, and returns the lease coordinates. The request is a small JSON envelope; session_id is optional.

// request body
{
  "config": "engine:\n  name: example\n",  // required: full nexus config (YAML text)
  "session_id": "prior-session-id"          // optional: resume a persisted session
}

When session_id is set the broker spawns the instance with -recall <id> so the engine reloads that session and replays its history; when omitted it starts a fresh session. An unknown/invalid session_id makes the engine fail to boot, so the instance never signals ready and the claim returns 502 (“instance exited before signalling ready”) rather than silently starting a new session.

// success response (200)
{
  "lease_id": "…",                          // lease handle for this instance
  "ws_url": "ws://host:port/lease/<lease>",  // client WebSocket endpoint
  "session_id": "…"                          // engine session id: the generated id for a
                                             // new session (capture it to -recall later),
                                             // or the requested id echoed back on resume
}

POST /release/{lease_id} (HTTP API, not YAML)

POST /release/{lease_id} tears a live instance down gracefully. The broker sends a shutdown frame to the instance, whose nexus.io.broker plugin emits io.session.end so the engine performs a clean Stop — flushing and persisting the session before exit. The broker then waits up to release_grace for the process to exit and force-kills it if that window elapses (no orphan). The lease is removed and its slot freed. The session directory under ~/.nexus/sessions/<id>/ is left intact and remains resumable via -recall.

Release is idempotent: releasing an already-gone lease returns 404 rather than erroring, and concurrent releases of the same lease collapse to a single teardown.

GET /leases (HTTP API, not YAML)

GET /leases is a read-only introspection surface: it reports the capacity and queue aggregates plus a snapshot of every live lease, sorted by created_at then lease_id. It performs no mutation.

// response (200)
{
  "max_concurrent": 8,     // configured cap (0 = unlimited)
  "slots_in_use": 2,       // live instances currently holding a slot
  "queue_depth": 0,        // claims parked in the FIFO capacity wait queue
  "leases": [
    {
      "lease_id": "…",
      "session_id": "…",                       // omitted until reported by the instance
      "pid": 41234,
      "state": "active",                        // "spawning" | "active" | "draining"
      "reason": "manual release",               // teardown reason once draining; omitted otherwise
      "last_activity": "2026-06-25T12:00:00Z",  // RFC3339
      "created_at": "2026-06-25T11:59:30Z"      // RFC3339
    }
  ]
}

Surface states: spawning (lease exists, instance not yet registered), active (registered, frames can flow), draining (a teardown has latched).

Full narrative, the new-vs-resume flow, a WebSocket connect sketch, and the v1 deployment caveats live in the Session Broker guide.

Cross-references

• Plugin System — plugin lifecycle, Requires() vs Dependencies(), capability resolution.
• Gates — vetoable event mechanics shared by every gate plugin.
• Tool System — tool choice, parallel dispatch, structured output.
• RAG — embeddings, vector store, ingestion.
• I/O Transport — browser vs Wails, parity rule.
• Desktop Shell — embedder API.