@north-light/crouter 0.3.323 → 0.3.325

package/docs/sdk/files.md

@@ -0,0 +1,44 @@
+# `client.files`
+
+`client.files` reads, writes, and lists host files through the daemon.
+
+```ts
+const source = await client.files.read('/absolute/path/to/input.txt');
+const written = await client.files.write('/absolute/path/to/output.txt', source.content);
+const directory = await client.files.list('/absolute/path/to');
+```
+
+Every `path` is absolute. Relative paths and `~` are not expanded. File paths are sent to the daemon unchanged; the daemon checks that they are absolute and returns a mapped API error when they are not.
+
+Every method accepts ordinary request options in its final object: `headers`, `signal`, `timeout`, and `maxRetries`. `read` and `write` add `encoding`; `list` adds `limit`.
+
+## Read
+
+```ts
+await client.files.read(path, { encoding: 'utf8', timeout: 5_000 });
+await client.files.read(path, { encoding: 'base64' });
+```
+
+`read(path, options?)` returns `Promise<FilePeekDTO>`, `{ path, content, truncated }`, through `GET /v1/files/peek`. It captures at most 512 KiB of file bytes. `truncated: true` means `content` is only the prefix. Request `base64` for binary content.
+
+## Write
+
+```ts
+const result = await client.files.write(path, content, { encoding: 'utf8' });
+// result is { path, bytes_written }
+await client.files.write(path, bytes.toString('base64'), { encoding: 'base64' });
+```
+
+`write(path, content, options?)` returns `Promise<FileWriteDTO>`, `{ path, bytes_written }`. Writes create parent directories and atomically replace the target. If `path` is an existing symlink, the daemon resolves it and atomically replaces its destination; the symlink remains. Decoded content above 1 MiB is refused with `UnprocessableEntityError` carrying `status: 413` and `code: 'file_too_large'`; it is never truncated or partially written.
+
+## List
+
+```ts
+const result = await client.files.list(path, { limit: 100 });
+```
+
+`list(path, options?)` returns `Promise<FileListDTO>`, `{ path, entries, truncated }`, for one directory level. Each entry has `name`, `type: 'file' | 'dir' | 'other'`, `size`, and ISO-8601 `modified`. `limit` must be a positive integer; the default is 1000. `truncated: true` means the directory had more entries than the requested limit.
+
+## Authority
+
+The token is the owner credential. Anyone holding it can already create an agent with a bash tool, so these methods run with the daemon user's authority and do not provide a restricted file area.

package/docs/sdk/getting-started.md

@@ -156,5 +156,5 @@ An outcome is returned, never thrown — including a decline and a failure. Only
 - Every constructor option and environment-variable fallback: [Client construction](./client.md)
 - Checking the daemon connection and selected provider before a run: `client.auth.status()` above
 - The full create-parameter table and the outcome union: [Nodes](./nodes.md)
-- Watching a run as it works: [Streaming](./streaming.md) (phase 2)
+- Watching a run as it works: [Streaming](./streaming.md)
 - Running the daemon in a container instead: [Docker environment](./docker.md)

package/docs/sdk/migration.md

@@ -68,7 +68,7 @@ else console.error(run.reason, run.detail);
 | `client.ensureProfile('x')` | `client.profiles.ensure('x')` |
 | `schema` | `output_schema` |
 | `signal` in the params object | `signal` in the second argument, the per-request options |
-| `onEvent` | `client.nodes.stream()` — [Streaming](./streaming.md), phase 2 |
+| `onEvent` | `client.nodes.stream()` — [Streaming](./streaming.md) |
 | the `Environment` interface | deleted; nothing implements it |
 
 ## The result union changed
