@canonmsg/agent-sdk 11.2.1 → 12.1.0

package/README.md

@@ -1,616 +1,341 @@
 # @canonmsg/agent-sdk
 
-Build AI agents that participate in Canon conversations. Write message handlers, not infrastructure.
+Run an AI agent in Canon conversations. The SDK's runner owns every Canon behaviour: the connection, the inbox, a queue per room, Stop, live state, the final reply, approvals and questions, files and recovery. Your code only answers turns.
 
 For Canon's shared delivery, provenance, group participation, and runtime-boundary principles, read the [Agent communication contract](https://canonmail.com/agents/communication-contract) and the [capability manifest](https://canonmail.com/agents/integration-capability-manifest).
 
-## Quick Start
+## Install
 
 ```bash
-export CANON_ENVIRONMENT_ID=canon-prod-v1   # or canon-dev-v1
-export CANON_API_KEY=...                    # issued when your agent registration is approved
+npm install @canonmsg/agent-sdk
 ```
 
-```typescript
-import { CanonAgent } from '@canonmsg/agent-sdk';
+This is the only Canon package an agent installs. It bundles the Canon client code it uses and ships its own type declarations, so it depends on no other `@canonmsg/*` package; its dependencies are `@modelcontextprotocol/sdk`, `@noble/curves` and `chess.js`. The other `@canonmsg/*` packages on npm (`core`, `endpoint`, `backend-contracts`, `agent-tools`, `rich-cards` and the old hosts) are no longer published; remove them from an agent's dependencies. The `claude` driver also needs `@anthropic-ai/claude-agent-sdk` (an optional peer, see [Claude Code](#claude-code)); the `codex` driver needs the Codex CLI.
 
-const agent = new CanonAgent({
-  apiKey: process.env.CANON_API_KEY!,
-  environmentId: process.env.CANON_ENVIRONMENT_ID!,
-  historyLimit: 30,
-});
+Node.js 22.22.3 or later is required. You need an approved agent's API key; see [Registration](#registration).
 
-agent.on('message', async ({ messages, history, replyFinal }) => {
-  const response = await callMyLLM(messages, history);
-  await replyFinal(response);
-});
+## Quick start
+
+Write a module whose default export answers one turn:
 
-await agent.start();
+```js
+// agent.mjs
+export default async function (turn) {
+  turn.stream('Thinking…'); // a live preview, never posted
+  return `You said: ${turn.input.messages.at(-1).text}`; // the turn's one reply; null stays silent
+}
 ```
 
-## Installation
+Run it:
 
 ```bash
-npm install @canonmsg/agent-sdk
+export CANON_ENVIRONMENT_ID=canon-prod-v1   # or canon-dev-v1
+export CANON_API_KEY=...                    # or --profile <name> from $CANON_HOME/agents.json
+npx canon-agent run --driver code --module ./agent.mjs
 ```
 
-The SDK uses `@canonmsg/core` and the shared `@canonmsg/endpoint` engine. Node.js 22.22.3 or later is required.
-
-The endpoint owns stable installation and operation IDs, SQLite outbox/inbox state, live transport, receipt recovery, conversation synchronization, and upload dependencies. `CanonAgent` adds handler and native-session behavior. Set `CANON_ENDPOINT_STATE_DIR` to a persistent private directory; the default is `~/.canon/endpoint`. Keep this directory when upgrading or restarting a runtime.
+SIGTERM or Ctrl-C stops taking messages, gives running turns 10 seconds, then stops them. A second signal exits at once. The `code`, [`claude`](#claude-code) and [`codex`](#codex) drivers are available.
 
-Replicated or ephemeral cloud deployments must inject an operator-owned endpoint store through `endpoint: { endpoint: sharedEndpoint }`. File delivery also needs a durable `mediaBytes` adapter or persistent `mediaDirectory`; a temporary container filesystem is not a delivery journal. All replicas for one installation share the same store namespace. A process must not replay an uncertain provider call automatically.
+## Library form
 
-Existing conversations require the rollout tool's reconciled history baseline before agent execution. The immutable recovery cutover permits later room creations and new admissions to receive their bounded history automatically. Missing baselines appear as explicit recovery errors; startup never treats all old messages as new tasks.
-
-Runtime heartbeats come from Core through the shared endpoint, using the same machinery as the integrated plugins. No separate runtime Firebase token exchange is needed. The SDK adds handler dispatch and lifecycle wiring. Concurrent `start()` calls share one startup; failed startup can be retried, and `stop()` prevents an unfinished startup from reconnecting afterward. Heartbeat failures are reported and later heartbeats retry. This does not guarantee cancellation of arbitrary application work already running in a handler.
-
-## Configuration
+```js
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { codeDriver, createRunner } from '@canonmsg/agent-sdk';
 
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `apiKey` | `string` | **required** | API key obtained after agent registration approval |
-| `environmentId` | `string` | **required** | Canon trust domain shared by API, stream, RTDB, and future cryptographic state |
-| `baseUrl` | `string` | Environment default | Override the API base URL when the selected environment has no packaged default |
-| `streamUrl` | `string` | Environment default | Override the SSE stream URL when the selected environment has no packaged default |
-| `rtdbUrl` | `string` | Environment default | Legacy connection option; runtime state uses the shared endpoint |
-| `firebaseApiKey` | `string` | Environment default | Legacy connection option; no runtime Firebase token exchange |
-| `deliveryMode` | `'auto' \| 'sse'` | `'auto'` | How the SDK receives new messages |
-| `debounceMs` | `number` | `2000` | Batching window for incoming messages per conversation |
-| `historyLimit` | `number` | `50` | Number of historical messages to fetch (max 100) |
-| `autoMarkRead` | `boolean` | `true` | Advance Canon's read cursor after successful handler completion. The current endpoint marks through server time, not the exact handled batch; history fetches are read-only. |
-| `sessions` | `SessionOptions` | `undefined` | Enable per-conversation session queues and persistent metadata |
-| `clientType` | `AgentClientType` | `'generic'` | Agent runtime label used for Canon capability detection |
-| `runtimeDescriptor` | `CanonRuntimeDescriptor` | minimal generic descriptor | Supported live actions and runtime capability metadata for Canon UI |
-| `runtimeControls` | `RuntimeControlHandlers` | `undefined` | Optional `onInterrupt` / `onStopAndDrop` / `onNewSession` handlers for Canon working-state controls |
-| `runtimeControlSurface` | `'agent' \| 'host'` | `'agent'` | Runtime publishing surface. Use `host` when this SDK agent owns live runtime controls. |
-| `runtimePrimitives` | `RuntimePrimitiveHandlers` | `undefined` | Optional typed primitive command handlers for descriptor-backed runtime commands |
-| `sessionState` | `boolean` | `false` | Publish runtime-applied state to the canonical agent-session snapshot |
-| `turnVerbosity` | `'verbose' \| 'quiet' \| 'auto'` or `{ direct?, group? }` | `'auto'` | How much of a turn's middle readers see. See [Turn verbosity](#turn-verbosity). |
-
-### Optional runtime controls
-
-Runtime descriptors describe supported live actions and status. They do not publish local project/model inventories or reopen the retired `/session-config` interface. Native work-session setup uses the owner-private workflow below.
-
-SDK agents only advertise Stop or Send Now when they register runtime-control handlers. Handlers receive the active turn's `AbortSignal`; long-running work should check `ctx.abortSignal.aborted` or pass the signal into cancellable APIs.
-
-```typescript
-const agent = new CanonAgent({
-  apiKey: process.env.CANON_API_KEY!,
-  environmentId: process.env.CANON_ENVIRONMENT_ID!,
-  sessions: { enabled: true },
-  runtimeControls: {
-    onInterrupt: ({ conversationId }) => {
-      console.log(`Canon asked to interrupt ${conversationId}`);
-    },
-    onStopAndDrop: ({ droppedMessageIds }) => {
-      console.log('Dropped queued messages:', droppedMessageIds);
-    },
-  },
-});
-
-agent.on('message', async ({ messages, replyFinal, abortSignal }) => {
-  const result = await runWork(messages, { signal: abortSignal });
-  if (abortSignal.aborted) return;
-  await replyFinal(result);
+const runner = await createRunner({
+  apiKey: process.env.CANON_API_KEY,
+  environmentId: 'canon-prod-v1',
+  home: join(homedir(), '.canon'), // a private 0700 directory
+  driver: codeDriver(async (turn) => `You said: ${turn.input.messages.at(-1).text}`),
 });
+await runner.start();
+process.on('SIGTERM', () => runner.stop().then(() => process.exit(0)));
 ```
 
-Canon does not infer support from `clientType`. Advertise only actions your runtime implements. Message handlers receive Canon-computed `ctx.provenance`; use it to enforce your runtime's owner and group policies.
-
-### Native work sessions
-
-Use `createCanonWorkSessionHost` when Canon should share actual sessions from another runtime. Implement Core's `NativeWorkSessionProvider` (`catalog`, `create`, `open`, `close`) and `AttachedNativeSessionAdapter`. The SDK owns authentication, a single account stream/heartbeat, private setup requests, per-conversation routing, approvals and questions, and durable recovery. Codex is one provider of this API.
-
-The host requires a stable `hostId`, a durable `createFileWorkSessionHostStore`, a per-room attachment store, and an exclusive native-session lock. Its `connection` identifies the Canon account and environment. `createSessionStore(binding)` and `acquireNativeSession(binding)` let other integrations reuse their local storage/locking conventions. Start the host once per account; it can serve many conversations.
-
-The owner sees only choices advertised by the local provider. Creating a session applies those choices; attaching an existing session preserves its native settings. Admission uses the existing communication verbs and must finish before the private request is accepted. Each account has one session per Canon conversation. The runtime catalog stays separate from public runtime descriptors and presence.
-
-The host persists creation intent before native work and the exact returned native ID before attachment. A replayed claim never creates another session. Unknown outcomes remain explicit; the owner can resolve an uncertain reservation after inspecting existing native sessions. Input, shared text, and approval cards wait for Canon's binding acknowledgement. Confirmed bindings restore on the same host; owner or agent membership loss detaches the bridge.
-
-Native approval/input interactions use the existing Core request manager, exact owner identity, stable IDs and deadlines, and durable results. A native client may answer first; cancellation withdraws the Canon request. Detaching closes observers while leaving native threads and workspaces intact.
-
-See the [Codex workflow](../codex-plugin/README.md) for a runnable integration and [work-session design](../../docs/design/canon-work-session-setup.md) for boundaries and recovery behavior.
-
-### Runtime primitives
+`createRunner` checks `home` before anything else. `start()` connects and starts taking input. `stop()` stops intake, returns messages no turn has taken to the inbox, and lets running turns finish within the shutdown grace. The runner reads no environment variables.
 
-The SDK provides a standard catalog of seven runtime primitives. It advertises a primitive command only when you register its handler with `runtimePrimitives` or `agent.onPrimitive(id, handler)`, or explicitly include the command in a descriptor backed by a `'*'` fallback handler. Generic agents publish no commands by default. A fallback handles otherwise unhandled primitives; registering the fallback alone does not advertise the whole catalog.
+`runner.communicate(input)` sends outside any turn, for example from a cron job. It takes the `communicate` tool's input (the exported `CommunicateInput` type), acts under the agent's identity, and needs `start()` first:
 
-| Primitive | Aliases |
-|---|---|
-| `runtime.status` | `/status` |
-| `runtime.reasoning.set` | `/think`, `/effort` |
-| `runtime.verbosity.set` | `/verbose` |
-| `runtime.usage` | `/usage` |
-| `context.compact` | `/compact` |
-| `session.new` | `/new` |
-| `session.reset` | `/reset` |
-
-`agent.describeCommands()` returns the descriptor command list the SDK advertises. `agent.publishRuntimeFacts(conversationId, facts)`, `agent.publishRuntimeActivity(conversationId, item)`, and `agent.clearRuntimeActivity(conversationId, options?)` push runtime status and margin activity into Canon's live surfaces.
-
-## Delivery
-
-The SDK receives messages through the shared endpoint's SSE connection. `deliveryMode: 'auto'` (the default) resolves to `'sse'`; any other value throws at `start()`. There is no polling mode.
-
-A single connection receives events for all conversations. It auto-reconnects with exponential backoff if the connection drops, and uses `Last-Event-ID` to replay missed events while they remain inside the replay window. If the replay window has expired, the SDK surfaces that expiry; the shared endpoint owns durable synchronization and admission-checked recovery beyond the live replay window. Adapters must not add a second history dispatch loop.
-
-The SDK publishes runtime heartbeats every 30 seconds while SSE is connected and clears its runtime freshness on disconnect. Controls remain limited to the handlers and descriptor your runtime actually supports.
-
-Handler reply helpers carry the inbound SSE event's reply authority automatically. Outbound-closed agents need that authority for non-owner/group replies; it expires 15 minutes after the source message was created. Delayed processing or fetching history does not renew it. See [Replies and polling](https://canonmail.com/agents/contracts#replies-and-polling) for the current limits.
-
-With `autoMarkRead: true`, the SDK marks the conversation read after successful handler completion. The current `mark_read` action advances to server time, so messages arriving during the handler can also be marked read before they are handled. `ctx.markAsRead()` uses the same endpoint. Keep your processing checkpoint separate from this chat read receipt; the API currently has no exact-batch read cursor.
-
-## Message Handler
-
-The `message` event handler receives a context object with:
-
-| Field | Type | Description |
-|---|---|---|
-| `messages` | `CanonMessage[]` | New messages in this batch (debounced, sorted by time) |
-| `history` | `CanonMessage[]` | Last N messages before these new ones |
-| `replyContext` | `CanonReplyContext \| null` | Resolved swipe-reply target for the latest inbound message, when available |
-| `conversationId` | `string` | The conversation these messages belong to |
-| `conversation` | `CanonConversation` | Full conversation metadata |
-| `groupContext` | `CanonGroupContext \| undefined` | Participant context based on the current conversation roster |
-| `replyFinal` | `(text: string, options?) => Promise<{ messageId: string; messageIds: string[] }>` | Send the durable final reply for a turn |
-| `replyProgress` | `(text: string, options?) => Promise<{ turnId: string; durable: boolean; messageId: string \| null; messageIds?: string[] }>` | Update the live turn progress; add `durable: true` to also persist it |
-| `deleteMessage` | `(messageId: string) => Promise<void>` | Soft-delete a message sent by this agent |
-| `markAsRead` | `() => Promise<void>` | Advance this agent's read cursor for the conversation |
-| `leave` | `() => Promise<void>` | Leave the current conversation |
-| `react` | `(messageId, emoji) => Promise<void>` | Toggle an emoji reaction |
-| `addMember` / `removeMember` | functions | Manage participants when the agent has permission |
-| `communicate` | function | Message an existing conversation, start a conversation, create a conversation with several participants, forward an exact message, share a contact, or manage participants |
-| `agent` | `AgentContext` | Trusted Canon agent identity and access context |
-| `activeSelfContextId` | `string \| null` | Active private self-context id for this turn |
-| `selfContexts` | `CanonSelfContext[] \| undefined` | Private context explaining this agent's cross-session actions |
-| `provenance` | `CanonRuntimeProvenance` | Canon-computed sender/conversation context for the latest inbound message in this batch |
-| `turnContext` | `CanonTurnContextV2` | Compact structured turn context; fields reflect the current roster, sender and participation policy |
-| `requestedTurnMode` | `string \| null` | Runtime turn mode the sender requested for this inbound turn, if any |
-| `turnVerbosity` | `'verbose' \| 'quiet'` | Resolved emission mode for this turn — see [Turn verbosity](#turn-verbosity). Fixed for the whole turn |
-| `requestApproval` | `(request) => Promise<ApprovalResult>` | Render a Canon approval card and wait for the decision. Fail-closed: returns `{ decision: 'deny' }` on any non-abort failure instead of throwing |
-| `requestRuntimeInput` | `(request) => Promise<RuntimeInputResult>` | Render a Canon input card for clarification, sudo, or secret values |
-| `requestPlanReview` | `(request) => Promise<RuntimePlanReviewResult>` | Render Canon's native plan-review card and wait for approve, revise, reject, cancellation, or timeout |
-| `requestCard` / `sendCard` | functions | Render a generic `canon.card.v1` rich card. `requestCard` blocks only on cards that carry an `actions` block; `sendCard` posts a display card |
-| `media` | `{ materialize, uploadFile, replyWithFile }` | Canon-managed access to real media bytes via `~/.canon/media-cache` plus local-file uploads back into Canon |
-| `session` | `SessionInfo \| undefined` | Per-conversation queue/session state when sessions are enabled |
-| `turn` | `TurnController \| undefined` | Live turn-state helpers for thinking/streaming/tool/waiting-input |
-| `abortSignal` | `AbortSignal` | Cooperative cancellation signal for interrupt/stop handling |
-
-Messages from the agent itself are automatically filtered out -- your handler only receives messages from other participants.
-
-`ctx.provenance` describes the latest inbound message in the debounced batch. Use it for runtime-owned policy decisions such as owner-only tools, group mention handling, or self-context-aware behavior. `ctx.turnContext` collects that provenance with message, reply, media, self-context, group, and participation facts that are relevant to the current turn. Two-person human-agent turns stay sparse; agent-agent and larger-roster turns include extra loop/participation context when it matters. Canon provides trusted provenance; it does not impose an SDK-agent sandbox.
-
-## Events
-
-`agent.on(event, handler)` accepts ten events. Each event holds a single handler; registering again replaces it.
-
-| Event | Payload | Notes |
-|---|---|---|
-| `message` | `MessageHandlerContext` | Debounced inbound batch for one conversation |
-| `messageUpdated` | `MessageUpdatedPayload` | Reaction/status changes; not a new turn |
-| `contactAdded` | `ContactAddedPayload` | A contact edge now exists |
-| `contactRemoved` | `ContactRemovedPayload` | A contact edge was removed |
-| `participationSuppressed` | `ParticipationSuppressedPayload` | Observe-only notice that policy withheld a turn |
-| `interrupt` | `RuntimeSignalContext` | Same signal as `runtimeControls.onInterrupt` |
-| `stopAndDrop` | `RuntimeSignalContext` | Same signal as `runtimeControls.onStopAndDrop` |
-| `newSession` | `RuntimeSignalContext` | Same signal as `runtimeControls.onNewSession` |
-| `callStarted` | `VoiceSessionEventPayload` | **Register before `start()`** |
-| `callEnded` | `VoiceSessionEventPayload` | **Register before `start()`** |
-
-The voice event family is negotiated with the stream at connect time from handler presence. `callStarted` / `callEnded` handlers registered after `start()` never fire — the SDK only logs a warning — so register them before starting the agent.
-
-## Reaction Updates
-
-Agents can use `ctx.react(messageId, emoji)` to toggle any valid emoji reaction on a message. Reactions are also observable through the stream:
-
-```ts
-agent.on('messageUpdated', async ({ conversationId, messageId, changes }) => {
-  if (changes.reactions) {
-    console.log('Reaction state changed', conversationId, messageId, changes.reactions);
-  }
-});
-```
-
-Reaction update events are interaction state, not new chat turns. They do not call the `message` handler or wake another agent turn.
-
-### Human-in-the-loop cards
-
-Use `ctx.requestRuntimeInput(...)` when the runtime needs clarification, a sudo value, or a secret value from the user. Use `ctx.requestPlanReview(...)` when a planning runtime needs Canon's native approve/revise/reject card, and `ctx.requestApproval(...)` when the runtime needs an allow/deny decision before taking an action. Canon creates the visible card, routes the user's response, and returns the result to the handler; your runtime remains responsible for enforcing that result.
-
-`requestApproval` is fail-closed and never throws: it returns `{ decision: 'deny' }` when no approval manager can be built (no resolved agent identity or owner) and on any non-abort error. A `deny` therefore does not prove a human said no — check your own preconditions before treating it as a decision.
-
-Use `ctx.requestCard(...)` for generic rich reports and action forms. A `canon.card.v1` action may include small structured fields; Canon validates the selected action and declared field values, but your runtime still decides what to do with them:
-
-```ts
-const review = await ctx.requestCard({
-  card: {
-    schema: 'canon.card.v1',
-    title: 'Review draft',
-    fallbackText: 'Review draft: approve or request changes.',
-    blocks: [{
-      kind: 'actions',
-      actions: [
-        { id: 'approve', label: 'Approve', tone: 'positive' },
-        {
-          id: 'revise',
-          label: 'Request changes',
-          fields: [{ id: 'note', label: 'What should change?', type: 'textarea', required: true }],
-        },
-      ],
-    }],
-  },
+```js
+await runner.communicate({
+  action: 'message_existing', conversationId, text: 'The nightly report is ready.',
+  messageId: 'nightly-2026-10-14', // optional stable id
 });
 ```
 
-`RuntimeCardResult.status` is one of `'submitted' | 'cancelled' | 'timeout' | 'displayed'`; only `'submitted'` carries `actionId` and `values`. A card with no `actions` block has nothing to wait for, so `requestCard` forwards it to `sendCard` and resolves immediately with `{ status: 'displayed', cardId }`. Requests default to a five-minute timeout; pass `timeoutMs` or `expiresAt` to change it.
-
-The SDK does not validate card documents — it forwards `request.card` to Canon as-is, and a malformed card surfaces as a backend 400. Install [`@canonmsg/rich-cards`](https://www.npmjs.com/package/@canonmsg/rich-cards) if you want strict authoring validation (`validateCard`, the `card()` builder, and the `canon-card` CLI); it is a separate package and not a dependency of this one.
-
-### Turn-aware example
+## Claude Code
 
-```typescript
-agent.on('message', async ({ messages, history, replyFinal, replyProgress, turn, session }) => {
-  await turn?.setThinking('Reviewing the request...');
+The `claude` driver runs each turn in Claude Code through the Claude Agent SDK, which you install next to this package:
 
-  const plan = await draftPlan(messages, history, session?.messages ?? []);
-  await replyProgress(`Plan: ${plan.summary}`);
-
-  await turn?.setTool('Running checks...');
-  const result = await runWork(plan);
-
-  if (result.needsInput) {
-    await turn?.setWaitingInput('I need one more detail before I continue.');
-    return;
-  }
-
-  await replyFinal(result.text);
-});
+```bash
+npm install @canonmsg/agent-sdk @anthropic-ai/claude-agent-sdk
+npx canon-agent run --driver claude --cwd ~/work/my-repo [--model <id>] [--permission-mode default|acceptEdits|bypassPermissions]
 ```
 
-### Session queues
+- Each conversation has its own Claude Code session, resumed turn after turn. New session starts a fresh one.
+- Claude Code signs in with the machine's Claude subscription (Pro or Max), or uses `ANTHROPIC_API_KEY` when it is set. `CANON_*` variables never reach it.
+- It works in `--cwd` (default: the current directory) and may send files from there and from the OS temp directory.
+- Canon's tools (`no_reply`, `communicate`, `react`, `send_file`) are its `canon` MCP server for the turn.
+- With `--permission-mode default` (the default), each tool call Claude Code would ask about becomes a Canon approval for the owner, who can approve that exact call for the session: a later call of the same tool with the same input then runs without asking (a built-in tool's `description`, the model's wording of the call, does not count), and any other input asks again (approving `ls` never approves `rm -rf`). `acceptEdits` and `bypassPermissions` allow more without asking. In any mode, a turn that holds a message from anyone but the owner (a group member, another agent) may use only Canon's tools, AskUserQuestion and ToolSearch: nothing runs on the owner's machine for them. A message from a [trusted teammate agent](#team-rooms) counts as the owner's.
+- `--instructions <file>` appends the owner's standing instructions (a role, say) to Claude Code's system prompt; see [Team rooms](#team-rooms).
+- AskUserQuestion becomes Canon questions: a question with options is a choice, one without is free text.
+- Stop interrupts Claude Code; a process that has not stopped 5 seconds later is closed.
+- Not available yet: switching models, slash commands, plan review and steering.
 
-When `sessions.enabled` is on, the SDK serializes work per conversation and exposes:
+In library form: `claudeDriver({ cwd, model?, permissionMode?, claudePath?, interruptGraceMs?, instructions? })`.
 
-- `session.id`: the conversation/session id
-- `session.messages`: accumulated session context within the configured limit
-- `session.metadata`: mutable per-session state
-- `session.queueDepth`: number of pending inbound batches behind the current one
+## Codex
 
-This is the easiest way to build agents that need per-conversation memory or queue awareness.
+The `codex` driver runs each turn in the app server of the Codex CLI, which you install and sign in to separately:
 
-## Agent directory, contacts, blocking, and conversations
-
-Directory lookup is separate from reachability. It returns only agents whose
-owners made them discoverable, plus the responsible owner and public contact
-policies; it does not grant permission to message or add an agent to a group.
-Agents whose outbound policy is closed cannot search the directory.
-
-```typescript
-const page = await agent.directory.search({ query: 'research', limit: 10 });
-for (const entry of page.agents) {
-  console.log(entry.principalId, entry.owner, entry.inboundPolicy);
-}
-```
-
-The other instance sub-APIs wrap Canon's authenticated REST surface:
-
-```typescript
-await agent.contacts.list();                       // CanonContact[]
-await agent.contacts.get(contactId);               // CanonContact | null
-await agent.contacts.remove(contactId);
-await agent.contacts.request(targetUserId, 'why I am reaching out');
-
-await agent.users.block(userId);
-await agent.users.unblock(userId);
-
-await agent.conversations.list();                  // all conversations
-await agent.conversations.list({ targetUserId });  // only those the target is a member of
+```bash
+npm install -g @openai/codex && codex login
+npx canon-agent run --driver codex --cwd ~/work/my-repo [--model <id>] [--sandbox workspace-write|read-only|danger-full-access] [--approval-policy on-request|untrusted|never]
 ```
 
-## Media
+- Each conversation has its own Codex thread, resumed turn after turn by a short-lived `codex app-server` process. New session starts a fresh thread.
+- Codex uses its own login (`codex login`, usually ChatGPT). With `OPENAI_API_KEY` set and no other model provider configured, it uses that key. `CANON_*` variables never reach it.
+- It works in `--cwd` (default: the current directory) and may send files from there and from the OS temp directory. Images sent to the agent reach the model as images; every attachment's path is in the prompt.
+- Canon's tools (`no_reply`, `communicate`, `react`, `send_file`, `ask_question`) are its `canon` MCP server for the turn, used without approval.
+- In the owner's turns Codex runs in the `--sandbox` (default `workspace-write`) and asks before acting as `--approval-policy` says (default `on-request`). Each request is a Canon approval for the owner, who can approve the exact command (in that directory, with that network access), set of files or MCP tool for the session. A turn that holds a message from anyone but the owner (a group member, another agent) runs read-only, approves nothing and has only Canon's tools and questions: no shell, file or image reads, apps, plugins, browsers, web search or the owner's MCP servers. If Codex starts any other tool anyway, the turn stops and its thread is dropped. A message from a [trusted teammate agent](#team-rooms) counts as the owner's.
+- `--instructions <file>` appends the owner's standing instructions (a role, say) to Codex's developer instructions; see [Team rooms](#team-rooms).
+- Codex asks its questions through Canon's `ask_question` tool: a question with options is a choice, one without is free text. No Codex feature flag is turned on for it.
+- Stop interrupts Codex; a process that has not stopped 5 seconds later is closed.
+- Not available yet: switching models, slash commands, plan mode, steering and attaching to a running Codex session.
 
-Normalized Canon messages always expose `attachments[]` as the single canonical media contract. Legacy flat fields (`imageUrl`, `audioUrl`, `audioDurationMs`) are no longer part of the message shape — agents must consume `attachments` directly.
+In library form: `codexDriver({ cwd, model?, sandbox?, approvalPolicy?, codexPath?, interruptGraceMs?, instructions? })`.
 
-Use the handler `media` helpers when you need the actual file bytes:
-
-```typescript
-agent.on('message', async ({ messages, media }) => {
-  const files = await media.materialize(messages[messages.length - 1]);
-  console.log(files[0]?.path); // ~/.canon/media-cache/<agent>/<conversation>/<message>/...
-});
-```
+## Turns
 
-- `media.materialize(message?, options?)` streams attachments on demand into `~/.canon/media-cache`. Automatic materialization is capped at 10 MiB per attachment before and during the download. A runtime that deliberately needs a larger input can pass `maxBytes`, up to 100 MiB. Failed or oversized attachments are reported through optional `onError`; valid siblings are still returned. Cancellation still aborts the complete operation. Cache files are published through an atomic rename. The cache is persistent and currently has no aggregate quota or automatic eviction, so hosted-agent operators should monitor or periodically clear it.
-- `media.uploadFile(path, options?)` streams a local file (up to 100 MiB) through Canon's private resumable-capable upload lane and returns `{ uploadId, url, attachment }`. The attachment carries the same server-issued `uploadId`, allowing a subsequent durable message/card write to retain the temporary upload. File bytes are never base64-buffered in the SDK. The current helper uses one streamed PUT; a failed application-level attempt starts a new Canon session rather than resuming an acknowledged byte range in the old session.
-- `media.replyWithFile(path, text?, options?)` uploads a local file and sends it as the durable final Canon reply for the current turn.
+A handler receives a `CodeTurn`:
 
-GIFs are regular image attachments. Agents can receive or send them through `attachments[]` with `kind: 'image'` and `mimeType: 'image/gif'`; Canon does not use a separate GIF content type.
-
-The public helpers are also available from the Node-only subpath export:
-
-```typescript
-import { materializeMessageMedia, uploadMediaFile } from '@canonmsg/agent-sdk/media';
+| Field | Meaning |
+|---|---|
+| `input` | Read-only facts: `conversationId`, `room` (`'direct'` with two members, else `'group'`), `sender` (`id`, `name`, `type`, `isOwner`, `trustedAgent`), `messages` (this turn's inputs, oldest first; `trustedAgent: true` marks a confirmed [trusted teammate agent](#team-rooms)) and `history` (up to 20 earlier messages since the agent was admitted) |
+| `prompt` | The same messages rendered as text for a model, history first |
+| `files` | Absolute paths of this turn's inbound attachments, already downloaded |
+| `signal` | Aborts on Stop, Stop & clear, New session, `no_reply`, membership loss, the no-progress deadline and shutdown |
+| `stream(text)` | The full visible answer so far, not a delta. A preview only |
+| `activity(event)` | A status row `{ id, kind: 'tool' \| 'status', title, state: 'running' \| 'done' \| 'failed' }`, replaced by `id` |
+| `ask(request)` | Approvals and questions; see below |
+| `state` | `get`, `set` and `delete` of JSON values for this conversation, at most 64 KiB. Kept across restarts; New session clears it |
+| `tools` | `call(name, args)` for `no_reply`, `communicate`, `react`, `send_file` and `ask_question`, bound to this turn |
+
+What the handler returns decides the turn's output:
+
+- A string is the turn's one final reply. Long replies are split into ordered parts for you; one that would need more than 100 parts, files included, is cut short with a note saying so.
+- `{ reply, files }` sends the files ahead of the reply's text.
+- `null` is deliberate silence: nothing is posted and files are withheld.
+- Throwing, or returning anything else (including `undefined`), posts one short failure notice. The turn is never re-run.
+
+Several messages that arrive while a turn runs are answered together by the next turn, up to 20 at a time.
+
+### Asking a person
+
+```js
+const answer = await turn.ask({ kind: 'approve', id: 'deploy', title: 'Deploy to production?', risk: 'destructive' });
+if (answer.status !== 'answered' || !answer.allow) return 'Not deploying.';
 ```
 
-## Calls
+- `approve` answers with `allow` and `scope`. `choose` (`options: [{ id, label }]`, optional `multiple`) answers with `choices`, the chosen option ids. `text` (optional `secret`) answers with `text`.
+- The person who sent the turn's newest message answers; when that sender is an agent, the owner answers. A secret goes to the owner only. With `allowSession: true` the owner may approve for the session: the owner's later asks with exactly the same title (or the same `scopeKey`, when you set one: make it name the exact call, such as a tool and its whole input, since one session answer covers everything that shares it) and `allowSession` then get `{ allow: true, scope: 'session' }` without a card, until New session or a restart.
+- A request expires after 1 hour with `{ status: 'expired' }`; an expired approval is a denial. A request that is cancelled or refused gives `{ status: 'cancelled' }`.
+- While an ask waits, the turn keeps its room; new messages queue and are never read as answers. Stop rejects a pending `ask` with an `AbortError`.
+- Asking again with the same `id` in one turn returns the same answer.
 
-Agents can start, join, decline, and end Canon audio/video calls. The SDK returns the LiveKit room token; it does not ship an RTC transport — bring your own (for example `@livekit/rtc-node`, lazily imported).
+A runtime that calls tools itself asks through the `ask_question` tool instead: `{ question, options?, multiple? }` (up to 10 option labels) raises the same `choose` or `text` ask, with the same responder, expiry and waiting, and returns the chosen labels (joined by `, `) or the typed text, or a sentence starting "Nobody answered" when it expired or was withdrawn. It never asks for a secret. The same call made again while the first still waits joins it. A driver whose runtime has a question tool of its own declares `capabilities.nativeQuestions` and is not offered `ask_question`; the `claude` driver does, for AskUserQuestion.
 
-```typescript
-agent.on('callStarted', async ({ conversationId, session, targetsMe }) => {
-  if (targetsMe === false) return; // group/human-mode calls arrive here too; absent means targeted
-  const { url, token, roomName } = await agent.joinCall(conversationId, session.id);
-  await connectMyRtcClient(url, token, roomName);
-});
+### Tools
 
-await agent.start();
-```
+`turn.tools.call(name, args)` resolves to `{ content, isError? }`:
 
-| Method | Description |
-|---|---|
-| `startCall({ conversationId, media?, targetAgentId? })` | Start or rejoin a call; `media` is `'audio'` (server default) or `'video'` |
-| `joinCall(conversationId, sessionId)` | Join an active session and get the room token |
-| `declineCall(conversationId, sessionId)` | Stop this agent's ring only |
-| `endCall(conversationId, sessionId)` | End the session for everyone |
-| `getCallState(conversationId, sessionId)` | Current `CanonVoiceSession` state |
-
-Register `callStarted` / `callEnded` before `start()` — see [Events](#events).
-
-## Agent Registration
-
-For persistent local onboarding, import `ensureAgentProfile` from this package. It reuses an environment-bound profile in `~/.canon/agents.json`, resumes the exact saved approval request, persists credentials before ACK, and retries an interrupted ACK on the next call. `waitMs: 0` (the default) checks once; a positive value waits up to that deadline and returns `pending` if approval is still outstanding. See the [complete runnable quickstart](https://canonmail.com/agents/build#run-a-complete-agent).
+| Tool | Arguments | Effect |
+|---|---|---|
+| `no_reply` | `{ reason? }` | Ends the turn silently. `reason` is never sent. Anything returned afterwards is withheld |
+| `communicate` | a `CommunicateInput` | Messages another conversation, starts or creates one, manages participants, leaves, forwards a message, shares a contact, lists conversations or finds agents |
+| `react` | `{ emoji, messageId? }` | Toggles a reaction in this conversation, by default on the newest input |
+| `send_file` | `{ path }` | Attaches a file, by absolute path, to the final reply |
+| `ask_question` | `{ question, options?, multiple? }` | Asks the person whose message the turn answers and returns the answer; see Asking a person |
 
-Adapters with provider-native configuration can use the exported `resumeRegistration` and `RegistrationStore` contract. Store callbacks must await durable persistence; credential reads must match the pending environment. Serialize callers sharing a store. Both helpers distinguish `credential-expired` and `credential-delivered` from a pending approval.
+The same tools are served over MCP Streamable HTTP at `turn.tools.url` for runtimes that call tools themselves. Once a turn has ended, its tools refuse calls.
 
-For an intentional retry after rejection or a terminal credential outcome, `clearPendingRegistration(profileName)` removes the local pending record. Then call `ensureAgentProfile` again; use `requestedAgentId` and `reconnect: true` when reconnecting an existing identity. A transport failure should resume its saved request.
+### Files
 
-The original static helpers remain available for clients that manage their own lifecycle (no API key needed). `register` also accepts `localRegistrationId`, `requestedAgentId`, and `clientType`; `checkStatus` exposes both `apiKeyDelivered` and `apiKeyExpired`:
+Outbound files, from `send_file` or the returned `files`, must resolve inside the driver's roots and be 1 byte to 100 MiB. The CLI allows the module's directory and the OS temp directory. In library form the default is the OS temp directory; set others with `codeDriver(handler, { outboundFiles: { roots: [...] } })`. A refused file is named in one line appended to the reply.
 
-```typescript
-import { CanonAgent } from '@canonmsg/agent-sdk';
+Inbound attachments are downloaded before the turn starts, up to 10 MiB each, and removed when it ends. One that fails is named in the prompt, and the turn still runs.
 
-const canonConnection = {
-  environmentId: process.env.CANON_ENVIRONMENT_ID!,
-  baseUrl: process.env.CANON_BASE_URL,
-  streamUrl: process.env.CANON_STREAM_URL,
-  rtdbUrl: process.env.CANON_RTDB_URL,
-  firebaseApiKey: process.env.CANON_FIREBASE_API_KEY,
-};
+## What the runner owns
 
-// 1. Submit registration request
-const { requestId, pollToken } = await CanonAgent.register({
-  ...canonConnection,
-  name: 'My Agent',
-  description: 'A helpful assistant',
-  ownerPhone: '+1234567890',
-  developerInfo: 'Acme Corp — hello@acme.com',
-});
+- One connection and one event stream per process. Input comes only through the durable inbox.
+- One turn at a time per room, in order, and up to 8 rooms at once. There is no debounce.
+- Stop, Stop & clear and New session from the Canon app. A stopped turn's reply and files are withheld even if the handler still returns.
+- Live state: thinking, typing, previews (at most 4 per second) and activity. Turns are verbose in two-person rooms and show status only in larger rooms.
+- One final per turn, split into parts of at most 3,800 bytes and journaled before the first send, so a restart delivers it once under the same ids.
+- One notice when a handler throws or a turn makes no progress for 30 minutes, and one when a restart interrupted a reply.
+- Read receipts, inbound downloads, the runtime descriptor and heartbeats.
+- Group rules: Canon decides when the agent is woken, and the runner never re-evaluates it.
 
-console.log('Registration submitted:', requestId);
-await saveRegistrationPickup({ requestId, pollToken });
+## Configuration
 
-// 2. Poll for approval
-const status = await CanonAgent.checkStatus(requestId, { ...canonConnection, pollToken });
-console.log('Status:', status.status); // 'pending' | 'approved' | 'rejected'
+`createRunner(options)`:
 
-if (status.status === 'approved' && status.apiKey) {
-  console.log('Agent ID:', status.agentId);
-  await saveAgentCredentials({ agentId: status.agentId, apiKey: status.apiKey });
-  await CanonAgent.ackStatus(requestId, { ...canonConnection, pollToken });
-}
+| Option | Default | Meaning |
+|---|---|---|
+| `apiKey` | required | The agent's API key |
+| `environmentId` | required | `canon-prod-v1` or `canon-dev-v1`. The runner refuses to start when Canon reports another environment |
+| `home` | required | The Canon home (see below) |
+| `driver` | required | `codeDriver(handler, capabilities?)`, `claudeDriver(options)` or `codexDriver(options)` |
+| `abortGraceMs` | 10 s | How long an aborted turn may take to settle before its session is reset |
+| `noProgressMs` | 30 min | A turn with no text or activity for this long fails. The clock waits while an `ask` is pending |
+| `askExpiryMs` | 1 h | How long an `ask` waits for its answer |
+| `shutdownGraceMs` | 10 s | How long running turns may finish after `stop()` |
+| `log` | stderr | Receives operational lines, never prompt or reply text |
+| `mls` | none | The agent's MLS device for encrypted rooms (Dev only); see [Encrypted rooms](#encrypted-rooms-dev) |
+| `relay`, `installationId` | off | Canon's class-C relay (Dev only); see [The class-C relay](#the-class-c-relay-dev-canon-operated) |
+| `trustedAgents` | none | Agent ids whose messages count as the owner's for tool use while Canon confirms each is an active agent of the same owner; see [Team rooms](#team-rooms) |
+| `agentTurnCap` | 6 | Encrypted rooms: how many agent @mentions in a row wake the agent in a room before a person writes there again |
+| `mentionAliases` | none | Encrypted rooms: other names that @mention the agent, such as its role |
+| `sessionApprovalForDestructive` | off | Encrypted rooms: whether the owner may allow an action the runtime marks destructive for the rest of the session (CLI `--allow-session-for-destructive`) |
+
+`baseUrl`, `streamUrl`, `endpoint` and `fetch` are test seams; production never sets them. `codeDriver`'s second argument overrides its capabilities, such as `outboundFiles` and `maxConcurrentTurns` (default 8).
+
+The CLI is `canon-agent run --driver code --module <path> [--profile <name>] [--environment <id>]`, or `--driver claude` with the [Claude Code](#claude-code) flags, or `--driver codex` with the [Codex](#codex) flags, plus the [Team rooms](#team-rooms) flags:
+
+- The environment comes from `--environment`, else `CANON_ENVIRONMENT_ID`, and is required.
+- The key comes from `CANON_API_KEY`, else the `--profile` entry in `$CANON_HOME/agents.json`. A profile from another environment is refused.
+- The home is `CANON_HOME`, else `~/.canon`.
+
+**The home.** It must be an absolute path with no symlinks, a directory owned by the user with no group or other access (0700), and every parent up to `/` must be owned by the user or root and not writable by others. A missing home is created with mode 0700. Otherwise the runner refuses to start and names the path. One instance of an agent runs per home; a second one fails to start. Keep the home across restarts: it holds the endpoint store (`endpoint/`), the reply journal and driver state.
+
+## Encrypted rooms (Dev)
+
+Encrypted (MLS) rooms are a Dev preview, for agents whose communication policies are all open. The runner holds the agent's MLS device; drivers need nothing for it. Give the runner the operator's MLS configuration: a private JSON file with the custody helper and the Dev issuer public keys, never private keys or credentials. `issuerKeys` is a list, and during an issuer rotation it must hold both key versions (Dev's version 1 issues until 2026-11-07, version 2 after), so credentials from either verify. Its format and custody provisioning are in `docs/design/mls-dev-agent-host.md` in the Canon repository:
+
+```sh
+canon-agent mls --action status --mls-dev-config /abs/mls-dev.json --profile dev-agent
+canon-agent mls --action enroll --mls-dev-config /abs/mls-dev.json --profile dev-agent
+canon-agent mls --action publish --room <conversation id> --mls-dev-config /abs/mls-dev.json --profile dev-agent
+canon-agent run --driver claude --mls-dev-config /abs/mls-dev.json --profile dev-agent
 ```
 
-The approved response only includes the API key until you acknowledge delivery. Persist it on the first approved poll, then call `ackStatus()` so Canon clears the plaintext key from the request.
-Replace `saveRegistrationPickup` and `saveAgentCredentials` with your own encrypted/local secret-store writes; do not print these values in logs.
+`canon-agent mls` runs one setup step (`status`, `provision` for portable custody, once, `enroll`, `renew`, `publish` a KeyPackage for a room before someone adds the agent, `refresh` a room) on the same home as `run`, so stop the agent first. It prints public device state and never starts a model. In library form, pass `mls: await loadMlsDevConfiguration(path, { environmentId })` to `createRunner`.
 
-Registration and startup verify that the API and stream advertise the selected
-environment before sending credentials. Production is the packaged default;
-development can be selected explicitly with `canon-dev-v1`. Persist the
-environment ID and complete endpoint snapshot beside the API key so a profile
-cannot mix Canon trust domains.
+In an encrypted room:
 
-## Error Handling
+- Turns take a person's messages, read from the device's verified history under the room's current audience, and another agent's only when it mentions this agent, a few times in a row at most (see [Team rooms](#team-rooms)). Any other agent's encrypted message is seen but starts no turn, and a message sent to an older audience is settled with no turn.
+- A change of membership stops the running turn and withholds its reply. The next turn runs in a fresh native session, and a driver without session memory sees only the history of the current audience. A member adding or removing a device (and keeping one) is not a change of membership: the turn and its session go on.
+- Canon receives encrypted text and a content-free turn state, nothing else. The turn state says only when the agent is busy (`thinking`), waiting on a card (`waiting_input`), stopped (`interrupted`) or done (`idle`), with an opaque turn id and its times, so the owner's phone shows the agent working and offers Stop; Canon learns when the agent works, never what it does. There is no typing, live preview, activity, queue, read receipt or silence report. A reply longer than 32 KiB is cut short with a note, because encrypted text is not split into parts.
+- The tools are `no_reply` and a `communicate` that lists conversations or agents and sends text to the same room only, plus `ask_question` in a room created for approvals and questions (`canon.mls.dev-text.v2`, and `v3`, which Canon creates). `react` and `send_file` fail closed with a tool error, and returned files are named in the reply as not sent.
+- In a room created for them, approvals and questions are encrypted cards that only the room's members can read, put to the person whose message the turn answers (the owner for a secret, and when an agent's message started the turn). The answer counts only from that person's verified device, and an ask that is not answered within `askExpiryMs` expires (an approval is then a denial), whatever Canon says. The owner may allow an approval for the rest of the session, which ends with New session, any change of membership and a restart; an action the runtime marks destructive offers no such rule unless the runner runs with `--allow-session-for-destructive` (`sessionApprovalForDestructive`). If the owner adds a device while a card waits, the card is asked again so the new device can answer it. Cards still pending when the runner stops are withdrawn when it restarts. In a room created as `canon.mls.dev-text.v1`, approvals and questions fail closed (a `cancelled` ask, and `ask_question` is not offered).
+- A reply is journaled before it is encrypted. A retry or a restart sends the same ciphertext, and only while the room's audience is unchanged.
+- The ids Canon sees for what the runner sends there (each message's id, and a card's request id) are keyed with a secret the runner creates once in `$CANON_HOME/runner/<environment>/<agent>/mls-ids/` (0600; it belongs with the rest of the home). They reveal nothing about the text or what was asked, and every message's id has the same shape, whether it is a reply, a notice or a `communicate` send.
 
-The SDK exports `CanonApiError` for typed error handling:
+Without `--mls-dev-config` (or `mls`), the runner refuses each encrypted room, logs it once, and runs nothing for it.
 
-```typescript
-import { CanonAgent, CanonApiError } from '@canonmsg/agent-sdk';
-
-agent.on('message', async ({ messages, replyFinal }) => {
-  try {
-    await replyFinal('Hello!');
-  } catch (err) {
-    if (err instanceof CanonApiError) {
-      console.error(`API error ${err.status}: ${err.message}`);
-    }
-  }
-});
-```
+### The class-C relay (Dev, Canon-operated)
 
-## Graceful Shutdown
+An assistant without an install of its own (ChatGPT, Claude.ai and the like) reaches Canon through the remote MCP connector; its provider runs it, not Canon. For such an agent's encrypted rooms Canon operates a **relay** that only relays messages: one process per agent, running this package's runner with the `connector` driver, which holds an MLS device for the agent, decrypts each turn for the assistant (handed over through the connector's pickup tools) and encrypts its reply. Those rooms are therefore **not end-to-end encrypted** to that agent. Agent developers do not run it; Canon's operator does:
 
-```typescript
-process.on('SIGINT', async () => {
-  await agent.stop();
-  process.exit(0);
-});
+```sh
+canon-agent run --driver connector --relay-config /abs/relay.json --mls-dev-config /abs/mls-dev.json
+canon-agent mls --action provision --mls-dev-config /abs/mls-dev.json --relay-config /abs/relay.json
 ```
 
-## Live turn state
-
-While a handler runs, the SDK automatically publishes Canon turn state and clears it when the turn completes. Use the `turn` helpers when you want richer live UX:
-
-- `setThinking(text?)`
-- `setStreaming(text)`
-- `setTool(text)`
-- `setWaitingInput(text?)`
-- `noReply(reason?)`
-
-`noReply()` is Canon's `no_reply` verb on the SDK side: end this turn without posting anything. The live bubble is blanked and removed instead of being preserved as a durable message, so nothing is rendered and no other member or agent is triggered — the agent-turn trigger is message-driven. Use it in groups when the handler decides it has nothing to add. `reason` is private: the text never leaves the process. Only its presence is reported — the SDK puts a fixed sentinel on the wire so the durable silence record can set `hasReason` — and the text itself is never sent and never rendered.
-
-It governs teardown only. Calling `replyFinal()` as well is two explicit decisions by the same author, so the text still lands — unlike the model-driven runtimes, where a `no_reply` tool call suppresses the reply outright. A handler that throws keeps the ordinary teardown, because there the streamed content is the only record of what the turn managed to say.
+The relay configuration (a private JSON file) names the agent, where the channel to Canon's Functions listens, and the path of the channel secret. No API key is involved: when the owner enables the relay, Canon delivers the relay's own credential over that channel (it works only for the relay's encrypted-room work, and stops when the relay or its connection is revoked), and the relay keeps it in `$CANON_HOME/relay` and starts under the relay installation it names (`canon-relay:…`). The relay serves only encrypted rooms; plaintext ones stay with the connector. In library form: `startRelayChannel({ agentId, secret, onCredential })`, then `createRunner({ apiKey: credential, driver: connectorDriver(), relay: true, installationId, mls })` and `channel.serve({ runner, inbox: driver.inbox }, grantId)`. The `connector` driver declares `remote`: a runtime off the runner's host gets no local files, and the runner takes it into encrypted rooms only in relay mode.
 
-`setWaitingInput()` keeps the turn open in `waiting_input` and optionally sends a control message to the conversation so Canon clients can render “reply to continue” correctly.
+## Team rooms
 
-`replyProgress()` is ephemeral by default: it updates the live RTDB turn preview without adding a permanent Firestore message. In that mode it returns `{ turnId, durable: false, messageId: null }`; pass `{ durable: true }` when you intentionally want progress chatter to remain in history and receive a real Firestore message ID back.
+An owner's agents can work together in one room, for example an engineering agent on the `claude` driver and a QA and publishing agent on `codex`:
 
-`replyFinal()` supplies `turnSemantics: 'turn_complete'` by default, making the final eligible to trigger another agent under its participation policy and loop limits. `replyBehavior: 'suppress_auto_reply'` suppresses that trigger without hiding ordinary final speech. Lower-level plain sends without turn metadata are human-visible speech but do not automatically trigger other agents; explicit progress stays outside ordinary conversation-preview/unread/notification promotion. Read receipts and message visibility are separate from whether another runtime accepted or completed work. See [Agent speech and handoffs](https://canonmail.com/agents/contracts#agent-speech-and-handoffs).
-
-## Turn verbosity
-
-By default an agent is **quiet with more than two participants and verbose with two**, based on the refreshed roster. A quiet turn shows the thinking indicator and the answer, and nothing in between.
-
-```ts
-const agent = new CanonAgent({
-  apiKey: process.env.CANON_API_KEY!,
-  environmentId: 'canon-prod-v1',
-  turnVerbosity: 'verbose',              // scalar: applies everywhere
-  // turnVerbosity: { group: 'verbose' }, // object: override one roster policy scope
-});
+```sh
+canon-agent run --driver claude --profile engineer --cwd ~/work/repo --mls-dev-config /abs/mls-dev.json \
+  --instructions ~/team/engineer.md --trust-agent <qa agent id> --mention-alias engineer
+canon-agent run --driver codex --profile qa --cwd ~/work/repo --mls-dev-config /abs/mls-dev.json \
+  --instructions ~/team/qa.md --trust-agent <engineer agent id> --mention-alias qa
 ```
 
-| Value | Effect |
-|---|---|
-| `'auto'` (default, same as omitting the option) | Verbose with two participants, quiet with more than two |
-| `'verbose'` | Live turn state and the margin activity trail, everywhere |
-| `'quiet'` | Thinking indicator and the final message only, everywhere |
-| `{ direct?, group? }` | Compatibility keys for the two-person/larger-roster scopes; the unnamed scope keeps its default |
+- **Waking each other.** In a plaintext room, Canon decides when an agent's message wakes another agent (its group rules). Canon cannot read an encrypted room, so there the runner decides: another agent's message wakes this one only when it mentions it, either in the encrypted mentions of a v3 room's message or with an @ in its text by display name, agent id or a `--mention-alias` (`mentionAliases`), in any case. To stop two agents from waking each other forever, a room wakes the agent this way at most `--agent-turn-cap` (`agentTurnCap`, default 6) times in a row; past that, agents' mentions start no turn (the runner logs it once) until a person writes in the room.
+- **Trusted teammates.** A turn holding anyone else's message gets no tools on the owner's machine (see [Claude Code](#claude-code) and [Codex](#codex)). `--trust-agent <id>` (`trustedAgents`) lists agents whose messages count as the owner's for that, in plaintext and encrypted rooms alike, but only where nobody else could have prompted them: in a room whose members are only the agent, its owner and listed agents, all of which Canon confirms at the start of each turn are active agents of the same owner; in an encrypted room with no relay device in the group; and in a plaintext room only for a teammate's final reply that its own runner marked as answering the owner or confirmed teammates alone (the runner marks its own replies that way, so list only agents that run on this runner). Anything else, including a transferred, deactivated or unlisted agent and a turn that also holds anyone else's message, is guarded as before. A trusted message carries `trustedAgent: true` and its prompt line says it comes from a trusted teammate agent. It is still not the owner: its approvals go to the owner, and the owner alone should give release go-aheads.
+- **Standing instructions.** `--instructions <file>` (the drivers' `instructions` option) appends the owner's instructions for this agent, such as its role and its handoff rules, to Claude Code's system prompt or Codex's developer instructions. The file is read once at start; it must be UTF-8 text of at most 32 KiB at its real path (no symbolic links), owned by you and not writable by others, in a directory only you (or root) can change, and it is never sent to Canon. The `code` driver's module writes its own prompts. An example brief for an engineer and a QA agent is [in the Canon repository](https://github.com/HeyBobChan/canon/blob/main/docs/agents/examples/team-room-roles.md).
+- In an encrypted room created for cards (`canon.mls.dev-text.v2` or `v3`, which is what Canon creates), approvals and questions go to the owner (or the person whose message the turn answers) as encrypted cards. In a v1 encrypted room they cannot be asked (they fail closed), so what an agent does there without asking is what its `--permission-mode` or `--sandbox` and `--approval-policy` allow.
 
-Adding or removing participants can change the default on the next turn. The SDK
-holds verbosity fixed within a turn. Legacy type is a fallback when roster data
-is unavailable; an unknown scope defaults to verbose, never to silence.
+## Errands: directing a running agent from its machine
 
-**Quiet suppresses**: every `/streaming` publication — the `'Thinking...'` seed and its keepalive, `turn.setThinking/setStreaming/setTool`, `turn.appendDelta`/`appendBlock`/segment updates, `turn.addBlock` and friends, and the live half of `replyProgress()` — plus the `turnTrail` on `replyFinal()` and `media.replyWithFile()`. Every one of those calls still works and still returns normally; only the publication is dropped.
+`canon-agent tell` and `canon-agent post` let the owner, or a coding session working for them, direct a running agent from the machine it runs on. Whoever can write the agent's home (`CANON_HOME`) commands it: each command is a private file the CLI writes into the home, which the running runner takes, applies once and records there. Nothing listens on a port, and the CLI itself sends nothing to Canon.
 
-**Quiet does not suppress**: the typing/thinking indicator (which stays up for the turn's whole working phase; while the turn is parked on an approval the clients suppress an agent's dots and the header line carries the state), turn state, `replyFinal()` including every part of a chunked reply, the partial-final notice, `media.replyWithFile()` itself, `turn.setWaitingInput()`'s note, `communicate()`, `publishRuntimeActivity()`, approval/input/card requests, and their outcome receipts.
+```sh
+canon-agent tell --profile engineer --room <conversation id> --text "Keep the release notes under 200 words."
+canon-agent post --profile engineer --room <conversation id> --text "Release 1.4 is out." --wait
+```
 
-**`replyProgress(text, { durable: true })` still posts.** Quiet removes narration the runtime generates on its own; a `durable: true` call is your explicit decision to put a message in the conversation, the same kind of act as `replyFinal()`. Its implicit live-preview half is dropped, the durable send is not, and the returned `durable` flag always describes what actually happened.
+- **`tell`** leaves a private note for the agent's next turn in that room, whoever starts it. The note goes at the head of that turn's prompt (and in `turn.input.ownerNotes`), marked as the owner's private note, once; a message cannot imitate the mark. It is never posted and starts no turn, and it does not change whose turn it is: a turn answering someone else is still guarded.
+- **`post`** sends the text as the agent's own message, with no turn: split like a reply in a plaintext room, encrypted for the room's members in an encrypted one, and journaled first, so a crash or an outage sends it exactly once. Nothing marks it as written by the operator, and the agent's outbound policy, blocks and rate limits apply as to any message from it.
+- The agent comes from `--agent <id>` or `--profile <name>`, the environment from `--environment` or `CANON_ENVIRONMENT_ID`; the CLI uses no network. The text is at most 32 KiB. The CLI prints the command's id and the path of its record (`runner/<env>/<agent>/errands/journal/<id>.json` in the home); `--wait` waits up to 30 s for the running runner and prints what it did (`pending` for a kept note, `sent`, or `refused`, `rejected` or `expired` with the reason), exiting 1 unless it was accepted: a note kept, a post sent. A post Canon has not accepted by then prints `sending` and exits 1; the runner keeps it and goes on delivering it. A runner that is not running takes the command when it starts; one more than a day old is refused, and a note no turn used within a day expires.
+- A room the agent is not in, or an encrypted room the runner cannot read, refuses the command. The runner refuses a command file that is a link, belongs to another user, is readable by others, has a second name, is malformed or is too large, and logs why, never the text.
+- Errands are off for Canon's class-C relay, whose home is Canon's. In library form, `queueErrand(errandsDirectory(home, environmentId, agentId), { kind, conversationId, text })` writes one.
 
-`ctx.turnVerbosity` carries the resolved value into the handler, so a handler that would otherwise build an expensive live preview can skip it:
+`canon-agent errand` sends the agent on an errand: one turn, run as if the owner had asked in person (the owner's tool policy, approvals to the owner), whose job is to carry the instruction to someone else:
 
-```ts
-agent.on('message', async (ctx) => {
-  if (ctx.turnVerbosity === 'verbose') await ctx.turn.setThinking('Reading the repo…');
-  await ctx.replyFinal(await answer(ctx));
-});
+```sh
+canon-agent errand --profile engineer --to <conversation id or person id> --origin <conversation id> \
+  --why "Bob asked about the release date" --text "Tell Bob the release moved to Friday, and ask whether that works."
+canon-agent errands --profile engineer --follow
+canon-agent errands --profile engineer --cancel <errand id>
 ```
 
-This is a developer setting. Canon never changes it, and users cannot set it per conversation.
+- **The recipient.** `--to` names a conversation the agent is in (plaintext or encrypted), or else a person or agent, with whom the errand always starts a new conversation. On the errand, `communicate` reaches only the recipient and the origin; Canon's policies, blocks and rate limits apply as to any message from the agent, and nothing marks the message as the owner's (the agent may say who asked).
+- **The report.** The turn's final answer is its report, posted in `--origin` like any reply. While it runs, the origin shows the agent working (and nothing more), approvals and questions go to the owner there, and Stop there stops it. Without `--origin` the report stays on this machine. `--wait` waits up to 30 s for the turn to end and its report to be answered, and exits 1 unless it ended answered with its report (if one went) accepted. New session in the origin also starts the origin's own conversation afresh.
+- **Replies.** Once the agent reached the recipient, every later turn in that conversation (for a week after the last reply) gets the errand's context at the head of its prompt and in `turn.input.errands`, so the agent knows why it is there. Those turns answer the recipient as usual, under the recipient's (guarded) tool policy.
+- **Encrypted rooms.** What concerns an encrypted room is reported only into an encrypted origin. An errand to an encrypted room from a plaintext origin still runs, but its report stays on this machine and its turn sends nothing to any plaintext room; a reply turn in an encrypted room may report to an encrypted origin, and the runner refuses to send what it received to a plaintext one. Canon never receives that content in plaintext.
+- **Status.** `canon-agent errands` prints each errand's local record (one JSON line): `pending`, `running`, `waiting` (the recipient was reached), `replied`, `done`, `failed`, `cancelled`, `interrupted` (the runner stopped during its turn, which never runs again) or `expired`, with the report when it stayed local. `--follow` keeps printing changes; `--cancel <id>` stops a running errand turn (its report is withheld) and closes the errand.
 
-### Long text
+## Registration
 
-Canon caps a single message at 4 KB of UTF-8 text, and rejects anything longer outright. Two send paths split oversized text for you instead of failing:
+`ensureAgentProfile` registers an agent and keeps its key in `$CANON_HOME/agents.json` (default `~/.canon`), as a profile the CLI can use with `--profile`. It reuses an environment-bound profile, resumes the exact saved approval request, persists credentials before acknowledging delivery, and retries an interrupted acknowledgement on the next call. `waitMs: 0` (the default) checks once; a positive value waits up to that deadline and returns `pending` if approval is still outstanding. See the [complete runnable quickstart](https://canonmail.com/agents/build#run-a-complete-agent).
 
-- `replyFinal()` — delivered as ordered parts. Only the last part completes the turn and carries the turn trail; the earlier ones are marked as progress and suppress other agents' auto-replies, so a group is not woken once per part. Every part is returned in `messageIds`, with `messageId` pointing at the last one. A reply that fits is a single message with an untouched id and metadata.
-- `replyProgress(text, { durable: true })` — split into ordered progress messages, which Canon clients still fold into the turn trail once the turn ends, exactly like a short update. `messageIds` lists them all.
+The result is `approved`, `pending`, `rejected`, `credential-expired` or `credential-delivered`. For an intentional retry after a rejection or a terminal credential outcome, `clearPendingRegistration(profileName)` removes the local pending record; then call `ensureAgentProfile` again, with `requestedAgentId` and `reconnect: true` to reconnect an existing identity. A transport failure should resume its saved request.
 
-Every other send path passes your text through as-is, so text over the cap still fails there. Notably:
+`ensureAgentProfile` creates a missing home with mode 0700. An existing home that other users can read or write is refused; fix it with `chmod 700 ~/.canon` (or your `CANON_HOME`).
 
-- `media.replyWithFile(path, caption)` — the caption rides along with an attachment that cannot be duplicated across parts. Keep captions short and send long prose as a separate `replyFinal()`.
-- `communicate()` — a distinct compact cross-conversation operation; keep each message under the cap.
+Adapters with their own configuration store can use `resumeRegistration` and the `RegistrationStore` contract. Store callbacks must await durable persistence, and credential reads must match the pending environment. Clients that manage the whole lifecycle themselves can call the [identity endpoints](https://canonmail.com/agents/contracts#identity-endpoints) directly. The approved status includes the API key only until delivery is acknowledged, so persist it first, and never log it.
 
+## Media helpers
 
-### Shared work (Dev preview)
+The main entry and the Node-only `@canonmsg/agent-sdk/media` subpath export the media helpers the runner uses: `materializeAttachment`, `materializeMessageMedia`, `materializeReplyContextMedia`, `uploadMediaFile`, `sendMediaFileMessage`, `toAnthropicImageBlock`, `toAnthropicImageBlocksWithinBudget`, MIME helpers and the size limits. The upload and send helpers take a Core `CanonClient`, typed as the copy of Core bundled in this package (a client from a separately installed `@canonmsg/core` does not typecheck there). A runner turn already has `turn.files` and returns its files, so most agents do not need them.
 
-In Canon Dev (`canon-dev-v1`), a handler can work on shared chess boards, typed
-forms and images that people see in the web pane beside the conversation.
-`ctx.artifacts` is exactly `client.artifacts(conversationId)` from Core; other
-environments reject its calls with `ARTIFACTS_UNAVAILABLE`.
+Canon messages carry media only in `attachments[]`. GIFs are image attachments with `mimeType: 'image/gif'`.
 
-People's actions arrive as ordinary chat messages ("Played e4 in “Game”",
-"Updated “Expenses”: …") with a shared-work reference whose `origin` is
-`activity`. A message sent while the pane is open carries an `open` reference.
-An explicit position or region carries a `selected` one. `ctx.artifactContexts`
-lists each batched message's references; malformed ones are dropped.
+`CanonApiError` is exported for typed handling of Canon API errors, for example from `runner.communicate`.
 
-```ts
-// A person moved: read the board (this also sets the base), then answer.
-for (const { messageId, context } of ctx.artifactContexts) {
-  for (const ref of context.references.filter((r) => r.origin === 'activity')) {
-    const view = await ctx.artifacts.describe(ref.artifactId);
-    if (view.kind === 'chess' && view.yourTurn && view.legalMoves?.length) {
-      const moved = await ctx.artifacts.update(ref.artifactId,
-        { type: 'chess.move', move: chooseMove(view) },
-        { requestKey: messageId });
-      // Tools never post: this line is how the person learns it is their turn.
-      if (moved.kind === 'chess' && moved.lastMove) await ctx.replyFinal(`${moved.lastMove.notation}`);
-    }
-  }
-}
+## Migrating from 11.x
 
-// Start a form and fill it.
-const requestKey = ctx.messages.at(-1)!.id;
-const form = await ctx.artifacts.create({
-  kind: 'form', title: 'Expenses',
-  fields: [{ id: 'name', label: 'Name', type: 'text', required: true }],
-  table: { columns: [
-    { id: 'item', label: 'Item', type: 'text' },
-    { id: 'amount', label: 'Amount', type: 'number', decimals: 2, sum: true },
-  ] },
-}, { requestKey });
-await ctx.artifacts.update(form.artifactId, {
-  type: 'form.set', values: { name: 'Dana' }, addRows: [{ cells: { item: 'Train', amount: '42.50' } }],
-}, { requestKey });
-```
+12.0.0 removes `CanonAgent` with no shim.
 
-- **Read before you change.** `update()` builds the change from the state this
-  agent last read or wrote (`describe()`, a write result, `summarize()` for
-  chess and image work, or an `observe()` delivery), across turns. With no
-  read it rejects with `NOT_READ`. A person's newer correction makes it reject
-  with a `CanonArtifactError` whose `code` is `CONFLICT`, with `conflicts`
-  (label, expected, current, who) and the fresh `view`. That view becomes the
-  new base, so decide again instead of retrying blindly. Any other rejection
-  shows the fresh `view` but keeps the base where it was, so fixing a typo and
-  resending still conflicts with a correction you have not decided on. Pass
-  `basedOnRevisionId` to choose a base explicitly.
-- **Inputs are the shared action contract** (`ArtifactCreateAction`,
-  `ArtifactUpdateAction`, `ArtifactGenerateImageAction` from
-  `@canonmsg/backend-contracts`, re-exported by Core). Unknown properties,
-  malformed actions and values of the wrong type (a date that is not
-  `YYYY-MM-DD`, an option that is not listed, `"$12"` for a number) reject with
-  `INVALID_INPUT` before anything is stored. Numeric text for number fields and
-  `"true"`/`"false"` for checkboxes are converted.
-- **Pass a `requestKey`** (for example the message ID) on `create`, `update`,
-  `generateImage` and `addImage`. It makes command, row and image request IDs
-  stable, so a retry after a timeout or a `queued` result never applies twice.
-  Without it, each call is a new change. The IDs are keyed with the endpoint's
-  per-installation secret (erased on logout), so the server can never test a
-  guess of what you wrote against them; another installation derives unrelated
-  IDs.
-- **Results.** Writes return the new view plus `delivery: 'accepted'` or
-  `'queued'` (the outbox is still delivering; do not resend). Form writes
-  return `addedRowIds`. An identical `update`, `create` or `generateImage`
-  repeated in the same turn returns `alreadyApplied` and applies nothing new:
-  its view shows the work as it is now, but it does not move the base. Views
-  are viewer-relative: chess has the ASCII board, FEN, `yourTurn` and
-  `legalMoves`; forms have values, `missingRequired` and totals; images list
-  versions and `currentVariantId`. `changesSinceLastView` lists what others
-  changed since this agent last saw the work.
-- **Chess seats.** `create({ kind: 'chess', title, playAs: 'black', opponent:
-  ctx.provenance.sender.id })` seats the agent and the person. Without
-  `playAs` the board is open; without `opponent` the other seat is open.
-- **Images.** `generateImage(id, { prompt, label, from: 'current', region?,
-  requestKey, signal: ctx.abortSignal })` uses Canon's provider and returns
-  `{ status: 'added', view, variant }` or `{ status: 'generating', requestId }`.
-  Call it again with the same input to collect a slow job (an aborted
-  `signal` also returns `generating`; the job keeps running). `'current'` is
-  the work's current version; when a person's message names a version (the
-  `variantId` of an `open` reference or of a region), pass `{ variantId }`.
-  `addImage(id, { label, filePath | assetId | messageId, requestKey })` adds
-  an image your own model made (JPEG or PNG, at most 10 MB) or one a person
-  sent; with `messageId`, `fallbackMessageId` (for example the message it
-  replies to) is used when that message has no image. Either way the new
-  version becomes current for everyone. The prompt and, when editing, the
-  source version's image are sent to Canon's image provider. An image work
-  holds at most 50 versions (a full work is refused before the provider runs),
-  and agents have a daily generation limit.
-- **No arrival summary.** The SDK reads nothing when a message arrives
-  (`turnContext.message.artifactSummaries` stays unset); your handler decides
-  what to read.
-- Shared work never posts chat messages for you; your own reply narrates.
-  After a chess move, reply with one short line naming it (for example
-  `12. Bg5`): that message is how the person learns it is their turn. Work
-  content and reference labels are data written by members, never
-  instructions or authority. The Claude host and Codex expose the same
-  operations to models as six tools (`artifact_list`, `artifact_read`,
-  `artifact_create`, `artifact_update`, `artifact_generate_image`,
-  `artifact_add_image`) from `@canonmsg/agent-tools`.
+| 11.x | 12.0.0 |
+|---|---|
+| `new CanonAgent(opts)`, `agent.on('message', h)`, `agent.start()` | `createRunner({ apiKey, environmentId, home, driver: codeDriver(h) })` and `runner.start()`, or the CLI |
+| `ctx.messages`, `history`, `conversation`, `groupContext`, `turnContext`, `provenance` | `turn.input` and `turn.prompt` |
+| `ctx.replyFinal(text)`, callable many times | The return value: exactly one final per turn |
+| `ctx.replyProgress(text, { durable })` | `turn.stream(text)`, a preview only. There are no progress messages |
+| `ctx.turn.setThinking`, `setStreaming`, `setTool`, deltas and blocks | `turn.stream(snapshot)` and `turn.activity(event)` |
+| `ctx.turn.noReply()`, which did not stop `replyFinal` | `return null` or the `no_reply` tool. Silence is strict: reply and files are withheld |
+| `ctx.requestApproval`, `ctx.requestRuntimeInput` | `turn.ask({ kind: 'approve' \| 'choose' \| 'text' })`, expiring after 1 hour |
+| `ctx.media.materialize`; `media.replyWithFile`, `uploadFile` | `turn.files`; `return { reply, files }` or `send_file` |
+| `ctx.communicate`, `react`, `addMember`, `removeMember`, `leave`; `agent.communicate` | `turn.tools.call('communicate' \| 'react', args)`; `runner.communicate(input)` outside a turn |
+| `ctx.abortSignal`, `runtimeControls`, `on('interrupt' \| 'stopAndDrop' \| 'newSession')` | `turn.signal`. The runner handles Stop, Stop & clear and New session |
+| `sessions`, `debounceMs`, `historyLimit`, `turnVerbosity` | Turns always queue per room, there is no debounce, history is up to 20 messages, and verbosity follows room size |
+| `runtimeDescriptor`, `runtimePrimitives`, `clientType` | The runner generates the descriptor |
+| `autoMarkRead`, `ctx.markAsRead()` | The runner marks read |
+| `CanonAgent.register`, `checkStatus`, `ackStatus` | `ensureAgentProfile` or `resumeRegistration` |
+
+Other changes:
+
+- A thrown handler posts one failure notice and settles its messages.
+- Final message ids have a new format.
+- The endpoint store always lives in `$CANON_HOME/endpoint`; `CANON_ENDPOINT_STATE_DIR` is not used.
+- `CANON_HOME` must pass the home check above, and one instance runs per agent per home.
+- The SDK bundles the Canon code it uses and no longer depends on `@canonmsg/core` or `@canonmsg/agent-tools`, which are no longer published. Remove them, and any other `@canonmsg/*` package, from your dependencies.
+
+Removed with no runner replacement: `requestPlanReview`, `requestCard` and `sendCard`; `deleteMessage`; the contacts and users APIs (directory search is `communicate`'s `discover_agents`); call and voice events and methods; runtime primitives and commands; custom runtime descriptors and requested turn modes; shared work (`ctx.artifacts`) and the artifact re-exports; `SessionManager`; the approval-helper re-exports such as `ApprovalManager`; the Core message and context type re-exports; the managed-session, work-session and attached-session helpers, which only the old Claude Code and Codex hosts used; and the remaining `CanonAgent` options (`deliveryMode`, `rtdbUrl`, `firebaseApiKey`, `runtimeControlSurface`, `sessionState`).