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 blocks are guarded separately, and by a different mechanism. core, engine, capabilities, plugins.active and journal have their values checked by the engine schema, but unknown key names there could not be caught that way: LoadConfigFromBytes is a non-strict YAML decode, and the validator rebuilds those blocks from the already-decoded typed config, so a key YAML dropped never reached the schema at all. A misspelled block therefore used to boot clean with the feature it configured silently switched off — which is at its worst with core.object_store, where the run looks entirely healthy and simply never persists anything.

checkUnknownConfigKeys now walks the raw YAML against the config structs’ yaml tags before anything else and rejects an unknown key at any depth, naming the path and listing what was valid there:

config: unknown key "core.object_stor" (valid keys here: agent_id, log_level,
logging, max_concurrent_events, models, object_store, sessions, storage,
tick_interval)

Every unknown key in a file is reported in one message, so a bad config is fixed in one pass rather than one boot per typo.

Three blocks are exempt because their keys are data rather than field names, and each is guarded elsewhere or not at all by design:

The check is derived from the structs by reflection rather than from a hand-maintained list, so adding a config field needs no corresponding edit — and there is no second list to drift into rejecting a legitimate new key.

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

Optional. Makes a remote object store the source of truth for everything Nexus persists between runs, for deployments with no durable local disk. The block sits on core rather than under core.sessions because it is not session-only: the same backend carries the session tree, app- and agent-scope per-plugin storage, and eval run output — see Beyond the session tree below. Local disk remains the working copy during a run: core and every plugin keep reading and writing ordinary files, and the engine talks to the store only at lifecycle points. Absent this block — the default — behaviour is byte-identical to a build with no object-store support and no object-store code executes.

Backends are selected by name, in the database/sql driver style. A backend ships as its own Go module so the main module’s dependency list is untouched; an embedder adds it to their build with a blank import and names it in config:

import _ "github.com/frankbardon/nexus/modules/objectstore-s3"

core:
  object_store:
    backend: s3
    bucket: nexus-sessions
    prefix: prod/nexus
    region: us-east-1
    failure_policy: degrade

No core change is needed to add a backend, and a third party can implement the pkg/engine/objectstore.Backend seam in their own repository.

Object Storage is the adoption guide: wiring a backend into your own binary end to end, credential setup for each shipped backend, and the full list of what this feature deliberately does not do — starting with the fact that single-writer per session is assumed and not enforced. This page stays canonical for the keys themselves.

Validation is at load, not at first write. The whole block is checked while the YAML is parsed, so a typo, a missing bucket or a backend whose module was never imported fails the boot with the offending key in the message — rather than surfacing an hour into a session as a silently missing artifact. In particular, naming a backend whose module is not in the build reports that no backend module is imported.

Setting any key in the block while leaving backend empty is also an error: that combination is always a mistake, and silently ignoring it would leave the operator believing storage was configured.

Lifecycle. With a backend configured, the engine:

1. Opens the backend at the top of Boot, before anything touches the session tree.
2. Hydrates eagerly and whole-tree when resuming a session (-recall, or an embedder setting RecallSessionID), under the object key prefix sessions/<session id> beneath bucket + prefix. Hydration completes before the workspace is opened and before the first turn runs, so every subsequent read behaves exactly as it would on a host that never left — there is no lazy or faulting read path.
3. Claims an owner marker at sessions/<session id>.owner/owner.json recording host, PID, a per-run instance ID and a heartbeat refreshed every 30 seconds, and reads whatever marker was already there. A second host that still looks like the holder is logged at error level and raised as session.owner.conflict. Detection only — nothing is refused, no lock is taken and nothing waits. A clean Stop removes the marker.
4. Snapshots the whole session tree at every turn boundary — on agent.turn.end, and on demand via session.snapshot.request — and again at shutdown. A hard kill therefore loses at most the in-flight turn.
5. Flushes and releases the backend at the end of Stop, after plugins, the journal and per-plugin SQLite have all closed.

Behaviour worth knowing:

• The snapshot is synchronous. It blocks the goroutine that ended the turn until the upload is durable, because a turn reported complete while its state is still in flight is exactly the guarantee the snapshot exists to provide. The cost is O(tree size) per turn and is logged on every snapshot — objects, bytes, db_bytes and duration — and published as session.snapshot.result.

• failure_policy governs a failed snapshot — see Failure policy below for exactly what each value guarantees. Either way session.snapshot.result carries ok: false.

• An unknown session ID is not an error. Recalling an ID the store has never seen produces a valid, empty session, identical to one created locally.

• A tree already on local disk wins. It is the live working copy, so hydration is skipped rather than overwriting it with a possibly older remote copy.

• A hydration that fails partway fails the boot — under both failure policies. Hydration lands in a staging directory and is committed with an atomic rename, so a partial tree is discarded and never mistaken for a complete session. degrade means “keep running against the local copy”, and at hydrate time there is no local copy.

• session.lock never crosses the seam. It records the PID of the process that owns the session on one machine; round-tripping it through the store would make every resumed session look locked. It is stripped from anything hydrated and is never uploaded.

• SQLite sidecars never cross the seam either. store.db-wal, store.db-shm and store.db-journal describe a machine, not a session. Each store.db is WAL-checkpointed and snapshotted as a standalone file at the turn boundary, so the uploaded database restores with no sidecars beside it.

• A failed or partial snapshot never replaces the previous good copy. A per-object manifest at sessions/<session id>.manifest/manifest.json and then a commit marker at sessions/<session id>.snapshot.json — both siblings of the tree, not members of it — are written only after every other object is durable, so they always describe the last snapshot that completed. A snapshot only ever adds and overwrites; it never deletes.

• Hydration restores exactly the committed generation. The manifest lists the object set of the generation the marker names, and objects in the bucket that it does not name are not materialised into the session tree. They are left in the bucket, never deleted — reclamation is the operator’s. A bucket with no manifest (written by an older build, or by a session that has never completed a snapshot) hydrates whole, exactly as before. Content- addressed blobs are the one thing never pruned, because the local blob store sweeps under an LRU budget while the bucket does not, so a blob a committed history references can legitimately outlive the manifest that named it. See Sessions → The generation stamp and the per-object manifest.