@@ -101,7 +101,7 @@ Aborting still stops **your client waiting**, not the run. Call `client.nodes.ca
 - Reports are available from `client.nodes.reports.list(id)`.
 - Settlement is the return of `waitForOutcome`.
 
-Streaming (phase 2) is strictly more capable than `onEvent` was: the three events it emitted are three of the events the stream carries, alongside assistant text deltas and tool calls.
+Streaming is strictly more capable than `onEvent` was: the three events it emitted are three of the events the stream carries, alongside assistant text deltas and tool calls.
 
 ## `CrtrClient` is no longer yours to construct
 

package/docs/sdk/nodes.md

@@ -1,6 +1,6 @@
 # `client.nodes`
 
-Phase 1, except where a row says otherwise.
+Shipped, except where a row says otherwise.
 
 A node is one agent run on the crouter canvas. It is asynchronous by construction: `create` returns as soon as the daemon has spawned it, and the run keeps working after your call returns.
 
@@ -20,20 +20,22 @@ There is one name for it — `client.nodes`. There is no `client.responses` alia
 | `nodes.message(id, body)` | `POST /v1/nodes/{id}/messages` | 1 | Send a follow-up to a running or dormant node. |
 | `nodes.interrupt(id)` | `POST /v1/nodes/{id}/interrupt` | 1 | Stop the current turn, keep the node. |
 | `nodes.cancel(id, body?)` | `POST /v1/nodes/{id}/close` | 1 | Tears the node and its exclusive subtree down. `cancel` is the method name; `close` is the route. |
-| `nodes.update(id, patch)` | `PATCH /v1/nodes/{id}/config` | 2 | |
-| `nodes.fork(id)` | `POST /v1/nodes/{id}/fork` | 2 | |
-| `nodes.revive(id, body?)` | `POST /v1/nodes/{id}/revive` | 2 | |
-| `nodes.promote(id, body?)` / `nodes.demote(id, body?)` | matching routes | 2 | Move a node between base and orchestrator mode. |
-| `nodes.recycle(id, body?)` | `POST /v1/nodes/{id}/recycle` | 2 | |
-| `nodes.yield(id, body?)` | `POST /v1/nodes/{id}/yield` | 2 | |
-| `nodes.wait(id, body?)` | `POST /v1/nodes/{id}/wait` | 2 | |
-| `nodes.relaunchRoot(id, body?)` | matching route | 2 | |
-| `nodes.reviveAll(body?)` | `POST /v1/nodes/revive-all` | 2 | |
-| `nodes.stream(params)` | create + `GET /…/events` | 2 | [Streaming](./streaming.md). |
-| `nodes.events(id, opts?)` | `GET /v1/nodes/{id}/events` | 2 | [Streaming](./streaming.md). |
+| `nodes.update(id, patch)` | `PATCH /v1/nodes/{id}/config` | Shipped | |
+| `nodes.fork(id)` | `POST /v1/nodes/{id}/fork` | Shipped | |
+| `nodes.revive(id, body?)` | `POST /v1/nodes/{id}/revive` | Shipped | |
+| `nodes.promote(id, body?)` / `nodes.demote(id)` | matching routes | Shipped | Move a node between base and orchestrator mode. |
+| `nodes.recycle(id)` | `POST /v1/nodes/{id}/recycle` | Shipped | |
+| `nodes.yield(id, body?)` | `POST /v1/nodes/{id}/yield` | Shipped | |
+| `nodes.wait(id, body)` | `POST /v1/nodes/{id}/wait` | Shipped | |
+| `nodes.relaunchRoot(id)` | matching route | Shipped | |
+| `nodes.reviveAll()` | `POST /v1/nodes/revive-all` | Shipped | |
+| `nodes.stream(params, options?)` | create + `GET /…/events` | Shipped | [Streaming](./streaming.md). |
+| `nodes.events(id, options?)` | `GET /v1/nodes/{id}/events` | Shipped | [Streaming](./streaming.md). |
 
 Action methods keep the product's literal name (`fork`, `revive`, `promote`, `yield`) rather than being renamed into a generic verb.
 
+Every method in the table accepts `RequestOptions` as its final argument: `{ headers?, signal?, timeout?, maxRetries? }`. `nodes.stream(params, options?)` uses those options for create and stream opening, except that its stream has no wall-clock `timeout`; `nodes.events(id, options?)` takes `NodeEventsOptions`, which adds `after` and excludes `timeout`.
+
 ## Create parameters
 
 Wire fields are `snake_case`. Every `NodeCreateParams` property is optional; `parse()` additionally requires `output_schema`. `NodeCreateParams` is the daemon's `CreateNodeRequest`, except `output_schema` also accepts an object. When neither `parent` nor `root` is supplied, the SDK sends `root: true`; otherwise fields pass through without camelizing.
@@ -165,21 +167,12 @@ Nested routes become nested properties.
 
 | Property | Methods | Phase |
 |---|---|---|
-| `nodes.reports` | `list` | 1 (`create` in 2) |
-| `nodes.messages` | `list` | 2 |
-| `nodes.artifacts` | `list` | 2 |
-| `nodes.context` | `list` | 2 |
-| `nodes.transcript` | `retrieve` | 2 |
-| `nodes.session` | `retrieve` | 2 |
-| `nodes.snapshot` | `retrieve` | 2 |
-| `nodes.subject` | `retrieve` | 2 |
-| `nodes.outcomeDelivery` | `create`, `retrieve`, `delete` | 2 |
-| `nodes.subscriptions` | `create`, `delete` | 2 |
-| `nodes.jobs` | `list`, `cancel` | 2 |
-| `nodes.worktree` | `close`, `abandon` | 2 |
-| `nodes.result` | `submit` | 2 — only an agent inside a run calls this |
-
-`nodes.reports.list(id)` is how an application shows progress before streaming lands: an agent pushes a report whenever it has something to say, and the list is newest-first.
+| `nodes.reports` | `list` | Shipped |
+| `nodes.jobs` | `list`, `cancel` | Shipped |
+| `nodes.worktree` | `close`, `abandon` | Shipped |
+| `nodes.result` | `submit` | Shipped — only an agent inside a run calls this |
+
+`nodes.reports.list(id)` returns the agent's pushed progress reports, newest first. Use it when reports are the progress view your application needs; use [streaming](./streaming.md) for live output and tool-call events.
 
 ```ts
 const reports = await client.nodes.reports.list(node.node_id, { limit: 10 });
