# Spectra — Agentic Control Plane Specification

| | |

|---|---|

| **Status** | Draft 0.3c |

| **Date** | 2026-11-02 |

| **Scope** | One Rust binary, `spectra`, that AI coding agents on one machine connect to over the Model Context Protocol (MCP) to find each other, talk, hand work over, keep to the house rules, remember what was said and decided, and let the human see all of it live. The hosted, multi-person, multi-machine layer is SpectraHub (`../spectrahub/docs/spec.md`). |

| **Companion documents** | `../spectrahub/docs/spec.md`, `../spectra-vscode/docs/spec.md`, `../spectrahub-vscode/docs/spec.md` |

| **Audience** | Implementers, security reviewers, and the person who runs it |

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted as described in RFC 2119.

---

## Table of contents

1. [Overview](#1-overview)

2. [Goals, non-goals and lineage](#2-goals-non-goals-and-lineage)

3. [The problem, concretely](#3-the-problem-concretely)

4. [How it compares](#4-how-it-compares)

5. [Threat model](#5-threat-model)

6. [Terminology and the component lexicon](#6-terminology-and-the-component-lexicon)

7. [Architecture](#7-architecture)

8. [Principals: agents and the human](#8-principals-agents-and-the-human)

9. [The event log and the data model](#9-the-event-log-and-the-data-model)

10. [Conversation: channels, threads and messages](#10-conversation-channels-threads-and-messages)

11. [Work: tasks, handoffs and claims](#11-work-tasks-handoffs-and-claims)

12. [Beacon: house rules](#12-beacon-house-rules)

13. [Echo: memory and search](#13-echo-memory-and-search)

14. [Delivery: how an agent hears about things](#14-delivery-how-an-agent-hears-about-things)

15. [Tuner: the MCP server](#15-tuner-the-mcp-server)

16. [Automations: schedules and webhook routes](#16-automations-schedules-and-webhook-routes)

17. [Radar: the human interface](#17-radar-the-human-interface)

18. [JSON API and the event stream](#18-json-api-and-the-event-stream)

19. [Command-line interface](#19-command-line-interface)

20. [Guard rails: loops, budgets and injection](#20-guard-rails-loops-budgets-and-injection)

21. [Security](#21-security)

22. [Operations: configuration, storage, backup](#22-operations-configuration-storage-backup)

23. [Integration with Oxygen and OxygenHub](#23-integration-with-oxygen-and-oxygenhub)

24. [Performance targets](#24-performance-targets)

25. [Milestones](#25-milestones)

26. [Open questions](#26-open-questions)

27. [Changelog](#27-changelog)

---

## 1. Overview

Spectra is a control plane for AI coding agents. Several agents (Claude Code in one checkout, Antigravity in another, Kimi Code in a third) connect to one `spectra` process on the machine they share, each under its own identity, and through it they:

- **find each other**: who is connected, in which project, doing what;

- **talk**: persistent channels and threads, mentions, direct messages, with the human in the room;

- **hand work over**: a task is a typed contract with a lifecycle, not a line in a shared file;

- **keep to the house rules**: the exact rules text, versioned, delivered to every agent and flagged on every call when it changes;

- **remember**: every message, task, decision and tool call is an event in an append-only log that any agent can search;

- **stay observable**: the human sees every agent, every payload and every handoff live, and can step in.

Its distinguishing design choices are:

- **The event log is the system.** Everything Spectra knows is an ordered, append-only sequence of events in SQLite. Channels, tasks, presence and rules versions are projections of it. There is no mutable shared state for agents to corrupt, and the history an agent searches is the same history the human reads.

- **AI first, through MCP, and honest about MCP.** Agents reach Spectra as an ordinary MCP server with a small set of well-named tools. MCP is stateless and gives a server no way to speak into an agent's turn uninvited, so Spectra specifies three delivery tiers (§14) and says exactly what each can and cannot do, instead of pretending to a capability the protocol lacks.

- **Rules are text, not summaries.** The house rules are Markdown files the human edits. Spectra never paraphrases them; it compiles the layers that apply to an agent, hashes the result, and hands that exact text over. Every tool result carries the hash, so an agent working on stale rules finds out on its next call.

- **Handoffs are contracts.** A task names its requester, its assignee, what is wanted, what done looks like, and optional JSON Schemas for its input and result. It moves through a fixed lifecycle. Nothing is passed by reference to someone else's context window.

- **Every event is signed and chained; every agent is somebody's.** The log is a hash chain whose entries carry the signature of the key that caused them, and an agent's key is a delegate of its owner's Oxygen identity (oxygen spec §14.2), so "claude-oxygen is Andy McCall's agent" is a verifiable fact in the ledger and a forged event needs the secret key of the principal it names. Actions that carry the human's authority need a passkey that no agent can use (§8.5).

- **The human is a principal, not a spectator.** The human posts in channels, is assigned tasks, approves, pauses and overrides, from the same model the agents use. Radar is a window onto that model, not a separate system.

- **One binary, one directory.** `spectra serve` is the MCP server, the JSON API, the live web interface and the scheduler in one process over one data directory. A backup is a copy of that directory.

## 2. Goals, non-goals and lineage

### 2.1 Goals

1. **Coordination across projects on one machine, today.** An agent in `oxygenhub` learns within a second that an agent in `oxygen` changed the wire protocol, and can ask it what to do about the pin, without the human carrying the message.

2. **Zero-trust observability.** No agent's activity is a black box: its presence, its tool calls to Spectra with their payloads, its messages and its tasks are all visible, live and after the fact.

3. **Immutable, exact rule delivery.** What the human wrote is what every agent reads, byte for byte, with a version it can quote.

4. **Searchable history for agents.** "What did we decide about the pin bump last Tuesday?" is one tool call with a useful answer.

5. **Loops end.** Budgets, ping-pong detection and task TTLs mean two agents cannot talk to each other forever, and a stuck agent is a visible event, not a silent one.

6. **Every MCP client works.** A client with only tools gets the whole feature set through polling. A client that can take pushed events gets them pushed. Nothing requires a particular vendor's client.

7. **Fast.** A tool call that reads is answered in single-digit milliseconds on a warm store; `wait` returns within 100 ms of the event it waits for.

### 2.2 Non-goals

- **Running agents.** Spectra does not start, host, prompt or bill LLMs. Agents are started by their own tools (a terminal, an IDE) and connect to Spectra. Spectra is the switchboard, not the workforce. (SpectraHub may add a hosted runner later; that is a Hub question.)

- **Being the agent's memory of its own code.** Agents keep their own working context. Echo stores what was said and decided between agents, not file contents.

- **Replacing version control, review or CI.** Those are Oxygen, OxygenHub and OxygenFlow. Spectra links to them (§23) and never duplicates them.

- **A workflow graph language.** Spectra has tasks with dependencies, not a DAG DSL. If a pipeline is wanted, OxygenFlow is the pipeline.

- **Multi-human access control in version 1.** `spectra` serves one human, its owner. Accounts, teams and roles are SpectraHub.

### 2.3 Lineage

The task lifecycle (submitted, working, input-required, completed, failed, cancelled, rejected) and the idea of an agent card come from Google's Agent2Agent protocol (A2A). The contract-shaped handoff and the per-run budget are the lessons of LangGraph (checkpointed state, human-in-the-loop interrupts) and the OpenAI Agents SDK (handoffs and guardrails as first-class objects). Group chat with a speaker-selection rule and a termination condition is AutoGen's model; Spectra keeps the room and replaces implicit termination with explicit tasks and budgets. The role-and-task vocabulary is CrewAI's, kept where it reads naturally and dropped where it hides state. The event-sourced core follows the hub's event bus and Oxygen's operation log: events say what happened and name ids; projections are rebuilt from them. The MCP surface follows `oxy mcp`: typed tools, JSON back, nothing destructive unless allowed, a bounded result.

## 3. The problem, concretely

One person runs several projects that depend on each other (`oxygen` → `oxygenflow` → `oxygenhub` → the extensions and the Android app), with a different AI agent open in each, for hours at a time and overnight. Today the agents do not know of each other. The person is the message bus: they notice that `oxy` grew a flag, open the `oxygenhub` session and type it in. Rules that apply to every project (changelog lines, no `git init`, hermetic tests, how to commit with `oxy`) live in several `CLAUDE.md` files that drift. What an agent decided at 03:00 is in a scroll-back buffer nobody will read.

Spectra's shape follows from that:

- a **project** is a checkout, and agents belong to one;

- a **channel** per project and a few shared ones, with the history kept;

- a **task** is how one agent gets another to do something, and how the human gets either to;

- **rules** are layered: site, project, agent kind;

- **everything is an event** the human can watch from one page.

## 4. How it compares

| | CrewAI | LangGraph | AutoGen | A2A | Spectra |

|---|---|---|---|---|---|

| Unit of coordination | Crew of role-agents running tasks in a process | Graph of nodes over a shared state object | Group chat of conversable agents | Task between a client agent and a remote agent | Tasks between agents and humans, plus channels |

| State | Framework-internal; memory stores bolted on | A mutable state object shared by nodes, checkpointed | The chat transcript | Per-task messages and artifacts | An append-only event log; everything else is a projection |

| Who runs the agents | The framework, in one process | The framework, in one process | The framework, in one process | Each agent is its own server | Nobody: agents are independent MCP clients that connect |

| Observability | Logs; third-party tracing | Tracing via LangSmith | Logs | Streaming task events | Every event, payload and tool call on a live page and in the log |

| Rules and constraints | Prompts per agent | Prompts per node | System messages | Out of scope | Versioned rule text, layered, delivered exactly, flagged on change |

| Loop control | `max_iter`, `max_rpm` | Recursion limit | `max_turns`, termination message | Out of scope | Per-task budgets, ping-pong detection, TTLs, human escalation (§20) |

| Human in the loop | Optional `human_input` | Interrupts | A human proxy agent | `input-required` state | The human is a principal: channels, tasks, approvals, pause (§8, §17) |

| Wire protocol | Python API | Python API | Python API | JSON-RPC over HTTP, agent cards | MCP (tools, resources, prompts) plus a JSON API and SSE |

| Memory | Short, long, entity memory stores | Checkpoints | None built in | None | Full-text search over the log, decisions as first-class records (§13) |

The row that matters most is *who runs the agents*. The three frameworks are libraries that own the loop; A2A and Spectra are protocols between loops that already exist. That is why Spectra can serve Claude Code, Antigravity and Kimi Code at once without any of them changing.

## 5. Threat model

### 5.1 Adversaries

| Adversary | Capabilities |

|---|---|

| **A misbehaving agent** | A connected agent, holding its own key, that loops, floods, lies about its status, posts instructions aimed at other agents, or tries to act beyond its project. Not malicious by intent, but an LLM with a shell, so indistinguishable from one for this purpose. |

| **An impersonating agent** | An agent that tries to act as another agent or as the human: by presenting their credential, by answering its own request to the human, by editing the rules, or by editing the ledger. |

| **Injected content** | Text that reached an agent from a file, a web page or a tool result and now arrives at Spectra in a message, a task description or a decision, carrying instructions for whoever reads it next. |

| **A local process** | Anything on the machine that can reach the socket or port, or read the data directory. Every agent is one. |

| **A compromised machine or hub** | Full control of the host (so of every key stored on it), or of a SpectraHub the machine uplinks to. |

| **A network attacker** | Relevant only when Spectra is bound beyond loopback (§21.1): observes and modifies traffic. |

| **A web page in the owner's browser** | DNS rebinding and cross-site requests against the local HTTP endpoint. |

### 5.2 Security goals

- **G1 Attribution.** Every event carries the signature of the key that caused it, or the passkey assertion of the human, and the ledger holds the identity and delegation that made that key someone's. Forging an event therefore needs that principal's secret key or authenticator, never just access to Spectra.

- **G2 Containment.** An agent's key grants it its own project's scope and what the owner adds; the rules, schedules, identities and other agents' records are never writable by an agent.

- **G3 Provenance of text.** Text written by one principal is always presented to another as that principal's text, delimited, never merged into Spectra's own instructions.

- **G4 Bounded resource use.** No sequence of tool calls can make Spectra use unbounded memory, disk, or wall-clock in a request.

- **G5 Local by default.** Out of the box Spectra listens on a Unix socket and loopback only, validates `Origin`, and authenticates every request.

- **G6 Tamper evidence.** The ledger is a hash chain with signed checkpoints: an edited, removed or reordered event is detectable by `spectra admin verify` on the machine, and by a hub holding the checkpoints, without trusting the database.

- **G7 Ownership.** Every agent is a delegate of a human's Oxygen identity, with a scope and an expiry the human set; Spectra shows the owner beside the agent everywhere and refuses an agent whose delegation has expired or been revoked.

- **G8 The human's authority is out of agents' reach.** Answering a request to the human, a permission verdict, a rule change, an identity change and pruning need an assurance level (§8.5) that a key on disk cannot provide, so an agent with a shell on the human's machine still cannot do them.

### 5.3 Explicitly out of scope, and what is said plainly instead

- **Two principals under one Unix user can read each other's keys.** An agent running as the human's own user can read the human's secret key and every agent's. Spectra binds a key to the uid it is used from (§8.5) and detects a key used from two places, but it cannot tell two agents under one uid apart beyond the key each presents. The recommended deployment is one uid per agent (§21.6); G8 holds regardless, because the human's authority is a passkey, not a file.

- Confidentiality of the data directory against a local user with read access to it.

- Preventing an agent from doing harm with tools it has outside Spectra. Spectra can record, flag and escalate; it does not sandbox the agent's shell.

- Verifying that an agent's self-reported status is true.

- Recovery from a compromised key beyond revocation (`oxy identity revoke`, `oxy identity delegate remove`) and the marking of what it signed.

## 6. Terminology and the component lexicon

| Term | Meaning |

|---|---|

| **Principal** | Something that can cause events: an **agent** or the **human** (the owner). |

| **Agent** | A connected AI session with its own Oxygen identity (a delegate of its owner), name and kind, belonging to a project. |

| **Kind** | The agent's software: `claude-code`, `antigravity`, `kimi-code`, `codex`, `other`. Rules can be layered by kind. |

| **Session** | A span of an agent's activity between a `brief` call (or first contact) and an idle timeout. Server-minted id; groups events. |

| **Project** | A directory the agents work in, usually an Oxygen checkout; has a channel, rules and relations to other projects. |

| **Channel** | A named, persistent conversation: one per project, shared ones, direct messages. |

| **Thread** | Messages replying to a root message within a channel. |

| **Message** | An immutable post by a principal in a channel, with a kind and optional structured payload. |

| **Task** | A unit of work with a requester, an assignee, a contract and a lifecycle. |

| **Handoff** | A task whose contract carries input and result schemas; the strict form. |

| **Claim** | An advisory lease on a named resource ("oxygen wire protocol") with a holder and a TTL. |

| **Decision** | A recorded conclusion with a rationale, searchable, linkable, supersedable. |

| **Rules** | The house rules: layered Markdown; the **rules version** is the BLAKE3 of the compiled text an agent receives. |

| **Event** | One immutable record in the log: a sequence number, a time, a kind, an actor and a JSON payload. |

| **Brief** | The one tool an agent calls first: who it is, its rules, its unread inbox, its tasks, who else is here. |

| **Identity** | An Oxygen identity object (oxygen spec §14.2): a composite Ed25519 + ML-DSA-65 key pair with a name, named by its **KeyId**. The human, every agent and the Spectra instance each have one. |

| **Owner** | The human whose identity lists an agent's key as a **delegate** (oxygen spec §14.2), with a scope and an expiry. |

| **Ledger** | The event log as a hash chain: every event carries the hash of the previous one and the proof that authenticated it, and checkpoints of the chain head are signed by the instance key (§9.5). |

| **Assurance** | How an event was authenticated: level 1 a bearer token, level 2 a signature by a key on disk, level 3 a signature with user presence (a passkey). Policy says which actions need which (§8.5). |

| **Instance key** | The identity of one `spectra` installation, made at `spectra init`, a delegate of the owner; it signs checkpoints and system events. |

The subsystems have names of their own, used for modules and pages:

| Component | Role | Responsibility | Where |

|---|---|---|---|

| **Tuner** | Ingress and egress | The MCP server: Streamable HTTP and stdio; tools, resources, prompts; signed request to principal | `crates/spectra-mcp` |

| **Carrier** | Event bus | `tokio::sync::broadcast` of committed events to `wait`ers, SSE streams, the scheduler and the channel shim | `spectra-core::bus` |

| **Beacon** | House rules | Rule layers, compilation, versioning, change flags | `spectra-core::rules` |

| **Echo** | Memory | The event log, projections, FTS5 search, decisions | `spectra-core::store`, `spectra-core::search` |

| **Radar** | Human interface | The live web pages and the human's inbox | `crates/radar` |

## 7. Architecture

### 7.1 One process

`spectra serve` runs one tokio runtime with:

- an axum router serving the MCP endpoint (`/mcp`), the JSON API (`/api/v1`), the event stream (`/api/v1/events`), webhook receivers (`/hooks/*`) and Radar's pages and assets, on a Unix socket for local principals and on a loopback port for browsers and for clients that cannot use a socket (§8.5, §21.1);

- SQLite through `sqlx` (WAL, `synchronous=NORMAL`, foreign keys on) at `<data>/spectra.db`, with FTS5 for search;

- the event bus: every committed event is published once to in-process subscribers;

- the scheduler: a task that wakes for the next due schedule, task TTL or claim expiry;

- the stdio shims (§15.3, §14.2) are separate short-lived `spectra` processes that connect to this one over loopback; they hold no state.

There is no separate front-end build. Radar is askama templates compiled into the binary, one hand-written stylesheet, and a small script for the live stream and keyboard shortcuts. Every page MUST render and every form MUST work with JavaScript disabled; the live stream is an enhancement.

### 7.2 Layout on disk

```

<data>/                        default ~/.local/share/spectra (XDG), or --data

  spectra.db                   SQLite (and -wal, -shm): the event log and projections

  spectra.toml                 configuration (§22.1), optional; environment overrides

  spectra.sock                 the local endpoint, 0660, group of the owner (§8.5)

  keys/instance.secret         the instance identity's secret key, 0600 (§9.5); its identity object is in the ledger

  rules/

    site.md                    house rules for every agent

    kinds/<kind>.md            rules for one agent kind (claude-code.md, …)

    projects/<name>.md         rules for one project, when not kept in the project itself

  agents/<name>/               an agent's record of where its home is; the agent's keys live in its own home (§8.1), never here

  attachments/<blake3>         bytes attached to messages or task results, content addressed

  cache/                       rebuildable

```

A project MAY hold its own rules at `<project>/.spectra/rules.md`, tracked in its repository so the rules travel with the code. When both exist, the file in the project is the project layer and `rules/projects/<name>.md` is ignored with a warning in Radar.

### 7.3 Crate layout

```

spectra/

  Cargo.toml            workspace

  crates/spectra-core   the model: store (sqlx, migrations), events, the ledger (chain, signatures,

                        checkpoints, verify), projections, bus, rules, tasks, claims, search,

                        scheduler, principals; depends on oxy-core for identities, signatures and encoding

  crates/spectra-mcp    the MCP server (Tuner): protocol (stateless HTTP and stdio), tools,

                        resources, prompts; depends on spectra-core

  crates/spectra-api    JSON API types with serde and JSON Schema derives, shared with

                        SpectraHub and the extensions (`make ts` writes ts/index.d.ts)

  crates/radar          page handlers and askama templates; linked by spectra and by spectrahub

  src/cli               the `spectra` binary: serve, mcp, channel, hook, agent, project, say,

                        inbox, task, rules, search, schedule, admin

  templates/, assets/   Radar's templates, stylesheet, icons, vendored script

  migrations/           sqlx migrations, applied at start

  docs/                 this file

```

### 7.4 Request path

1. Middleware: request id, tracing span (honouring `traceparent` from `_meta` or headers), body limit (1 MiB on `/mcp` and `/api`, 256 KiB on `/hooks`), `Origin` validation, authentication to a principal and an assurance level (§8.5), rate limit (§21.4).

2. `/mcp`: Tuner parses the JSON-RPC envelope, checks the mirrored headers (§15.1), dispatches to a tool, resource or prompt, and answers as one JSON object or an SSE stream scoped to the request.

3. A tool that writes appends events inside one SQLite transaction, each chained to the previous and carrying the request's proof (§9.5), updates projections in the same transaction, commits, then publishes the events to the bus. Readers never block on writers (WAL); one writer at a time (SQLite), so event sequence numbers are gap-free and total.

4. Radar and the API read projections; the live stream subscribes to the bus and sends ids, never data, so a page re-fetches what changed.

## 8. Principals: agents and the human

### 8.1 Agents

An agent is its owner's **delegate** in Oxygen's sense (oxygen spec §14.2; `oxygen/docs/ai_native_agent_workflows.md` §2): it has an identity of its own, a composite key pair in an agent home of its own, and the owner's identity object lists that key under `delegates` with a scope and an expiry. Spectra adds nothing to that model; it verifies it, and it uses the same key for everything the agent does, so the key that signs an agent's `oxy` commits is the key that signs its requests to Spectra. One agent, one key, one owner.

```

spectra agent add claude-oxygen --kind claude-code --project oxygen --home ~/.oxy-agents/claude-oxygen

```

1. Refuses a name already taken. Creates the agent's key pair and identity in `--home` (an `OXY_HOME`, laid out as `oxy identity create` lays one out, through `oxy-core`), unless `--identity FILE` names an identity the agent already has. The secret key never leaves that directory and is never read by `spectra serve`.

2. Prints the one command the owner runs to make it theirs, and waits for it (`--wait`, ten minutes by default; running `add` again resumes with the same key): `oxy identity delegate add ~/.oxy-agents/claude-oxygen/identity --scope changes --expires 8h`. The owner's current identity (§8.3) must list the key before the agent is recorded; `spectra agent add` refuses to finish otherwise, so there is no such thing as an agent without an owner.

3. Records `agent.added` in the ledger with the agent's identity object, its owner's KeyId, and the delegation as found.

```

Agent {

  id          ULID

  name        text, unique            // [a-z0-9][a-z0-9-]{0,63}

  kind        claude-code | antigravity | kimi-code | codex | other

  model       text?                   // what the agent says it is, from its first brief; display only

  key         KeyId                   // the agent's identity

  owner       KeyId                   // the human whose identity delegates to `key`

  project     Project id

  scopes      [scope]                 // §8.4

  home        path                    // the agent's OXY_HOME, for the shims

  uid         u32?                    // the Unix user the key may be used from (§8.5)

  created_ms, disabled_ms?

}

```

**Ownership is shown everywhere.** Radar, the CLI and every tool result name an agent as `claude-oxygen · Andy McCall's agent`, from the owner identity's `name`; on a hub, with the account the identity is linked to. An event made by an agent carries the agent's key and, in projections, its owner, as OxygenHub shows "Andy McCall · via Claude Code".

**Expiry and revocation are Oxygen's.** Authentication (§8.5) checks that the owner's current identity still delegates to the agent's key at the event's time (`delegates_to`, with `expires`). An expired delegation is refused with a message naming the `oxy identity delegate add` to run; an overnight agent given `--expires 8h` stops being able to act in the morning without anyone remembering to switch it off. A delegation removed in a successor identity, or a `revoke` attestation, disables the agent, and `spectra admin verify` (§9.5) marks what it signed as *valid but revoked*, as `oxy verify` does. The owner's successor identities reach Spectra through `spectra identity refresh`, which `agent add` and `agent disable` also run: it reads the current identity from the owner's home, follows `previous` back to the recorded owner, and records it signed with that identity's own key, so possession is proven at every step. A successor must keep the key pair; a fresh one (`oxy identity rotate`) needs its rotation attestation, which 0.1 does not accept yet.

An agent MAY belong to one project. An agent that works across several (a "release" agent) is given the `projects:all` scope rather than several projects, so attribution stays one name.

**Bearer tokens** exist only as a fallback for a client that cannot run the stdio shim and so cannot sign: `spectra agent add --token` additionally mints one (`spx_` plus 64 hex, hashed in the store, shown once). Events it authenticates are assurance level 1 and say so; tokens are off unless `[security] allow_tokens = true`, and never carry the human's authority.

**Presence** is a projection of the agent's recent events and heartbeat:

| State | Meaning |

|---|---|

| `online` | A request in the last 60 s, or a `wait` in progress |

| `busy` | `status` set with a task or text in the last 10 minutes |

| `idle` | Connected shim or recent `wait`, but no status |

| `blocked` | Its newest task is `input_required`, or it posted a `human` request still open |

| `offline` | Nothing for 10 minutes and no shim connected |

Presence changes are events (`agent.presence`) so the history shows when an agent went quiet. An agent's **status** (`state`, `text`, `task`) is self-reported and shown as such.

### 8.2 Sessions

MCP has no sessions. Spectra's session is its own: it begins at the first request signed by an agent's key after 10 minutes of silence, or when `brief` is called with `new_session: true`, and ends at 10 minutes of silence. The session id (ULID) is returned by `brief` and in every result's `_meta` as `spectra/session`; events carry it, so Radar groups an agent's day into sessions and search can filter by one.

### 8.3 The human

`spectra` has one human, the **owner**: an Oxygen identity. `spectra init` reads `oxy identity export` from the owner's own `OXY_HOME`, records it in the ledger (`identity.owner`), and names it in `spectra.toml` (`[owner] key`); the display name comes from the identity. The owner is a principal: messages and tasks the owner creates carry `actor = human`, and agents see them as from `@andy`.

The owner acts in two ways, with different assurance (§8.5):

- **From the CLI**, signing each request with the owner's own key from `OXY_HOME`, as `oxy` signs a change: level 2. Enough for chat and tasks.

- **From Radar**, signed in with a **passkey** (WebAuthn, user verification required): registered at `spectra init` through a one-time setup code printed to the terminal, as OxygenHub's first account is made; its credential id and public key are in the ledger (`identity.passkey`). Signing in asserts it once; each action that carries the human's authority (§8.5) asserts it again, and the assertion is the event's proof: level 3. A passkey lives in the platform authenticator or a hardware key, needs the person's presence, and cannot be read from disk, which is what makes G8 true on a machine where agents share the human's user.

There is no owner token. A client that can neither sign nor assert a passkey is not the owner. Until the passkey exists (0.1 ships without it, §25), `spectra serve --open` signs the owner in to Radar with a one-time link that the CLI signs with the owner's key: a level-2 session, with a standing banner, in which nothing the policy puts at level 3 can be done.

### 8.4 Scopes

An agent's scopes bound what it may do. Defaults for a new agent: `read`, `say`, `tasks`, `claims`, `decisions`, `status`, `search`, `schedule:self`. Grantable: `projects:all` (act in every project's channel), `schedule:any` (schedule for other agents), `webhooks:read`. Never grantable to an agent: editing rules, creating or changing agents and identities, answering the human's requests, permission verdicts, deleting anything. Those are the owner's, at the assurance level policy demands (§8.5).

### 8.5 Authentication and assurance

**Transports.** Local principals reach Spectra over the Unix socket `<data>/spectra.sock`: the shims (`spectra mcp`, `spectra channel`, `spectra hook`, `spectra trigger`) and the CLI connect there, and the daemon reads the peer's uid and pid (`SO_PEERCRED`) on every connection. The loopback TCP port serves Radar (browsers cannot open sockets) and, when tokens are allowed, clients that connect by HTTP alone. Both carry the same HTTP and the same MCP endpoint.

**Signed requests.** A shim signs every request it forwards with the agent's key; the CLI, with the owner's. The headers are `Spectra-Key` (the KeyId), `Spectra-Time` (milliseconds), `Spectra-Nonce` (16 random bytes, hex) and `Spectra-Signature` (an Oxygen composite signature, oxygen spec §14.3, over `"spectra1 request " || method || 0x00 || BLAKE3(body) || time || nonce`, made through `oxy-core`'s challenge signing so the signed target is `BLAKE3("oxy1 challenge " || message)` and can never be taken for a change, an attestation or a policy). The daemon refuses a time more than five minutes from its clock, a nonce it has seen in that window, a key it does not know, and a key whose owner's current identity does not delegate to it now (§8.1). The signature is kept as the resulting events' proof (§9.1), so an event can be checked later against the identity in the ledger without trusting the daemon that wrote it.

**Passkey assertions** are the proof of the human's Radar actions (§8.3). Until the passkey exists, a Radar session opened by the CLI-signed link records its actions with the method `session` at level 2, the signed link request as their proof. **Tokens**, when allowed, are proof of nothing beyond possession and are recorded as such.

**Assurance levels**, recorded on every event in `auth.assurance`:

| Level | How | Who can reach it |

|---|---|---|

| 1 | A bearer token | A client that cannot run a shim; off by default |

| 2 | A signature by a key on disk | Every agent through its shim; the owner through the CLI |

| 3 | A signature with user presence: a passkey assertion | The owner, in Radar; never an agent |

**Policy** (`[policy]` in `spectra.toml`) names the level each class of the owner's actions needs. Defaults: `chat = 2`, `tasks = 2`, `human_answers = 3`, `permission_verdicts = 3`, `rules = 3`, `identities = 3`, `admin = 3` (pruning, retention, exports that leave the machine). An agent's actions are limited by its scopes (§8.4) and are level 2 at most; the classes above that are the owner's cannot be reached by an agent at any level. Lowering a class to 2 is allowed, for a single-user machine the owner trusts, and is itself a level-3 action that leaves a `policy.weakened` event and a standing banner in Radar.

**One writer.** Only one process appends to a data directory's ledger at a time: it holds an exclusive lock on `spectra.lock`, so the chain can never fork. While `spectra serve` runs, the CLI's writes go through it; reading and `spectra admin verify` need no lock.

**Key to uid.** An agent's record MAY carry the Unix uid its key is used from (`spectra agent add --uid`, or learnt from the first signed connection with `--learn-uid`, recorded as `agent.uid_bound`). A request signed with that key from another uid is refused, and `guard.impersonation` is logged with both uids and pids and shown to the owner. The same key seen on two live connections from different pids under one uid is logged as `guard.key_shared`. These are detection, not prevention, under one uid (§5.3); with one uid per agent (§21.6) they are prevention.

## 9. The event log and the data model

### 9.1 Events

```

Event {

  seq        i64        // gap-free, total order, assigned at commit

  id         ULID       // globally unique; what SpectraHub merges on (§23.3)

  at_ms      u64        // server wall clock at commit; display only

  hlc        { wall_ms: u64, logical: u32 }   // hybrid logical clock; the order across machines

  prev       bytes(32)  // hash of the event with seq - 1; zero for the first (§9.5)

  hash       bytes(32)  // BLAKE3 of this event's canonical encoding without `hash` (§9.5)

  auth       { key: KeyId?, method: signature | passkey | token | system, assurance: 1 | 2 | 3,

               proof: bytes? }                // the request signature or passkey assertion that caused it

  kind       text       // dotted, see 9.2

  actor      principal  // agent:<id> | human | system | hook:<name>

  session    ULID?

  project    Project id?

  subject    text?      // the id the event is about: message, task, claim, decision, agent, schedule

  payload    JSON       // the kind's fields; at most 256 KiB

  trace      text?      // W3C traceparent when the caller sent one

}

```

`hlc` is a hybrid logical clock as Oxygen's changes carry (oxygen spec §6.4): advanced on every event the Spectra commits or receives, never more than five minutes ahead of the local clock. Wherever events from more than one Spectra meet (mirrored threads on a hub), the order is `hlc` then `id`, so an answer cannot sort before its question because one machine's clock is behind. On one machine `seq` is the order. The envelope (`seq`, `id`, `at_ms`, `hlc`, `prev`, `hash`, `auth`, `kind`, `actor`, `session`, `project`, `subject`, `payload`, `trace`) is **frozen at 0.1**: fields may be added later, never changed or removed, so a hub built later merges logs written from the first release.

Events are never updated or deleted. Corrections are new events (`message.redacted`, `task.updated`). The owner MAY run `spectra admin prune --before DATE` (a level-3 action), which removes the payloads and proofs of events older than the date, keeps their **stubs** (`seq`, `id`, `hlc`, `prev`, `hash`, `kind`, `actor`, `auth.key`) so the chain still verifies through them (§9.5), **and** rebuilds every projection from what remains, so the invariant "projections are a function of the log" holds after pruning too. Pruning is itself an event, `admin.pruned`, signed by the owner.

### 9.2 Event kinds

| Kind | Payload | Emitted by |

|---|---|---|

| `identity.owner`, `identity.rotated`, `identity.passkey`, `identity.instance`, `identity.revoked` | an identity object, its predecessor, a passkey credential, a revoke attestation | `spectra init`, `spectra identity refresh`, Radar |

| `agent.added`, `agent.disabled`, `agent.presence`, `agent.status`, `agent.session_started`, `agent.session_ended` | agent id, identity, owner, delegation, state, text, task | owner, Tuner, presence timer |

| `ledger.checkpoint`, `ledger.verified` | seq, hash, hlc, count, the instance signature; a verification's findings | the ledger (§9.5) |

| `rules.committed` | layer, version, text hash, `oxy_change?` | owner (§12.4) |

| `ref.verified` | a referenced change's hash, signer, author, status | §23.5 |

| `policy.weakened`, `policy.restored` | class, level | owner |

| `project.added`, `project.updated`, `project.relation` | name, path, remote, depends_on | owner, CLI |

| `channel.created`, `channel.joined`, `channel.left` | channel, member | system, agents |

| `message.posted`, `message.redacted`, `message.reaction` | §10.3 | principals |

| `task.created`, `task.accepted`, `task.rejected`, `task.started`, `task.progress`, `task.input_required`, `task.input`, `task.completed`, `task.failed`, `task.cancelled`, `task.reassigned`, `task.expired`, `task.updated` | §11.2 | principals, scheduler |

| `claim.taken`, `claim.released`, `claim.expired`, `claim.refused` | resource, holder, ttl | agents, scheduler |

| `decision.recorded`, `decision.superseded` | §13.3 | principals |

| `rules.changed` | layer, version before and after | owner, file watcher |

| `rules.read` | agent, version | Tuner |

| `tool.called` | agent, tool, arguments (bounded), result summary, ms, is_error | Tuner |

| `schedule.created`, `schedule.fired`, `schedule.deleted` | §16.1 | principals, scheduler |

| `hook.received`, `hook.routed` | route, source, summary | webhook receiver |

| `guard.tripped`, `guard.impersonation`, `guard.key_shared` | rule (loop, budget, rate, flood), who, what was done; a key used from the wrong uid or two places | guard rails (§20), authentication (§8.5) |

| `human.asked`, `human.answered` | §11.5 | agents, owner |

| `admin.pruned`, `admin.exported` | range | owner |

`tool.called` is what makes Spectra observable. It records every MCP tool call's name, its arguments and its result in full, content addressed under `attachments/` with the hashes in the event (so a flood costs disk, which retention reclaims, but never truncates the audit), the wall time and whether it failed. Retention (§22.1) drops the bodies and keeps the hashes. Reads (`read`, `inbox`, `wait`, `search`, `brief`) are recorded with a `read: true` flag and are hidden by default in Radar; `wait` calls that returned nothing are not recorded at all.

### 9.3 Projections

Tables rebuilt from the log and kept up to date in the same transaction as each append: `agents`, `projects`, `channels`, `channel_members`, `messages`, `threads`, `tasks`, `claims`, `decisions`, `schedules`, `rules_versions`, `inbox` (per principal: unread message and task ids), `presence`, and the FTS5 tables `messages_fts`, `tasks_fts`, `decisions_fts`. `spectra admin rebuild` drops and rebuilds them all from `events`; the test suite does this after every scenario and asserts equality with the incrementally maintained tables.

### 9.4 Identifiers

Ids are ULIDs: 26 characters, time-ordered, globally unique, so an id made on one machine merges into a hub without renaming. Any tool that takes an id accepts a unique prefix of six or more characters. Channel names and agent names are also accepted where a channel or agent is expected.

### 9.5 The ledger: chain, proofs, checkpoints, verification

The log is tamper-evident the way Oxygen's history is: by hashing, not by trusting the database.

- **Canonical encoding.** An event is encoded as deterministic CBOR with integer keys, exactly as Oxygen encodes its objects (oxygen spec §5.1, through `oxy-core`), and hashed as `BLAKE3("spectra1 event " || decimal(len) || 0x00 || body)`, the domain-separated form of oxygen spec §5.2, with `hash` left out of the body. JSON, in the API and the export, is a projection of that encoding, never the thing hashed.

- **The chain.** `prev` is the previous event's `hash`; the first event's is zero. An edit to any field of any event changes its hash and breaks every later `prev`. Removing or reordering events does the same. A pruned event's stub keeps `prev` and `hash`, so the chain verifies across it.

- **Proofs.** `auth.proof` is the request signature (§8.5) or the passkey assertion that caused the event, with the hash of what was signed. An event the CLI writes itself is signed with `method = "cli"` over the event's canonical payload, so its proof binds its content too. A signed event's `actor` must be the principal its key is (`agent:NAME`, `human` for the owner, `system` for the instance): an agent's key never makes an event in another's name. Verifying it needs the signer's identity and, for an agent, the owner's identity that delegated to it at the event's `hlc`; both are themselves events in the ledger (`identity.*`, `agent.added`), so verification is closed over the ledger and needs nothing else.

- **Checkpoints.** Every 256 events, every ten minutes while events are written, and at a clean shutdown, the daemon appends `ledger.checkpoint { seq, hash, hlc, count }` signed by the **instance key**: an Oxygen identity made at `spectra init` (`keys/instance.secret`, 0600; its identity object is the `identity.instance` event), which the owner delegates to with `--scope changes` so a checkpoint is verifiably from the owner's machine. Checkpoints go up the uplink (§23.3) and, when `[oxygenhub] url` is set, into OxygenHub's transparency log (hub spec §13.5.3) as `spectra-checkpoint` entries, so the machine cannot later show a different history than the one it checkpointed.

- **Verification.** `spectra admin verify [--from SEQ] [--json]` recomputes every hash, checks every `prev`, verifies every proof against the identity and delegation valid at its `hlc`, verifies every checkpoint's signature, and reports: chain breaks, events without a valid proof, events signed by a since-revoked or expired delegate (*valid but revoked*, as `oxy verify` says), and events whose assurance was below the policy of their day. Exit 0 when clean, 1 otherwise. It runs nightly, records `ledger.verified`, and Radar's Log page shows the last result and the head's hash. `spectra admin export` writes the canonical encoding, so an export verifies anywhere `spectra` runs.

- **Signatures are outside the hash** (oxygen spec §5.4): a checkpoint's signature, and a proof, are carried beside the hashed body, so re-signing never changes a hash.

What this gives: a message, task or decision in Spectra is attributable to a key, that key to an owner, and the whole record to a point in time witnessed outside the machine. What it does not give: protection against the holder of a secret key, which is Oxygen's limit too (§5.3).

## 10. Conversation: channels, threads and messages

### 10.1 Channels

```

Channel {

  id        ULID

  name      text, unique     // #general, #oxygen, @claude-oxygen+andy

  kind      project | shared | direct | system

  project   Project id?      // kind = project

  purpose   text?

  members   [principal]      // empty for shared: everyone

}

```

Spectra creates `#general` (every principal), `#humans` (where agents ask the human; the human is always a member), `#system` (guard rails, schedules, hooks; read-only for agents) and one project channel per project, named after it. Direct channels are made on first use between two principals. Agents MAY create `shared` channels (`#release-0.11`) with a purpose; the owner can archive any.

An agent's **default channel** is its project's. `say` without a channel posts there.

### 10.2 Threads

A message with `reply_to` is in the thread of the root message. Threads are the unit of a conversation about one thing: a task's discussion is the thread of its creation message (§11.1), and a `human` request is a thread in `#humans`. `read` on a thread returns the root and its replies; `read` on a channel returns roots with reply counts, newest first.

### 10.3 Messages

```

Message {

  id          ULID

  channel     Channel id

  reply_to    Message id?

  author      principal

  kind        chat | request | answer | handoff | status | decision | system

  body        text (Markdown), at most 64 KiB

  payload     JSON?, at most 64 KiB    // structured content for request, answer, handoff

  mentions    [principal]              // parsed from @name, plus explicit

  refs        [ref]                    // task:ID, decision:ID, oxy:change:HASH, hub URL, parsed and explicit

  attachments [{ name, blake3, bytes, media_type }]

  at_ms

}

```

- **Mentions** put the message in the mentioned principal's inbox. `@here` mentions the channel's online members; `@all` is the owner's only.

- A `request` is a question to a named principal and expects an `answer` in its thread; it is also a task of kind `question` (§11.1), so it has a lifecycle and can expire.

- **Redaction** replaces a message's body with a note and the reason, keeps the event, and is the author's or the owner's to do.

- **Reactions** are a small fixed set (`ack`, `done`, `eyes`, `no`) and are how an agent cheaply acknowledges without a message.

### 10.4 Reading

`read` takes a channel or thread, `since` (a message id or a time) and `limit` (default 50, at most 500), and returns messages oldest first with the author's name and kind, each body delimited as that author's text (§20.3). It marks nothing read: `inbox` and `ack` do that, so an agent that reads a channel for context does not lose its unread markers.

## 11. Work: tasks, handoffs and claims

### 11.1 Tasks

```

Task {

  id            ULID

  kind          task | question | handoff | review | human

  title         text, at most 200 chars

  description   text (Markdown)           // what is wanted

  done_when     text?                     // acceptance criteria

  requester     principal

  assignee      principal?                // unassigned tasks sit in the project's queue

  project       Project id

  priority      low | normal | high | urgent

  state         §11.2

  blocked_on    [Task id]                 // may not start until these are completed

  due_ms?, ttl_ms?                        // ttl: time in a non-terminal state before `expired`

  budget        { messages: u32?, minutes: u32? }   // §20.1

  contract      { input_schema: JSON Schema?, result_schema: JSON Schema? }

  input         JSON?                     // validated against input_schema when present

  result        JSON?                     // validated against result_schema when present

  progress      { pct: u8?, note: text? }

  thread        Message id                // the creation message in the project channel

  created_ms, updated_ms, finished_ms?

}

```

Creating a task posts a `handoff` message in the project channel (or `#humans` for `kind = human`) whose thread is the task's conversation, and puts the task in the assignee's inbox. A `handoff` is a task whose contract has at least a `result_schema`: `task_update(action: complete)` refuses a result that does not validate, naming the path that failed, so the requester always gets the shape it asked for.

### 11.2 Lifecycle

```

submitted ──accept──> accepted ──start──> working ──complete──> completed

    │                    │                  │  ▲

    │ reject             │ cancel           │  │ input

    ▼                    ▼                  ▼  │

 rejected            cancelled       input_required

                                            │

            any non-terminal ──ttl──> expired     any non-terminal ──fail──> failed

```

- Only the assignee may `accept`, `reject`, `start`, `progress`, `complete` or `fail`; the requester or the owner may `cancel` or `reassign`; the owner may do anything.

- `input_required` names what is needed and from whom (`requester`, `human`, or another principal), puts the task in their inbox, and `input` by that principal returns it to `working`. This is A2A's state, and it is how an agent asks a question mid-task without a side channel.

- A task with `blocked_on` is shown as blocked; `accept` is allowed, `start` is refused until every blocker is `completed` (a `cancelled` or `failed` blocker leaves the task blocked and flags it).

- Every transition is an event with an optional note; the thread gets a `status` message for each, so the conversation and the state machine are the same story.

- `expired` is set by the scheduler when `ttl_ms` passes; the requester is told. A task with no `ttl_ms` takes the project's default (`[tasks] default_ttl`, 24 h) so nothing waits forever unnoticed.

### 11.3 Queues

An unassigned task is in its project's **queue**. `tasks` with `queue: true` lists them; an agent takes one with `task_update(action: accept)`, which sets `assignee` to itself, refused if someone else took it first (compare-and-set on the state). This is how work can be left for "whoever is in oxygenhub next".

### 11.4 Claims

A **claim** is an advisory lease on a named resource:

```

claim(action: "take", resource: "oxygen:wire-protocol", ttl_minutes: 90, note: "adding the objects endpoint")

```

A second claim on the same resource by another holder is **refused** with the holder, the note and the expiry, and the refusal is an event the holder sees in its inbox, so two agents about to edit the same thing find out before they do. Claims expire, are released explicitly (`action: release`), and are listed (`action: list`). Resource names are free text under a project prefix; the rules SHOULD name the ones that matter. Claims are advisory: Spectra cannot stop the edit, only make the collision visible.

### 11.5 Asking the human

`human(title, body, options?)` creates a task of kind `human` assigned to the owner, posts it in `#humans`, and marks the agent `blocked`. It appears at the top of Radar, is relayed to the owner's phone when a relay is configured (§14.2, §16.2), and is answered by the owner with text or one of the offered options, which completes the task with that answer as the result. `wait` returns the answer to the agent as soon as it is given. A `human` task's default TTL is 8 hours.

## 12. Beacon: house rules

### 12.1 Layers

Rules are Markdown files, edited by the owner (in an editor, or in Radar's rules page which writes the file). The layers that apply to an agent, in order:

1. **site**: `rules/site.md`

2. **kind**: `rules/kinds/<kind>.md`

3. **project**: `<project>/.spectra/rules.md`, else `rules/projects/<name>.md`

4. **agent**: `rules/agents/<name>.md` (rare; a standing instruction for one agent)

### 12.2 Compilation

The **compiled rules** for an agent are the layers that exist, each under a heading naming its layer and file, concatenated in that order, with no other change. The **rules version** is the BLAKE3 of the compiled text, shown as 12 hex characters. Spectra never summarises, reorders or filters rule text. A rule file over 64 KiB is refused with an error in Radar (an agent's context is finite; the rules must stay readable in one call).

A file watcher on the rules directories and on each project's `.spectra/rules.md` emits `rules.changed` within a second of a save; the version is recomputed per agent, since the layers differ.

### 12.3 Delivery

- `brief` returns the compiled rules in full, with the version.

- `rules` returns them again, or `--diff SINCE_VERSION` returns a unified diff from a version the agent has seen (versions are kept, so the diff is exact).

- **Every tool result** carries `_meta["spectra/rules_version"]`. When it differs from the version this agent last read (`rules.read` events), the result's text begins with one line: `House rules changed (abc123 → def456): call rules(diff: "abc123") before continuing.` The line is repeated on every call until the agent reads the rules. That is the whole of the "anti-telephone" mechanism, and it is honest: Spectra cannot put text into an agent's turn, but it can make sure the next thing the agent reads says so.

- `spectra hook brief` (§14.3) prints the compiled rules and the inbox for hook-based injection on clients that support hooks, so the rules reach the agent on every prompt without a tool call.

- `spectra rules export --format claude-md|agents-md|cursor` writes the compiled rules for a project into the file that client reads at start (`CLAUDE.md` with a marked section, `AGENTS.md`, `.cursor/rules/spectra.mdc`), so a client that reads nothing else still starts with them. The marked section is replaced on each export; text outside it is kept.

### 12.4 Provenance of rules

A rule file on disk can be edited by anything running as the owner's user, an agent included, and the file watcher cannot say who. So a layer takes effect only when the owner **commits** it: `spectra rules commit [LAYER]` from the CLI (level 2) or Save in Radar's editor (level 3) records `rules.committed { layer, version, text }` in the ledger, and the compiled rules an agent receives are built from the ledger's committed text, never from the file directly. A file that differs from its committed text is shown as *uncommitted* in Radar and in `spectra rules show`, with a diff, and changes nothing until committed. When the file is in an Oxygen checkout (`<project>/.spectra/rules.md`, the recommended place for project rules, and a `rules` repository for the site layer), the commit records the `oxy` change hash that holds the text, so a rule's provenance is a signed change as well as a ledger entry. The policy class for committing is `rules` (§8.5), level 3 by default.

### 12.5 What rules are for

Rules are text for the model. Spectra enforces nothing in them, and the spec says so plainly so nobody designs around an enforcement that is not there. What Spectra does enforce is in §8.4 (scopes), §8.5 (assurance), §11 (lifecycle), §20 (guard rails) and §21. The site rules SHOULD state the conventions every Oxygen project shares today: changelog lines, commit with `oxy`, hermetic tests, no `git init`, which resources to claim, when to ask the human.

## 13. Echo: memory and search

### 13.1 Search

`search(query, kinds?, channel?, project?, author?, since?, until?, limit?)` runs an FTS5 query (porter stemming, prefix matches, phrases in quotes, `AND`/`OR`/`NOT`) over messages, task titles and descriptions, task results, and decisions, limited to what the caller may read, and returns hits newest first with a highlighted snippet, the author, the channel or task, the time, and the id to `read`. `since` and `until` take a time or a relative span (`7d`, `3h`). At most 100 hits; the default is 20.

### 13.2 Context windows

`read(thread: ID)` and `task(ID, with_thread: true)` give an agent the whole story of one thing. `search` finds the thing. Together they are the memory an agent is expected to use before asking a question that was answered last week, and the site rules SHOULD say so.

### 13.3 Decisions

```

Decision {

  id          ULID

  title       text

  decision    text (Markdown)     // what was decided

  rationale   text?               // why

  by          principal

  project     Project id?

  refs        [ref]

  supersedes  Decision id?

  at_ms

}

```

`decide` records one and posts a `decision` message in the project channel; `search(kinds: ["decision"])` lists them newest first, superseded ones marked. Decisions are the part of history meant to outlive the conversation that made them, and Radar has a page of them per project.

### 13.4 Semantic search

Not in version 1. FTS5 answers "what did we say about X" well enough for one person's projects, and an embedding store adds a model dependency Spectra does not otherwise have. The store keeps the door open: a `messages_embeddings` table keyed by message id can be added by a migration, filled by a background job calling a configured embedding endpoint, and merged into `search` as a second ranking. §26 records the question.

## 14. Delivery: how an agent hears about things

MCP revision 2026-07-28 is stateless: a server answers requests and may stream notifications on a `subscriptions/listen` stream, but it cannot start a turn in the client's model. Spectra therefore specifies three tiers and names what each client gets.

### 14.1 Tier 1, pull: `inbox` and `wait` (every client)

- `inbox()` returns the agent's unread items: mentions, direct messages, task events addressed to it, claim refusals, rule changes and human answers, oldest first, each with the id to act on, and marks them delivered (not read: `ack` does that, or acting on the item does).

- `wait(timeout_s: 1..=50)` is for waiting **inside a piece of work**: an agent that has just asked a question or handed a task over and cannot go on without the answer calls `wait` and gets it within 100 ms of its arrival instead of after a sleep. It blocks until something arrives for the agent or the timeout passes, then returns what `inbox` would. It subscribes to the bus before checking the inbox, so nothing is missed between the two. The response is an SSE stream with a keep-alive comment every 15 s so proxies do not cut it; the cap of 50 s keeps it under the common 60 s request timeout.

- **`wait` is not how an idle agent listens.** Every call is a model turn: the agent finishes a turn, emits the call and reads an empty result, so a loop of `wait(50)` overnight is hundreds of turns, a context window full of nothing, and a bill for it. Spectra enforces this rather than advising it: after three consecutive `wait` calls in one session that returned nothing, the next answers at once with `isError` and the text *"Nothing is waiting for you. End your turn; Spectra starts you again when there is work."*, and `wait` stays refused for ten minutes (`[guard] idle_waits`, `idle_wait_cooldown`). An idle agent is expected to end its session, which costs nothing; work given to it later sits in its inbox and queue until §14.3 or §14.4 starts it.

- With the MCP tasks extension (`io.modelcontextprotocol/tasks`), `wait` and `human` MAY return a task handle instead, and the client polls `tasks/get` from its harness, not its model. Spectra offers this when the client's capabilities declare the extension and the call asks for `as_task: true`.

### 14.2 Tier 2, push: the Claude Code channel shim

Claude Code can take pushed events from a stdio MCP server that declares the experimental `claude/channel` capability and sends `notifications/claude/channel` (content plus string meta, which become a `<channel source="spectra" …>` event in the model's context). `spectra channel --agent NAME` is that server: it connects to the running `spectra serve` over the Unix socket, signing with the agent's key from its home (§8.5), subscribes to the agent's inbox on the event stream, and pushes each item as a channel event with `meta` of `kind`, `from`, `channel`, `task` and `id`. Its `instructions` tell the model what arrives and to answer with the ordinary tools (`say`, `task_update`, …), so there is no separate reply tool to learn.

It also declares `claude/channel/permission` when started with `--relay-permissions`: Claude Code then forwards tool-approval prompts to the shim, which posts them to the owner's inbox in Radar (and to a configured relay, §16.2), and the owner's allow or deny in Radar goes back as `notifications/claude/channel/permission`. That makes Radar a place to approve an agent's actions from another room.

What this tier honestly is: a research-preview feature of one client, gated by `--channels` (allowlisted plugins) or `--dangerously-load-development-channels server:spectra`, interactive sessions only, on protocol revision 2025-11-25 (Claude Code does not register a channel that negotiates 2026-07-28, so the shim speaks the older revision on stdio while the daemon speaks the newest on HTTP). Spectra ships it because it is the difference between an agent that notices a handoff in a second and one that notices when it next polls, and documents the flags. Nothing else depends on it.

### 14.3 Tier 3, hooks: `spectra hook`

Clients with lifecycle hooks (Claude Code's `SessionStart`, `UserPromptSubmit` and `Stop`) run `spectra hook` at those moments. `spectra hook brief --agent NAME` prints, as text for the model's context, the rule-change line if any, the unread inbox, and (on `SessionStart`) the compiled rules, then marks the items delivered. `spectra hook stop --agent NAME --wait SECONDS` runs on `Stop`: it blocks **in the hook process, not the model**, for up to SECONDS (the hook's own `timeout` must allow it; 600 is the suggested value) until something arrives for the agent, then exits 2 with the inbox as text, which in Claude Code's hook contract keeps the agent going with that text instead of ending its turn; when nothing arrives it exits 0 and the session ends. An agent waiting this way spends no tokens. `spectra hook install claude-code` writes the hook entries into the project's `.claude/settings.json` (merged, never replacing other hooks).

### 14.4 Tier 4, launch: `spectra trigger`

For an agent with no session open, nothing above helps, and that is the normal overnight state. `spectra trigger --agent NAME -- CMD…` is a resident process that holds the agent's inbox stream, signed with the agent's key, and runs CMD when an inbox item or a queued task arrives for the agent while its presence is `offline`. CMD is the client's non-interactive mode: `claude -p "Call brief and do what is waiting"`, `kimi -p …`, or whatever the client offers. One command runs at a time per agent; `agent.launched` and the exit status are events; a failure backs off from one minute, doubling to thirty, and after five failures in a row the trigger stops and tells the owner. While idle it costs nothing on either side. A systemd user unit template in `packaging/` keeps a trigger per agent alive across logins. This works for every client with a non-interactive mode, which is all of them, and it is what makes an unattended machine useful without a hub.

### 14.5 What arrives

Whichever tier delivers it, an inbox item is:

```

{ id, kind: mention | dm | task | claim | rules | human | system, at_ms,

  from: { principal, name }, channel?, task?, summary: text (≤ 500 chars), action_hint: text }

```

`action_hint` names the tool and action that acts on it (`task_update(answer)`, `task_update(accept)`, `rules`), so a model needs no further lookup to respond.

### 14.6 What each client gets

Everything an agent can do in Spectra is a tool call; the tiers above differ only in how fast an agent learns that something is waiting, and in what that costs. So every MCP client works, and the difference per client is the latency of noticing, not the feature set.

| Client | Connects | Tier 1 (`wait`, in-task only) | Tier 2 (channel push) | Tier 3 (hooks) | Tier 4 (`spectra trigger`) |

|---|---|---|---|---|---|

| Claude Code | The stdio shim (`claude mcp add spectra -- spectra mcp --agent NAME`); HTTP with a token only where tokens are allowed | Yes | Yes, research preview (§14.2) | Yes (`spectra hook install claude-code`) | Yes (`claude -p`) |

| Antigravity | The stdio shim as a `command` entry in `mcp_config.json`; `serverUrl` with a token only where tokens are allowed | Yes | No | No; `spectra rules export --format agents-md` for the rules at start | Where a non-interactive mode exists |

| Kimi Code CLI | The stdio shim (`kimi mcp add spectra -- spectra mcp --agent NAME`); HTTP with `bearerTokenEnvVar` only where tokens are allowed | Yes | No | Not known; `rules export` as above | Yes (`kimi -p`) |

| Codex and any other MCP client | The stdio shim | Yes | No | Per client | Where a non-interactive mode exists |

A client without push or hooks ends its session when it has nothing to do and is started again by a trigger; it calls `brief` at the start of every session. Spectra treats every kind the same in channels, tasks, claims, rules and Radar; the `kind` exists for the rules layer and the display, nothing else.

Adding Spectra to Antigravity (`~/.gemini/config/mcp_config.json`, or `.agents/mcp_config.json` in the project) and to Kimi Code (`~/.kimi-code/mcp.json`) is the same one line, with nothing secret in the configuration, since the shim finds the agent's key in its home:

```json

{ "mcpServers": { "spectra": { "command": "spectra", "args": ["mcp", "--agent", "antigravity-oxygenhub"] } } }

```

```sh

kimi mcp add spectra -- spectra mcp --agent kimi-oxygenflow

```

## 15. Tuner: the MCP server