• Two hosts opening one session is detected, never prevented. The owner marker is a diagnostic, not a lease: no fencing token, no expiry the engine waits on, no refusal. A marker is treated as stale — and stays silent — when it belongs to this run, when its host matches and its PID is gone, or when its heartbeat stopped advancing more than 5 minutes ago, so an ordinary resume after a crash does not alarm. Both thresholds are constants rather than config keys. See Sessions → Two hosts, one session.

• The local working copy is not wiped on clean exit. On ephemeral compute the filesystem disappears with the process anyway; on a durable host the local tree is a warm cache and the copy failure_policy: degrade falls back to. core.sessions.retention remains the operator-owned answer to when local session data goes away.

Failure policy

core.object_store.failure_policy is the one durability trade-off the operator owns rather than the implementation. Both values retry, both surface the outage on the bus, and both recover with no operator action — what differs is whether the session keeps taking turns while the store is unreachable.

What strict guarantees, and what it does not. When a turn’s state cannot be persisted, the turn has already happened: its output was streamed to the user, its tools ran, and its side effects are in the world. Nothing in Nexus can un-run it, and no configuration makes it not have happened. What strict does is refuse to start another one:

• the failure is raised immediately — core.error, an error-level log line, and session.snapshot.result with ok: false;
• session.storage.degraded goes out with turns_blocked: true;
• every subsequent io.input is vetoed until a snapshot succeeds, with the reason carrying the last error. The veto runs at priority 200, behind every other before:io.input subscriber, so slash commands and cancellation still work while the gate is closed;
• the first successful snapshot clears the gate, emits session.storage.recovered and the session carries on.

So strict guarantees that no turn ever runs against state whose predecessor was not durably stored, and the divergence is never silent. It does not guarantee that the turn which hit the outage was prevented. A genuine pre-commit gate would need a vetoable turn-boundary event that does not exist, and would not help even if it did — by the time an agent loop can report a turn, the work is done.

What degrade costs. Turns keep succeeding against the local working copy, and that is the point — an object-store outage should not take down an interactive agent that still has a perfectly good local tree. The honest caveat: during a long outage the durability guarantee is not being met even though nothing is failing. Work the user watched happen exists only on local disk, so a host that dies while degraded loses it. That is the trade being chosen.

Retry and the queue bound. A single background worker per run retries with exponential backoff — 1 s, doubling, capped at 60 s — until the state lands. It handles two kinds of work:

• a bounded queue of deferred pushes, capacity 256 objects, fed by blob write-through failures;
• a pending whole-tree snapshot flag, the backstop, set by a failed snapshot, a failed flush, or a queue overflow.

Overflow does not lose work. A push that does not fit in the queue is discarded and the whole-tree snapshot is marked pending in its place. That snapshot re-uploads every object the store does not already hold at the right size, so the escalation is strictly stronger than the item it replaced — coarser, and paid in bandwidth rather than durability. The same is true of the blob write-through queue (also 256), whose own overflow escalates the same way. Both bounds, the backoff schedule and the per-request timeouts are compiled-in constants rather than config keys: every knob has to be documented, validated and supported forever, and an operator who wants to tune them is really asking for a different failure_policy.

Recovery needs nobody. An outage that heals mid-session drains on its own — either the next turn-boundary snapshot closes the episode, or, on an idle session where no further turn is coming, the retry worker does. The two events always pair: exactly one session.storage.degraded per outage and one session.storage.recovered when it ends, so a subscriber counts outages rather than failed requests.

One thing is deliberately not policy-governed. A blob write-through failure never closes the strict gate. Write-through is an optimisation in front of the turn-boundary snapshot, which re-uploads anything the store is missing; failing a turn because that optimisation stumbled on an object the very next snapshot repairs would make strict fire on transients it is not there to catch. Such a failure still queues for retry and still counts towards the degraded state.

Beyond the session tree

The session tree is one of four roots. With a backend configured, the same objectstore.Backend — no per-root methods, no per-root config — also carries:

Keys mirror the on-disk layout beneath the data root, one key segment per directory, so an operator browsing the bucket sees the directory names they already know. core.storage.root (default ~/.nexus) remains the single lever controlling where these live locally, exactly as it does with no backend configured.

• Cross-session lifetimes are preserved. An app-scope store keys to plugins/<pluginID>/store.db with no session ID anywhere in it, which is what keeps it machine-wide. nexus.gate.token_budget stores a tenant token ceiling there precisely so it spans sessions; keying it under the session that happened to flush it would turn that into a per-session ceiling with nothing to notice — the gate would keep running and stop being a budget.
• Agent scope follows the same collapse the storage manager applies. With core.agent_id empty, agent-scope handles resolve to app scope, and so do their keys. nexus.vectorstore.sqlite_fts (scope: agent) relies on this.
• Shared stores hydrate per plugin directory, and never over a local one. A plugin directory that already exists locally is left alone: it may be open in this process or another one on the same machine, and replacing a store.db under a live SQLite handle corrupts it rather than merely staling it. A plugin directory with no local copy is hydrated at boot, before any plugin can open a handle.
• They are snapshotted at the same turn boundary, with the same checkpoint-then-VACUUM INTO discipline, and are logged separately as shared_objects / shared_bytes / shared_db_duration so a large agent-scope index is distinguishable from a large session.
• One writing host at a time. App- and agent-scope stores are shared across sessions by definition. Two processes on one host share the local file and SQLite serialises them, so the later upload is a superset of the earlier — safe. Two processes on different hosts each have their own copy, and the later flush overwrites the other’s at whole-database granularity. See Per-Plugin Storage → Concurrency.
• Eval output is published once, at the end of the run. nexus eval run uploads its run directory under eval/<run-id>/ when the config file it was given (--config) names a backend. The per-case session trees under _sessions/ are excluded — they are session trees, and sessions are the seam’s other root. A publish failure warns and does not change the eval exit code, which is about the cases, not about the bucket.
• Journal output is already covered by the session snapshot: the journal lives at <session>/journal/ and is captured at a consistent instant on every turn boundary.