@@ -190,4 +183,8 @@ for (const report of reports) console.log(report.tier, report.body);
 
 List routes return what the daemon returns. `nodes.list`, `nodes.reports.list`, and `nodes.jobs.list` return plain arrays — there is no page object, no `hasNextPage()`, and no `after` cursor on them, because the daemon has no paging substrate behind those routes and an envelope there would promise a continuation that can never happen.
 
-The one place the page envelope exists is the memory routes. See [Memory](./memory.md).
+The one place the page envelope exists is the phase-3 memory routes. See [Memory](./memory.md).
+
+## Identifier validation
+
+Methods that take a node id validate it before the request: core node methods, lifecycle methods, `nodes.reports`, `nodes.jobs`, `nodes.worktree`, and `nodes.result`. An invalid id throws `TypeError` locally and sends no request. `nodes.outcome(id, { wait })` also throws `RangeError` locally when `wait` is not an integer from 0 through 25.

package/docs/sdk/resources.md

@@ -1,45 +1,53 @@
 # Resource map
 
-Every namespace on the client, with the phase it lands in. A namespace marked phase 2 or phase 3 does not exist yet.
-
-Namespaces are camelCase. Verbs are `create`, `retrieve`, `list`, `update`, `delete`, and `cancel`, except where the product already has a literal name for the action (`fork`, `revive`, `promote`, `pause`, `poke`) — in which case the SDK uses that name.
-
-| Namespace | Methods | Routes | Phase |
-|---|---|---|---|
-| `nodes` | `create`, `retrieve`, `list`, `cancel`, `interrupt`, `message`, `outcome`, `waitForOutcome`, `createAndWait`, `parse` | `/v1/nodes…` | 1; remaining methods in 2 |
-| `nodes.reports` | `list` | `/v1/nodes/{id}/reports` | 1 (`create` in 2) |
-| `nodes.messages` | `list` | `/v1/nodes/{id}/messages` | 2 |
-| `nodes.artifacts` | `list` | `/v1/nodes/{id}/artifacts` | 2 |
-| `nodes.context` | `list` | `/v1/nodes/{id}/context` | 2 |
-| `nodes.transcript` | `retrieve` | `/v1/nodes/{id}/transcript` | 2 |
-| `nodes.session` | `retrieve` | `/v1/nodes/{id}/session` | 2 |
-| `nodes.snapshot` | `retrieve` | `/v1/nodes/{id}/snapshot` | 2 |
-| `nodes.subject` | `retrieve` | `/v1/nodes/{id}/subject` | 2 |
-| `nodes.outcomeDelivery` | `create`, `retrieve`, `delete` | `/v1/nodes/{id}/outcome-delivery` | 2 |
-| `nodes.subscriptions` | `create`, `delete` | `/v1/nodes/{id}/subscriptions` | 2 |
-| `nodes.jobs` | `list`, `cancel` | `/v1/nodes/{id}/jobs` | 2 |
-| `nodes.worktree` | `close`, `abandon` | `/v1/nodes/{id}/worktree/…` | 2 |
-| `nodes.result` | `submit` | `POST /v1/nodes/{id}/result` | 2 — only an agent inside a run calls this |
-| `profiles` | `ensure`, `retrieve` | `/v1/profiles…` | 1; remaining methods in 2 |
-| `auth` | `status` | `GET /v1/status`, then `GET /v1/model-auth/readiness` once the daemon is ready | 1 |
-| `system` | `status`, `health`, `restart`, `admit`, `migrate` | `/v1/status`, `/healthz`, `/v1/daemon/…` | 1 for `status` and `health`; 3 for the rest |
-| `files` | `peek` | `/v1/files/peek` | 1 |
-| `bash` | — | — | 2 — reserved; not on the client today |
-| `llm` | — | — | Reserved; unbuilt |
-| `providers` | — | — | Reserved; unbuilt |
-| `canvas` | `attention`, `attentionCounts`, `snapshot`, `roster`, `dashboard`, `prune` | `/v1/canvas…` | 2 |
-| `canvas.history` | `search`, `grep`, `read`, `stats` | `/v1/canvas/history/…` | 2 |
-| `crons` | `create`, `retrieve`, `list`, `pause`, `resume`, `run`, `delete`, `poke` | `/v1/crons…` | 2 |
-| `human.requests` | `create`, `retrieve`, `replace`, `respond`, `dismiss`, `cancel` | `/v1/human/requests…` | 2 |
-| `human.inbox` | `list`, `retrieve`, `respond`, `progress`, `cancel`, `history`, `response` | `/v1/human/inbox…` | 2 |
-| `models.credentials` | `list`, `install`, `remove` | `/v1/model-auth…` | 2 |
-| `models.config` | `update` | `PUT /v1/model-config` | 2 |
-| `memory` | `list`, `retrieve`, `create`, `update`, `delete`, `move`, `search`, `history`, `resolve` | `/v1/memory…` | 3 — [Memory](./memory.md) |
-| `human.reviews` | `create`, `retrieve`, `list`, `submit`, `cancel`, `document` | `/v1/human/reviews…` | 3 |
-| `human.reviews.comments` / `human.comments` | `create`, `list`, `retrieve`, `edit`, `resolve`, `reopen`, `delete`, `fork`, `events`, `ranges` | `/v1/human/…comments…` | 3 |
-| `human.inbox.feedbackComments` | `create`, `resolve` | `/v1/human/inbox/{ticket}/feedback-comments…` | 3 |
-| `models.chatInventory` | `retrieve(nodeId)`, `prospective(query)` | `/v1/nodes/{id}/chat-inventory`, `/v1/prospective-chat-inventory` | 3 |
-| `worktrees` | `listQuarantined` | `/v1/worktrees/quarantined` | 3 |
+Every namespace exported by the client. Namespaces are camelCase. Verbs are `create`, `retrieve`, `list`, `update`, `delete`, and `cancel`, except where the product already has a literal name for the action (`fork`, `revive`, `promote`, `pause`, `poke`) — in which case the SDK uses that name.
+
+| Namespace | Methods | Routes |
+|---|---|---|
+| `nodes` | `create`, `retrieve`, `list`, `update`, `cancel`, `interrupt`, `message`, `outcome`, `waitForOutcome`, `createAndWait`, `parse`, `stream`, `events`, `fork`, `revive`, `reviveAll`, `promote`, `demote`, `recycle`, `yield`, `wait`, `relaunchRoot` | `/v1/nodes…` |
+| `nodes.reports` | `list` | `/v1/nodes/{id}/reports` |
+| `nodes.jobs` | `list`, `cancel` | `/v1/nodes/{id}/jobs` |
+| `nodes.worktree` | `close`, `abandon` | `/v1/nodes/{id}/worktree/…` |
+| `nodes.result` | `submit` | `POST /v1/nodes/{id}/result` |
+| `profiles` | `ensure`, `retrieve` | `/v1/profiles…` |
+| `auth` | `status` | `GET /v1/status`, then `GET /v1/model-auth/readiness` once the daemon is ready |
+| `system` | `status`, `health` | `/v1/status`, `/healthz` |
+| `files` | `read`, `write`, `list` | `/v1/files/peek`, `/v1/files/write`, `/v1/files/list` |
+| `bash` | `run` | `/v1/bash` |
+| `canvas` | `attention`, `attentionCounts`, `snapshot`, `roster`, `dashboard`, `prune` | `/v1/canvas…` and composed node/status requests for `dashboard` |
+| `canvas.history` | `search`, `grep`, `read`, `stats` | `/v1/canvas/history/…` |
+| `crons` | `create`, `retrieve`, `list`, `pause`, `resume`, `run`, `delete`, `poke` | `/v1/crons…` |
+| `human.requests` | `create`, `retrieve`, `replace`, `respond`, `dismiss`, `cancel` | `/v1/human/requests…` |
+| `human.inbox` | `list`, `retrieve`, `respond`, `progress`, `cancel`, `history`, `response` | `/v1/human/inbox…` |
+| `models.credentials` | `list`, `install`, `remove` | `/v1/model-auth…` |
+| `models.config` | `update` | `PUT /v1/model-config` |
+| `memory` | `list`, `retrieve`, `create`, `update`, `delete`, `move`, `search`, `history`, `resolve` | `/v1/memory…` — phase 3; see [Memory](./memory.md) |
+
+Action methods keep the product's literal name (`fork`, `revive`, `promote`, `yield`) rather than being renamed into a generic verb. Every request-capable method takes `RequestOptions` as its final argument after its path, body, or query arguments. `RequestOptions` is `{ headers?, signal?, timeout?, maxRetries? }`; stream event options exclude `timeout` and add `after`.
+
+## Files and bash
+
+[`client.files`](./files.md) reads through `GET /v1/files/peek`, atomically writes, and lists absolute host paths. Reads and lists report `truncated`; writes over 1 MiB are refused instead of truncated. [`client.bash`](./bash.md) runs one command in a required absolute working directory and returns non-zero exits as values.
+
+## Canvas
+
+`client.canvas.attention()`, `attentionCounts(body)`, `snapshot()`, `roster()`, and `prune(body)` each send their matching canvas route. `dashboard(query?)` composes `GET /v1/nodes` and `GET /v1/status`, because the daemon deliberately has no dashboard route. `client.canvas.history.search(body)`, `grep(body)`, `read(query)`, and `stats(body)` wrap the four history routes.
+
+## Crons
+
+`client.crons.create(body)`, `retrieve(id, query?)`, `list(query?)`, `pause(id, query?)`, `resume(id, query?)`, `run(id, query?)`, `delete(id, query?)`, and `poke()` retain the daemon's cron DTOs and snake_case query fields. `delete` is the SDK verb for the daemon's `DELETE /v1/crons/{id}` route.
+
+## Human requests and inbox
+
+`client.human.requests` exposes `create`, `retrieve`, `replace`, `respond`, `dismiss`, and `cancel`. `client.human.inbox` exposes `list`, `retrieve`, `respond`, `progress`, `cancel`, `history`, and `response`. The inbox methods preserve the page protocol's nested camelCase fields and the daemon envelope's snake_case fields.
+
+## Models
+
+`client.models.credentials.list()`, `install(provider, body)`, and `remove(provider)` wrap `/v1/model-auth`. `client.models.config.update(body)` sends `PUT /v1/model-config`. Credential material is accepted only by `install`; list responses remain sanitized daemon DTOs.
+
+## Identifier validation
+
+Methods with node, cron, bash-job, human-request, inbox-ticket, provider, or profile identifiers validate them before calling the daemon. Invalid values throw `TypeError` locally and send no request. This applies to node action methods and nested node resources, cron methods that take an id, `human.requests` methods that take an id, `human.inbox` methods that take a ticket id, `models.credentials.install` and `remove`, and profile `ensure` and `retrieve`. File paths are not subject to this identifier check; the daemon validates their absolute-path contract.
 
 ## Excluded from the typed surface
 
@@ -68,4 +76,4 @@ const focuses = await client.request<FocusDTO[]>('GET', '/v1/focuses');
 await client.request('POST', `/v1/nodes/${id}/some-new-route`, { field: 'value' }, { timeout: 5_000 });
 ```
 
-If you find yourself reaching for `client.request()` for something an application genuinely needs, that route belongs in one of the tables above. Say so rather than building on the escape hatch.
+If you find yourself reaching for `client.request()` for something an application genuinely needs, that route belongs in the table above. Say so rather than building on the escape hatch.

package/docs/sdk/streaming.md

@@ -1,42 +1,52 @@
-> **Phase 2 — not shipped.** Nothing on this page exists yet. There is no HTTP streaming route on the daemon today, and `client.nodes.stream` and `client.nodes.events` are not on the client. Until phase 2 lands, an application shows progress with `client.nodes.reports.list` and gets the result with `client.nodes.waitForOutcome`.
-
 # Streaming
 
 Watch a run as it works: assistant text as it is produced, tool calls as they start and finish, reports as they are pushed, and the settled outcome.
 
 ## The SDK surface
 
-<!-- TODO(verify): run against a live daemon once phase 2 lands. -->
-
 ```ts
-const stream = client.nodes.stream({ prompt: 'Fix the failing test', cwd });
+const stream = client.nodes.stream({ prompt: 'Fix the failing test', cwd }, { headers: { 'x-trace': 'run-9' } });
 