The s3 backend

Shipped in-repo as its own Go module — github.com/frankbardon/nexus/modules/objectstore-s3, under modules/objectstore-s3/. It is not part of bin/nexus: the AWS SDK it depends on is exactly the kind of dependency the root module refuses to carry, so an embedder who wants it blank-imports it into their own main. See Repository Go Modules.

It covers Amazon S3 and every S3-compatible store: MinIO, Cloudflare R2, Ceph RGW and Backblaze B2.

It adds no config keys of its own. Everything it needs is already in the core.object_store block above; what follows is how this backend reads each key.

# Amazon S3 with a workload identity — no key material anywhere.
core:
  object_store:
    backend: s3
    bucket: nexus-sessions
    prefix: prod/nexus
    region: eu-west-2

# MinIO on a laptop, or any S3-compatible store.
core:
  object_store:
    backend: s3
    bucket: nexus
    endpoint: http://127.0.0.1:9000
    credentials_file: ~/.config/nexus/minio-credentials

Boot-time validation. A malformed endpoint, a credentials_file that is not there, and an unresolvable region all fail the boot naming the key. Nothing remote is checked: failure_policy: degrade exists so an object-store outage degrades a run rather than ending it, and a boot-time round trip to the bucket would make it structurally unable to do that.

Object keys mirror the local tree, one key segment per directory, under prefix. Nothing is encoded, hashed or flattened, so the bucket is browsable — <prefix>/sessions/<id>/plugins/nexus.scene/scene.jsonl is exactly the path it came from. Empty files are stored as zero-byte objects and restored as empty files; this backend never writes a zero-byte directory marker, so there is nothing to confuse them with.

One object at a time, synchronously. Put returns only once S3 has acknowledged the write, so there is no in-backend queue with a second retry regime underneath the engine’s own — retry, backoff and failure_policy stay in one place. A single PutObject caps one object at 5 GiB; no session artifact Nexus produces approaches that.

The gcs backend

Shipped in-repo as its own Go module — github.com/frankbardon/nexus/modules/objectstore-gcs, under modules/objectstore-gcs/. Like the s3 backend it is not part of bin/nexus: the Google Cloud SDK it depends on is exactly the kind of dependency the root module refuses to carry, so an embedder who wants it blank-imports it into their own main. See Repository Go Modules.

import _ "github.com/frankbardon/nexus/modules/objectstore-gcs"

It covers Google Cloud Storage, and — through endpoint — the Cloud Storage emulators.

It adds no config keys of its own. Everything it needs is already in the core.object_store block above; what follows is how this backend reads each key, and the two keys it reads differently from s3 are called out because a config copied between the two clouds will contain them.

# Google Cloud Storage under GKE Workload Identity — no key material anywhere.
core:
  object_store:
    backend: gcs
    bucket: nexus-sessions
    prefix: prod/nexus

# A static service-account key, for somewhere Workload Identity is not available.
core:
  object_store:
    backend: gcs
    bucket: nexus-sessions
    credentials_file: ~/.config/nexus/gcs-service-account.json

# An emulator on a laptop. No credentials, no environment variables.
core:
  object_store:
    backend: gcs
    bucket: nexus
    endpoint: http://127.0.0.1:4443

Credential resolution, in order. credentials_file if set; otherwise Application Default Credentials if they resolve; otherwise, if endpoint is set, an unauthenticated client, logged at warn level, which is the emulator path — every Cloud Storage emulator is unauthenticated, and doing this from config is what lets an emulator deployment be described entirely in YAML. Anything else fails the boot. That last step is deliberately stricter than the Google SDK, which builds a client happily when it cannot find credentials and fails at the first request instead; under failure_policy: degrade that would be a run that starts, looks healthy and persists nothing.

Boot-time validation. A malformed endpoint, a credentials_file that is not there, and the no-credentials case above all fail the boot naming the key. Nothing remote is checked, for the same reason the s3 backend checks nothing remote: failure_policy: degrade exists so an object-store outage degrades a run rather than ending it, and a boot-time round trip to the bucket would make it structurally unable to do that.

Object keys mirror the local tree, one key segment per directory, under prefix — byte for byte the same layout the s3 backend produces. That is a decision, not a coincidence: a deployment migrating between the two clouds, or replicating one bucket into the other, can do it with the vendors’ own copy tools and no translation step. GCS has no directories — the console renders / as one, but a key is a single flat string — so depth costs nothing, and empty files are stored as zero-byte objects and restored as empty files. This backend never writes a zero-byte folder placeholder, so there is nothing to confuse them with.

One object at a time, synchronously, exactly as s3: Put returns only once GCS has acknowledged the write, so there is no in-backend queue with a second retry regime underneath the engine’s own. Two GCS-specific details fall out of that. Every upload and download is CRC32C-verified end to end by the SDK, so a successful Put means the bytes in the bucket are the bytes on disk, not merely that a request returned 200. And uploads and deletes are issued with the SDK’s RetryAlways policy rather than its default, which would not retry them at all: an object insert without a precondition is not idempotent in general, but this backend always writes whole objects and takes last-write-wins, so a repeated request converges. Without that, a transient 503 would fail a push that the s3 backend would have retried silently.

Deleting an object that is not there is not an error, matching the seam and matching s3. GCS itself returns 404 where S3 returns 204; the backend absorbs the difference, which is what lets the engine retry a delete without special-casing the second attempt.

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

Source: plugins/agents/a2aremote/. The outbound half of Nexus’s A2A interoperability: where nexus.io.a2a serves this instance as an A2A agent, this plugin lets a Nexus agent call remote A2A agents. Each configured remote registers one LLM-facing tool (default delegate_a2a_<name>); a call sends the delegated task over the A2A wire through pkg/a2a/a2aclient, and folds the remote task’s final text and artifacts back into the tool result under XML tag boundaries.

Remotes come from configuration only — the tool schema exposes no URL, host or endpoint parameter, so a model cannot point the instance at an arbitrary address. See Remote A2A Agents.