-stream.on('node.output_text.delta', (e) => process.stdout.write(e.delta));
+stream.on('node.output_text.delta', (event) => process.stdout.write(event.delta));
 
 for await (const event of stream) {
   // the same events, typed by `type`
 }
 
-const outcome = await stream.finalOutcome();  // resolves on node.settled
-stream.abort();                                // ends the HTTP response; the node keeps running
+const outcome = await stream.finalOutcome(); // resolves on node.settled
+stream.abort(); // ends the HTTP response; the node keeps running
 ```
 
 | Member | Behaviour |
 |---|---|
-| `client.nodes.stream(params)` | Creates the node, then opens its event stream. Returns **synchronously**; `stream.node` is a promise for the created node. |
-| `client.nodes.events(id, { after?, signal? })` | Streams a node that already exists. |
-| `.on(type, cb)` / `.off(type, cb)` | Typed event emitter. |
-| `[Symbol.asyncIterator]` | Yields the same typed events. |
-| `.finalOutcome()` | Resolves with the `NodeOutcome` from `node.settled`; rejects on a terminal `error` event. |
-| `.abort()` / `signal` | Aborts the underlying `fetch`. Raises `APIUserAbortError` in an in-flight iteration. |
+| `client.nodes.stream(params, options?)` | Creates the node, then opens its event stream. Returns **synchronously**; `stream.node` is a `Promise<NodeDetailDTO>` for the created node. The request options apply to creation and to opening the stream, except `timeout`, because a stream has no wall-clock timeout. |
+| `client.nodes.events(id, options?)` | Validates and retrieves an existing node, then streams it. `options` is `NodeEventsOptions`: `after` plus request `headers`, `signal`, and `maxRetries`; it deliberately has no `timeout`. |
+| `.on(type, listener)` / `.off(type, listener)` | Typed event emitter; each returns the `NodeStream`. |
+| `[Symbol.asyncIterator]()` | Yields the same `NodeEventDTO` union. |
+| `.finalOutcome()` | Returns `Promise<NodeOutcomeDTO>`, resolving on `node.settled` and rejecting on a terminal `error` event or a connection failure. |
+| `.abort()` | Aborts the underlying `fetch`. An in-flight iterator and `finalOutcome()` reject with `APIUserAbortError`. Passing your own `signal` in the options aborts the stream the same way; `NodeStream` exposes no `signal` property. |
 
 The method is called `events`, not `subscribe`: a subscription is already a push-delivery edge between two nodes on the canvas, and one word must not mean two things.
 
 **A stream is an observer, never a lifecycle hold.** Disconnecting drops your subscriber and leaves the node running. Opening a stream never revives a dormant node — call `client.nodes.revive(id)` first if that is what you want.
 
+## Activity helper
+
+`followActivity(stream, { describe? })` turns streamed tool-call events into immutable `ActivityStep[]` snapshots for a plain activity feed. `describeToolDefault(tool, summary)` names the common tools; pass `describe` to use labels for your application or return `null` to hide a tool call. Tool summaries describe the argument shape, never argument values or raw arguments.
+
+```ts
+import { followActivity } from '@north-light/crouter-sdk';
+
+for await (const steps of followActivity(stream)) {
+  render(steps);
+}
+```
+
+A step starts as `running`; a `node.tool_call.completed` event changes it to `done` when `status` is `ok` or `failed` when `status` is `error`.
+
 ## Events
 
-Each event carries `node_id` and a `sequence_number` in addition to the fields listed.
+Every event except `error` carries `node_id` and `sequence_number` in addition to the fields listed. `error` carries only its error object.
 
 | Event | `data` |
 |---|---|
@@ -47,11 +57,11 @@ Each event carries `node_id` and a `sequence_number` in addition to the fields l
 | `node.turn.started` | `{ node_id, sequence_number }` |
 | `node.turn.completed` | `{ node_id, sequence_number }` |
 | `node.report.pushed` | `{ node_id, sequence_number, report }` |
-| `node.status.changed` | `{ node_id, sequence_number, status }` |
+| `node.status.changed` | `{ node_id, sequence_number, status }`, where `status` can also be stream-only `'dormant'` |
 | `node.settled` | `{ node_id, sequence_number, outcome }` — terminal; the daemon ends the response after it |
-| `error` | `{ error: { code, message, details? } }` — terminal |
+| `error` | `{ error: { code: 'stream_gap' \| 'stream_dropped' \| 'stream_error', message, details?: { earliest_sequence?: number } } }` — `stream_gap` is recoverable; the other codes terminate the response |
 
-`summary` on a tool-call event is a capped rendering of the arguments, never the raw arguments.
+`summary` on a tool-call event states whether arguments are null, an array and its item count, an object and its field count, or a primitive type. It never includes argument values or tool output.
 
 **Deliberately not carried:** thinking deltas, the model's tool-call construction deltas, raw tool output, and the system prompt. Those belong to the owner's viewer, not to an application's run stream.
 
@@ -68,57 +78,63 @@ Server-sent events: one record per event as `event: <type>`, `data: <JSON>`, bla
 
 | Node state when you call | What the stream does |
 |---|---|
-| Already settled | Writes `node.settled` with the outcome and ends. Nothing is revived. |
+| Already settled | Writes retained events when available, ending in `node.settled`; otherwise writes `node.settled` with the outcome and ends. Nothing is revived. |
 | Running | Streams live, seeded as described below. |
 | Dormant and not settled | Writes `node.status.changed { status: 'dormant' }` and holds the response open with keepalives. It starts streaming if and when the daemon brings a broker up for that node. |
 
-A node can settle between your `create` and your `events` call, so both branches are ordinary. Either way the terminal event is `node.settled`, read from the same outcome row `nodes.outcome` reads — a client that joins after settlement and a client that was live at settlement see the same event.
+A node can settle between your `create` and your `events` call, so both branches are ordinary. Either way the terminal event is `node.settled`, read from the same outcome row `nodes.outcome` reads — a client that joins after settlement and a client that was live at settlement see the same outcome.
 
 ## Sequence, resume, and failure
 
-`sequence_number` is monotonic per node. The daemon keeps one in-memory ring per streamed node holding the last 512 events or 256 KiB, whichever binds first.
+`sequence_number` is monotonic per node while that node's in-memory stream hub exists. The daemon keeps one in-memory ring per streamed node holding the last 512 events or 256 KiB, whichever binds first.
 
 | Situation | Behaviour |
 |---|---|
-| You join a run already in progress | Seeded from the broker's snapshot: one `node.output_text.done` per completed assistant message, then one `node.output_text.delta` carrying the accumulated partial, then live. No content is lost — only delta granularity. |
+| You join a run already in progress | First replays already-pushed reports oldest first, then seeds from the broker's snapshot: one `node.output_text.done` per completed assistant message, then one `node.output_text.delta` carrying the accumulated partial, then live. No content is lost — only delta granularity. |
 | A second subscriber joins | Seeded from the ring, so both subscribers see the same sequence numbers. |
-| `after=N` within the ring | Replays from `N+1`. |
-| `after=N` older than the ring floor | An `error` event with code **`stream_gap`** carrying the earliest available sequence, **then the stream continues from the floor**. It never silently skips; you learn exactly what you lost. |
-| Your reader is too slow | The broker drops a client past 1000 queued frames or 32 MiB. You get an `error` with code **`stream_dropped`** and the response ends. One slow reader cannot stall the engine. |
-| The node's broker is replaced (revive, respawn) | The daemon reconnects and emits `node.status.changed`. Sequence continues. |
-| The daemon restarts | The ring is gone. A resuming client gets `stream_gap` from sequence 1. There is no durable event log. |
+| `after=N` within the retained range | Replays events after `N`. |
+| `after=N` outside the retained range, including a future cursor | An `error` event with code **`stream_gap`** carries the earliest available sequence, then the stream continues from that point. It never silently skips. |
+| One event exceeds the 256 KiB replay budget | Live subscribers receive it, but the daemon clears the resume ring. A cursor before that event gets `stream_gap`; a cursor on it resumes at the next retained event. |
+| Your HTTP reader is too slow | The daemon ends the response with an `error` event whose code is **`stream_dropped`**. One slow reader cannot stall the engine. |
+| The node's broker is replaced or its observer socket closes | The daemon reconnects and emits `node.status.changed`. Sequence continues while the stream hub remains in memory. |
+| The daemon restarts | The ring is gone. A resuming client gets `stream_gap` with `earliest_sequence: 1`. There is no durable event log. |
 | You disconnect | Your subscriber is dropped. The node keeps running. |
 
 ### Resuming
 
-<!-- TODO(verify): run against a live daemon once phase 2 lands; confirm the field carrying the earliest available sequence on a `stream_gap` error. -->
-
 ```ts