Each remote’s Agent Card is fetched lazily, on first use, never at boot: an unreachable remote must not be able to fail engine startup. Until the card resolves the tool carries the configured description; the first successful call replaces it with a description built from the card’s own skills and re-registers the tool once.

Every failure — unreachable card, refused binding, protocol error, dead stream, exhausted budget, a task that ends FAILED — becomes a clean tool.result error, never an engine-level failure.

A remote that parks at INPUT_REQUIRED is not a failure: the question is raised on the local bus as hitl.requested, the human’s answer resumes the remote task with the same taskId and contextId, and the delegation carries on. The delegating model never sees the question. See the hitl block below.

Every key from binding down is a default; each agents[] entry may override it. An agent-level extensions list replaces the inherited one wholesale rather than merging, so an empty list means “declare none”.

Each agents[] entry:

The hitl block, at either level:

Two deadlines run while a task is parked, and the earlier one wins. The whole-call timeout keeps running — a remote waiting on a human is still work this session authorized, and pausing the budget is how an unanswered question pins a session for ever — and hitl.input_timeout bounds the individual question. With the 5m default timeout the call budget expires first, so input_timeout only bites once timeout is raised; an operator who expects a remote to ask questions should raise both. Whichever fires, the outcome is the same and the tool error names the deadline that fired: the question is retracted with hitl.cancel, the remote task is cancelled with CancelTask, and the delegating model is told the question went unanswered and told not to answer it itself.

AUTH_REQUIRED is deliberately not routed to a human — no answer a person types into a chat is a credential — and reports that the agent’s credentials need configuring.

Anything a human answered is never cached. A person’s answer is a decision made at a moment, and replaying it for a later identical task would apply that decision again without asking.

The credentials block exists only inside an agents[] entry. There is deliberately no plugin-level default: a default credential silently applied to a remote added later is how a token reaches a host it was never issued for.

Everything a credentials block can be wrong about is checked at Init: an unset environment variable, a key belonging to a different type, an unreadable or mismatched client certificate, or an OAuth2 remote with no way to reach a token endpoint each fail boot with a message naming the agent and the key — not a 401 on the first delegation. No credential value is ever logged, on any path, including failures.

type: bearer — a static token, following the same api_key / api_key_env convention the LLM providers use:

type: oauth2_client_credentials — the RFC 6749 §4.4 machine-to-machine grant, implemented over net/http (no golang.org/x/oauth2 dependency). The token is cached and refreshed ahead of expiry, and a burst of concurrent calls triggers one token request, not one per caller:

One id/secret pair is required: set client_id or client_id_env, and client_secret or client_secret_env. When token_url is being discovered from the card, the well-known Agent Card fetch — and only that fetch — goes out unauthenticated, because the token cannot be obtained before the endpoint that issues it is known. Specification §8.2 makes the well-known card a public document; a remote that protects its card wants token_url set explicitly.

type: mtls — client-certificate authentication, wired into the http.Transport. Every path is resolved through the engine’s ~ expansion and read at Init:

On the first call to a remote — never at boot, since the card is fetched lazily — the configured credential is compared against the card’s securitySchemes, and an obvious mismatch (a bearer token against a card declaring only mutualTls, say) logs one warning. It warns rather than refuses: a card’s securitySchemes block is optional and routinely incomplete, and refusing on that evidence would break working deployments over a documentation defect.

The retry block, at either level:

Reads are retried on transport failures and 502/504; every operation is retried on 429/503. A message send is never retried on a transport failure, because A2A defines no idempotency key and a blind retry would run the remote’s work twice.

Every duration key is a duration string ("90s", "5m", "1h30m"), never a bare number: timeout: 600 reads as ten minutes to an operator and six hundred nanoseconds to Go, so a bare number is rejected rather than guessed at.

Timeout precedence for one call, first match wins: the tool’s timeout_seconds argument → the agent’s posture budget timeout → the timeout key (agent-level, else plugin-level) → the 5m built-in default.

Posture budgets. Only two dimensions of an AgentPosture cross an A2A boundary — default_budget.timeout and max_recursion_depth — because the protocol gives a client no control over the remote’s token or tool-call spend. A posture whose default_budget sets max_tokens or max_tool_calls is refused for a remote agent rather than half-honoured, and the call fails with an error naming the key.

Caching. Successful outcomes are cached in the LRU under a content hash of (remote identity, posture version, task, canonicalized context). Failures are never cached, so a remote that was briefly down is retried rather than replayed, and neither is any outcome a human answered a question for.

Cancellation. cancel.active — the event nexus.control.cancel emits once a cancellation is happening — retracts any question this plugin put in front of a human, issues CancelTask to every remote task in flight, and aborts the calls. The same abandonment runs on the ordinary exits too: if this instance walks away from a remote task that has not reached a terminal state, it tells the remote.

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.

nexus.tool.session_tags

Source: plugins/tools/session_tags/plugin.go. Registers session_tag_set, session_tag_get, session_tag_delete, session_tag_list — LLM-facing tools over the general-namespace session tag store (SessionMeta.Labels; see Session Tags for the full mechanism, and the Cost CLI section below for how tenant/project/user tags feed nexus cost report). Off by default — not in any stock config’s plugins.active; an operator opts in explicitly to give the agent write access to its own session’s tags.

Restricted to the general (non-_-prefixed) namespace: session_tag_set/ session_tag_delete ride the same vetoable before:session.tag.set/ before:session.tag.delete path any other caller uses, so a reserved-prefixed key is rejected identically — this plugin has no elevated privilege and no bypass. session_tag_get/session_tag_list report a reserved-prefixed key as not found / omit it entirely, never revealing its presence.

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.

Schema-validated at boot. The plugin ships plugins/io/agui/schema.json and implements ConfigSchema(), so the engine validates this block — including everything under auth: — before Init runs, with additionalProperties: false at every object level. A misspelled key aborts the boot naming the offender (unknown key "bearer_tokn" (did you mean "bearer_token"?)) instead of being silently ignored, which for an auth key would mean an unauthenticated listener and no warning. The table above is the whole surface: any key not listed is rejected.

One rule is deliberately not in the schema. auth: versus bearer_token/bearer_token_env is enforced in Init (see below), which owns the operator-facing message; duplicating it in JSON Schema would give two enforcement points that can drift, and the schema one runs first and would report the worse message.

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.

Authentication (auth:) on nexus.io.agui

The transport authenticates through the shared identity layer (pkg/nexusauth) — the same validator chain the session broker uses. Two spellings are accepted and they are mutually exclusive:

• bearer_token / bearer_token_env — one shared secret, unchanged and not deprecated. It is desugared into a one-entry static validator, which is purely an implementation detail with one visible improvement: the token comparison is now constant-time.
• auth: — the full validator-chain block, so an AG-UI deployment can verify OIDC JWTs (jwks), opaque tokens (introspect), or an identity a fronting proxy established (proxy_headers).

Setting both is a boot error naming both keys, not a precedence rule: two sources for one security decision means one of them is stale, and quietly preferring either is how an operator comes to believe a credential was tightened when it was not. (Setting bearer_token and bearer_token_env remains legal and keeps its original precedence — inline first, then the environment variable.)

Setting neither means authentication is disabled and every request is admitted, exactly as before. That is safe by default only because the listener binds loopback; change bind and you should configure auth in the same commit.

plugins:
  nexus.io.agui:
    bind: "0.0.0.0:8090"
    auth:
      validators:            # ordered; the first validator that accepts wins
        - type: static       # a shared token for CI or a local operator CLI
          tokens:
            - token: "..."
              principal: "ci-runner"
        - type: jwks         # OIDC JWTs verified against the issuer's published keys
          issuer: "https://id.example.com/"
          jwks_url: "https://id.example.com/.well-known/jwks.json"
          audience: "nexus-agui"
          principal_claim: sub

The validator keys are identical to the broker’s — validators[].type, principal_claim, tokens[], issuer/jwks_url/audience, the introspect keys, the proxy_headers keys, and their defaults and validation rules are all documented once under Authentication (auth:) and the per-validator sections that follow it. There is one deliberate difference: auth.admin_scope is broker-only and is rejected here as an unknown key. Unknown keys are rejected at every level in both hosts — a silently ignored auth key is a security bug, not a cosmetic one.

On this host they are rejected twice over, and the earlier of the two is the one an operator meets: plugins/io/agui/schema.json describes every validator key per type, so a key that belongs to a different validator type (jwks_url on a static entry) or a duration written as a bare number (cache_ttl: 600) fails at boot before pkg/nexusauth ever parses the block. The two agree by construction — the schema was derived from the nexusauth parsers, not from prose — and nexusauth remains the authority for the rules a schema cannot express (URL transport, algorithm confusion, duplicate tokens, TTL caps).

Gated surface. POST /agui only. OPTIONS /agui (CORS preflight) is deliberately not authenticated: a browser never attaches Authorization to a preflight, so gating it would make every cross-origin AG-UI client unable to reach the endpoint it is authorized for. CORS headers are applied before the auth check so a browser can actually read a 401 instead of seeing an opaque network error.

Status mapping. Denials are classified by the chain, never by string matching, and map onto:

The codes match the broker’s because the denial kinds are the shared package’s transport contract, and one deployment should not answer the same refusal two different ways. The bodies differ: this endpoint’s success response is an SSE stream, not JSON, so there is no envelope for an error to be consistent with, and the 401 body stays the plain unauthorized it has always been. The RFC 6750 challenge matters more here than on the broker — an AG-UI client is often a browser front-end whose only structured signal is the status plus the challenge, and error="invalid_token" is what lets it tell “sign in” from “refresh the token” without parsing prose.

Principal. A resolved Principal is carried to the run and recorded on the agui run started log record (principal_id); it is empty when auth is disabled. Nothing keys behaviour on it yet — this transport serves a single engine/session per listener and admits one run at a time, so there is no second principal for an authorization decision to distinguish.

nexus.io.a2a

Source: plugins/io/a2a/. Agent2Agent (A2A) serve transport: exposes this Nexus instance as an A2A agent over one HTTP listener carrying three surfaces — the /.well-known/agent-card.json discovery document, the JSON-RPC 2.0 binding, and the HTTP+JSON/REST binding. The wire format is pkg/a2a (A2A specification 1.0.x); this plugin contributes the listener, the credential guard, the card assembly and the routing. Safe by default: binds loopback, optional auth through the shared pkg/nexusauth chain, and CORS off unless configured. The A2A Interoperability guide covers the protocol mapping and a worked end-to-end example; nexus.io.a2a is the plugin page.

Maturity. Every A2A operation outside the push-notification family is wired. SendMessage and SendStreamingMessage drive a real Nexus turn; every task they create is persisted durably (see Task retention below) and GetTask, ListTasks and SubscribeToTask read it back — see Reading tasks below. A task interrupted by a human-in-the-loop question parks at TASK_STATE_INPUT_REQUIRED and is resumed by a message naming the same taskId, and CancelTask settles a task at TASK_STATE_CANCELED — see Interruption and cancellation below. The Agent Card reports all of this honestly: capabilities.streaming is true because both streaming operations are wired, while pushNotifications and extendedAgentCard are false. (A2A declares no capability boolean for cancellation; it is part of the core task surface.) A turn publishes its final text, its structured output, every tool result and every file it wrote as Artifacts, and the card declares the Nexus telemetry extension — see Artifacts and The Nexus extension below.

Schema-validated at boot. The plugin ships plugins/io/a2a/schema.json and implements ConfigSchema(), so the engine validates this block — including everything under auth: and card: — before Init runs, with additionalProperties: false at every object level. The schema also enforces that one of card/card_file is present. The table above is the whole top-level surface; any key not listed is rejected.

Running a turn

A SendMessage or SendStreamingMessage becomes one Nexus turn, reported as one A2A Task. There is no configuration for any of this; it is the fixed behaviour of the transport.

SendMessage blocks until the task reaches a state the caller has to act on and returns the Task, which is A2A’s default (§3.2.2). That means a terminal state or INPUT_REQUIRED: a task waiting for the caller cannot be waited on by the caller. SendStreamingMessage writes the same frames as SSE — an opening Task snapshot, status updates, the artifact, and the terminal status that closes the stream.