+import { APIError } from '@north-light/crouter-sdk';
+
 let cursor: number | undefined;
 
 for (;;) {
   const stream = client.nodes.events(id, { after: cursor });
   try {
     for await (const event of stream) {
-      if (event.type === 'error' && event.error.code === 'stream_gap') {
-        console.warn('missed events before', event.error.details?.earliest_sequence);
-        continue;  // the stream continues from the floor
+      if (event.type === 'error') {
+        if (event.error.code === 'stream_gap') {
+          console.warn('missed events before', event.error.details?.earliest_sequence);
+          continue; // the stream continues from the floor
+        }
+        throw new APIError(0, event.error.code, event.error.message, event.error.details);
       }
       cursor = event.sequence_number;
       handle(event);
     }
-    return;  // ended on node.settled
-  } catch (e) {
-    if (isDropped(e)) continue;  // stream_dropped — reconnect from the cursor
-    throw e;
+    return; // ended on node.settled
+  } catch (error) {
+    if (error instanceof APIError && error.code === 'stream_dropped') continue;
+    throw error;
   }
 }
 ```
 
 `stream_gap` is recoverable and the stream continues after it. `stream_dropped` is terminal for that HTTP response — reconnect with the cursor you last saw.
 
+## Identifier validation
+
+`nodes.events(id, options?)` validates `id` before it requests the node or opens SSE. Because it returns a `NodeStream` synchronously, an invalid node identifier rejects `stream.node`, `stream.finalOutcome()`, and an iteration with `TypeError`; no request is sent. See [Errors](./errors.md#identifier-validation).
+
 ## Event shapes depend on the pinned pi version
 
 The delta and tool-call shapes come from the installed `@earendil-works/pi-agent-core` and `pi-ai` packages, not from crouter. The daemon's translator is the one place that depends on them. A pi version bump must be checked against it.
-
-<!-- TODO(verify): record the pi version the phase-2 event table was verified against once streaming lands. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.323",
+  "version": "0.3.325",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.323",
+  "version": "0.3.325",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.323",
+      "version": "0.3.325",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,20 +5206,20 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.323",
+      "version": "0.3.325",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.323",
+      "version": "0.3.325",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.323",
+      "version": "0.3.325",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.321"
+        "@north-light/crouter-api": "^0.3.322"
       }
     }
   }