configuration.returnImmediately is honoured: the call answers with the task as it stands and the client follows it with GetTask or SubscribeToTask. It was refused for as long as a run’s lifetime was its request’s; see Task lifetime below. SendStreamingMessage ignores the flag, because a stream is already the follow-up it asks for.

Other refusals, each with the error type the specification reserves for it: a non-text Part or an acceptedOutputModes list with no text type (ContentTypeNotSupportedError), an inline taskPushNotificationConfig (PushNotificationNotSupportedError), and a second task while one is in flight (UnsupportedOperationError; the listener fronts one agent loop). A message naming a taskId is a continuation, not a refusal — see Interruption and cancellation.

Task lifetime

A run is this listener’s single active task and is released when the task reaches a terminal state — not when the HTTP request that started it returns. Three things follow, and they are the reason interruption works at all:

• A client may disconnect mid-turn without failing its own task. The turn carries on, GetTask still answers, and SubscribeToTask reattaches to exactly where it got to.
• A task may stay parked on a question for as long as answering it takes, bounded by tasks.input_timeout.
• configuration.returnImmediately is answerable.

The cost is that a turn nobody is watching holds the slot until something ends it, which is why CancelTask is wired and why an unanswered question has a deadline. A task left non-terminal by a process restart is settled at FAILED when the store next opens: no run drives it, no bus event will ever name it, and only terminal tasks are evictable, so leaving it would be an immortal row reading WORKING for ever.

Interruption and cancellation

There is no configuration here beyond tasks.input_timeout; the behaviour is fixed.

A question parks the task. When a Nexus agent asks a human something — nexus.control.hitl’s ask_user tool, or any plugin emitting hitl.requested — the task moves to TASK_STATE_INPUT_REQUIRED with the question on status.message, and a multiple-choice question renders its option ids into that text so a text-only A2A client can answer it. The task stays live: open SSE streams stay open (§11.7’s close rule keys off terminal states, which this is not), the transition is written through to the store, and a client that reconnects reads the question from GetTask or from SubscribeToTask’s opening snapshot.

A message naming the same taskId resumes it (§3.4). The answer is routed to hitl.responded and the task returns to WORKING inside the same turn — no io.input, no second task. An answer whose text matches one of the question’s option ids (case-insensitively) is delivered as that choice; anything else is free text. Continuing a task is refused, with UnsupportedOperationError, when it is already terminal, when the message names a different contextId than the task’s, or when the task is not waiting for input. A taskId that does not belong to the caller answers exactly as an unknown one does: TaskNotFoundError.

CancelTask settles the task at TASK_STATE_CANCELED, then tells the bus — hitl.cancel if the task was parked, so the blocked agent loop unblocks, then cancel.request, which is the control.cancel capability’s own entry point (the same event the TUI emits). Any open stream closes on the terminal frame. Cancelling an already-terminal task is refused with TaskNotCancelableError and writes nothing: a terminal state is final, so reporting success would tell a client its cancel took effect on a task that had already completed.

Task retention

Every task this listener creates is written to a SQLite database at <session>/plugins/nexus.io.a2a/store.db, opened through the engine’s per-plugin storage capability at session scope. There is no bespoke file format and no separate cleanup job: archiving the session disposes of its tasks with it. A listener that cannot open the store does not start — a task that existed only for the lifetime of its request is exactly the lie the store exists to prevent.

The record holds the task id, its contextId, the current state with its timestamp, the full status-transition history, every artifact, message references for both sides of the exchange, and the authenticated Principal that created it. Reads are principal-scoped: a caller can only ever reach tasks filed under its own principal id, and there is no unscoped query in the store’s API to reach for by mistake. With no auth: block configured every caller is unauthenticated and shares one partition.

Retention is load-bearing rather than housekeeping — a task carries its history and its artifacts, so an unbounded store would grow with traffic rather than with the conversation. Both knobs are enforced on open and after every task creation, and a task is evicted when it exceeds either of them. Only terminal tasks are evictable: a live task is the one a client is most likely to be following, so it is never dropped mid-turn. Non-terminal tasks still count against the per-context cap, so a wedged in-flight task shows up as retention pressure instead of exempting itself from it.

The defaults are chosen for the standalone single-context listener: 24 hours is comfortably longer than any plausible client reconnect window, and 200 tasks is 200 turns of history — far more than a client polls back over.

Sizing. The artifact side of the store is bounded by artifacts.max_task_bytes x tasks.max_per_context, which at the shipped defaults is 1 MiB x 200 ≈ 200 MiB in the worst case where every retained task saturates its artifact budget. No ordinary session approaches that — a turn’s artifacts are the tool outputs it actually produced — but the product is stated rather than implied, so an operator who cannot afford the worst case lowers one of the two knobs by arithmetic instead of by guesswork. See Artifacts.

input_timeout is not retention — it is a liveness bound, and it defaults to a non-zero value for a reason worth stating. A parked task is not idle: the turn that asked the question is blocked inside ask_user, holding this listener’s single active-task slot and the process’s one agent loop, so a question nobody answers pins the whole instance. 15 minutes is measured against a human, not a machine — long enough for someone to be paged, read the question and reply, short enough that an abandoned question frees the instance within one coffee break. Set "0s" only if a task parked until the process exits is genuinely what you want.

plugins:
  nexus.io.a2a:
    tasks:
      ttl: 72h
      max_per_context: 50
      input_timeout: 5m

Artifacts

A2A puts task output in artifacts and conversation in messages (§3.7). Four things a Nexus turn produces are output by that reading, and all four are published without an operator enabling anything:

Tool results are artifacts unconditionally. There is no key to turn them off, deliberately: an interop transport whose observability depends on the operator having enabled it is one a partner cannot rely on. The volume that buys is answered by the caps below rather than by a flag.

A human-in-the-loop question is not an artifact. It rides the INPUT_REQUIRED status message and the task’s message history, which is where a request for input belongs — putting it in the output channel as well would count one event twice.

File detection is tool.result-based, and is incomplete by design. A file is published only when a tool reports having written it: through the engine’s own ToolResult.OutputFile field (honoured for every tool), or through a structured-output key named by artifacts.file_sources. Snapshot-diffing the session workspace is out of scope, so a write by an uninstrumented path is missed — a shell command redirecting into a file reports stdout and an exit code and nothing about the file, so nothing is published for it. nexus.tool.shell therefore has no default rule; an operator whose shell wrapper does report a written path adds one to file_sources.

Every reported path is resolved against artifacts.file_base_dir and confined to it, symlinks followed. A path that escapes is dropped rather than clamped: a tool reporting ../../.ssh/id_rsa is either broken or hostile, and inlining what it named into a response that leaves the process cannot be walked back.

configuration.acceptedOutputModes is honoured, not merely validated: a request naming only text media types gets no application/json Part and no inline file contents. The files are still reported, as the same metadata note an oversized file gets, so the client learns they exist.

The caps are load-bearing rather than tuning. Unconditional tool-result artifacts, times inline base64 file parts, times a disk-persisted store, is an unbounded product; these three caps are what make it a bounded one. Per artifact it is max_file_bytes / max_tool_output_bytes; per task it is max_task_bytes; per store it is max_task_bytes x tasks.max_per_context.

plugins:
  nexus.io.a2a:
    artifacts:
      max_file_bytes: 1048576
      max_tool_output_bytes: 8192
      max_task_bytes: 4194304
      file_base_dir: "~/agent-workspace"
      file_sources:
        write_file: [path]
        render_report: [output_path]

The Nexus extension

Thinking steps, tool calls, subagent progress and token counts have no canonical A2A field. They ride the Nexus extension instead, whose URI is

https://github.com/frankbardon/nexus/a2a/extensions/agent-events/v1

There is no configuration for it: it is declared in the Agent Card under capabilities.extensions for the same reason the capability booleans are derived, and it is never required — everything it carries is supplementary, so a client that ignores it still receives a complete canonical stream.

The carrier is TaskStatusUpdateEvent.metadata, keyed by the extension URI. The status those frames carry is the task’s current state, not a hard-coded WORKING: a telemetry frame emitted while the task is parked at INPUT_REQUIRED must not tell a client the task went back to work.

Opt-in is per request and is honoured by not sending. A client asks with the A2A-Extensions service parameter:

curl -sN localhost:8091/a2a \
  -H 'A2A-Version: 1.0' \
  -H 'A2A-Extensions: https://github.com/frankbardon/nexus/a2a/extensions/agent-events/v1' \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendStreamingMessage","params":{…}}'

The response echoes A2A-Extensions with the extensions that were actually activated, so a client asking for several can tell which it got; an extension this agent does not speak produces no echo and no error. A client that asked for nothing receives a stream with no extension metadata on it at all.

Telemetry is not persisted. It is the one frame class that does not go through the task store’s write-through path. A stored telemetry frame would land in the status history as a WORKING transition, so GetTask would replay a turn’s reasoning as state changes the task never made — and a long turn would fill the history table with them. GetTask and SubscribeToTask’s opening snapshot therefore carry the canonical task only; telemetry is a live signal on an attached stream.

Reading tasks

GetTask, ListTasks and SubscribeToTask answer from the store above. There is no configuration for any of them; the behaviour below is fixed.

• History is the trail of message references the store retained, rendered as text messages stamped with their task and context — not a replay of memory.history. §3.7 leaves it to the server which messages are persisted, so a bounded reference trail is a conforming history. historyLength unset keeps everything retained, 0 omits history, and N keeps the most recent N messages.
• ListTasks pagination defaults to a page size of 50 and is bounded to 1–100 (§3.2). nextPageToken is an opaque keyset cursor over (created_at, rowid), not an offset, so a task created or evicted mid-walk cannot make a client skip or repeat a row. A token this server did not mint is an InvalidParamsError, not a silent restart. totalSize is counted under the identical filters, so it counts the same set the client is paging through.
• includeArtifacts defaults to false, per §3.2, so a page stays small; GetTask always returns artifacts. History has no such default in the specification and is therefore included in a listing unless the request caps it — pass historyLength: 0 for a compact page.
• SubscribeToTask always opens with the task’s current state. A live task then streams the same frames every other attached stream receives — several clients may follow one task and all see an identical sequence from the point they joined. An already-terminal task yields its terminal snapshot and the stream closes immediately. A task that is neither (one this process was serving when it last stopped) gets its snapshot and then a close, since nothing will ever update it again — though after a restart such a task is settled at FAILED when the store opens, so the snapshot names a real ending.
• Ownership is not enumerable. Every read goes through the store’s principal-scoped view, so a task belonging to another principal answers exactly as an unknown id does: the same TaskNotFoundError, the same HTTP 404, the same body, from the same single lookup. A distinct “exists but is not yours” answer would be an existence oracle for ids the caller was never told.

contextId and the Nexus session

An A2A context is a conversation and so is a Nexus session, so contextId maps onto the session — but a Nexus process owns exactly one session, fixed at boot, and there is no bus primitive that starts a second one or resets history. The binding follows from that:

• The first call claims the session. A client that names no contextId is assigned the session id and gets it back on the Task, so it can keep using it.
• Later calls naming the same context continue the conversation, with history intact — memory.history persists across turns within a session.
• A different contextId is refused with UnsupportedOperationError naming the bound context. Accepting it would hand the caller a conversation already carrying another context’s history while calling it new. Run one instance per context; the session broker automates exactly that.

Agent Card content

card: is the hand-authored half of the discovery document.

Skills are deliberately hand-authored — they are not derived from nexus.skills or the tool catalog. The card is a public contract: an internal catalog churns with every plugin an operator enables, and a discovery document that churned with it would both leak internal structure and break clients that keyed off it.

There are no keys for supportedInterfaces, capabilities, securitySchemes or securityRequirements, and there never will be. Those describe what the listener actually does, so they are derived and overwrite whatever the card source carried — including a complete card_file document. A card naming a URL nothing is bound to, a capability nothing implements, or a scheme nothing enforces is worse than no card: it is a confident wrong answer. Concretely:

• supportedInterfaces is [{public_url + jsonrpc_path, JSONRPC, 1.0}, {public_url + rest_prefix, HTTP+JSON, 1.0}], in that preference order.
• capabilities.streaming / pushNotifications / extendedAgentCard are computed from the set of operations the plugin actually implements.
• securitySchemes / securityRequirements come from the validator chain.

The card is rendered and validated at boot: a card that could not be served fails the process start, not the first partner’s request. It is served with an ETag (a hash of the card content, so an edit that does not bump card.version still invalidates a cache) and Cache-Control: public, max-age=300, per specification §8.6.1; If-None-Match yields 304.

Agent Card security schemes

The card’s securitySchemes and securityRequirements are derived from the configured validators, so what a client is told to present is what the chain enforces. One validator becomes one named scheme plus one requirement entry; the scheme name is the chain-order name nexusauth already assigned (static, jwks, jwks#2), so the card and the boot log name the same thing.

Requirements are emitted as separate entries rather than one entry naming every scheme, because that is the accurate translation of a nexusauth.Chain: the chain is first-success, so satisfying any validator suffices, and A2A spells “any of these alternatives” as separate members of the securityRequirements array. With no validators configured the card carries no securitySchemes at all, which is the honest document for a listener that admits everyone — and is why the bind address defaults to loopback.

Agent Card auth posture

GET /.well-known/agent-card.json is unauthenticated by default, even when every operation is guarded.

Specification §8.2 makes the well-known URI a pre-authentication bootstrap step: a client fetches the card precisely to discover which credentials to obtain (§7.3, step 1), so gating it behind those same credentials is circular and breaks every conforming client. The specification’s answer for a card that must stay private is a separate authenticated document behind GetExtendedAgentCard (§6.9), which this plugin does not implement and honestly declares as false.

The counter-argument is real, and is why card_requires_auth exists: this card names a private agent, and its description, skills and examples may describe capability an operator would rather not publish. Two things answer it. First, the listener binds loopback by default, so the “public” document is not reachable from anywhere the operator did not deliberately open. Second, the card’s contents are hand-authored for exactly this reason — nothing is derived from the tool catalog, so what the card reveals is what an operator chose to reveal.

An operator who moves bind off loopback and still needs the card private sets card_requires_auth: true and distributes the document out-of-band, which §8.2 explicitly sanctions (“Direct Configuration”). That is a real trade — it makes the agent undiscoverable to clients that have not already been told about it — so it is opt-in, not the default.

OPTIONS preflight on every route is never authenticated: a browser does not attach Authorization to a preflight.

A2A version negotiation

Specification §3.6.2 says an agent MUST interpret an empty A2A-Version as 0.3. pkg/a2a implements that literally, and since the codec speaks only 1.0, the literal reading turns every header-less request into a VersionNotSupportedError. That rule exists to protect clients that predate the parameter — an agent that used to serve 0.3 must not silently reinterpret an old client’s requests under new semantics.

This listener has no such client to protect, so the default is the lenient reading:

An explicit unsupported version (A2A-Version: 0.3) is refused under both settings — the policy only governs absence. The parameter may also ride a query parameter (?A2A-Version=1.0), which §3.6.1 permits.

Set strict_version_header: true for a conformance harness, or for a deployment that will later front a 0.3 interface from the same origin.

Error envelopes

Each binding answers in its own shape, so a client parses one format per endpoint:

A2A defines no authentication error in its taxonomy: §3.3.2 names “HTTP 401 Unauthorized, gRPC UNAUTHENTICATED, JSON-RPC custom error”, leaving the code to the implementation. -32000 is the one value in JSON-RPC 2.0’s implementation-defined server-error range that A2A does not claim for itself (A2A reserves -32001…-32099), so it cannot collide with a protocol error a client already knows how to interpret. The HTTP status stays the authoritative signal; the body exists so a client that only parses envelopes still gets a well-formed one. The RFC 6750 WWW-Authenticate challenge and the Retry-After on 503 follow the same status mapping nexus.io.agui and the broker use — the denial kinds are the shared package’s transport contract, and one deployment should not answer the same refusal three different ways.

Example

plugins:
  nexus.io.a2a:
    bind: "0.0.0.0:8091"
    public_url: "https://agent.example.com"
    bearer_token_env: NEXUS_A2A_TOKEN
    cors_origins: ["https://console.example.com"]
    card:
      name: "Nexus Research Agent"
      description: "Runs research turns with web search and file tools."
      version: "1.2.0"
      documentation_url: "https://example.com/docs/agent"
      provider:
        organization: "Example Inc."
        url: "https://example.com"
      default_input_modes: ["text/plain"]
      default_output_modes: ["text/plain"]
      skills:
        - id: research
          name: "Research a topic"
          description: "Searches the web and summarizes findings with citations."
          tags: ["research", "search", "summarization"]
          examples:
            - "Summarize the last three papers on retrieval-augmented generation."

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:

The spawn_secret is a second factor for the dial-back socket. The lease id alone is a poor authenticator for it: the same value appears in ws_urls, client requests and logs, so anything that observes one could otherwise impersonate an instance. The broker records the expected value on the lease and injects it through the environment (never argv, which is world-readable). Both the lease id and the secret must match or the dial-back is closed with the same policy-violation close an unknown lease gets.

How the broker produces the value depends on whether it keeps state — the plugin echoes whatever it was handed either way. With no state_dir it is 128 bits of crypto/rand per spawn, held only in memory. With a state_dir it is derived as HMAC-SHA256(<state_dir>/spawn-key, lease_id), so a restarted broker can recompute the value a surviving instance still holds; the secret itself is still never written to disk. See Restart recovery.

Enforcement on the broker side is unconditional: every register frame must carry the secret, with or without an auth: block, on a freshly claimed lease or on one restored after a broker restart. It used to be gated on auth:, which meant an unauthenticated broker authenticated its dial-back socket with a lease id alone — a value that travels in ws_urls, client requests and logs. A nexus build that predates the protocol is therefore now refused everywhere, and removing the auth: block is no longer a workaround; upgrade the binary the binary registry entry points at. The value is never logged and never appears in GET /leases. See Instance dial-back authentication.

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: