@north-light/crouter 0.3.321 → 0.3.323

package/docs/sdk/migration.md

@@ -0,0 +1,108 @@
+# Migration from `generate()` and `local()`
+
+Phase 1.
+
+**This is a hard cut.** `generate()`, `local()`, and the `Environment` interface are deleted in the same release that adds `Crouter`. There is no coexistence period, no deprecated re-export, and no compatibility shim. Both packages are pre-1.0 and the callers are countable.
+
+Pin your old version or migrate; there is no third option.
+
+## Before and after
+
+```text
+// before
+import { generate, local } from '@north-light/crouter-sdk';
+import { z } from 'zod';
+
+const schema = z.object({ name: z.string(), version: z.string() });
+
+const result = await generate({
+  prompt: 'Read package.json and report its name and version.',
+  schema,
+  env: local(),
+  cwd: '/path/to/repo',
+  profile: 'my-app',
+  kind: 'general',
+  model: 'anthropic/strong',
+  deadline: '10m',
+  signal,
+});
+
+if (result.kind === 'result') console.log(result.value.name);
+else if (result.kind === 'declined') console.warn(result.reason);
+else console.error(result.reason, result.detail);
+```
+
+```ts
+// after
+import Crouter from '@north-light/crouter-sdk';
+import { z } from 'zod';
+
+const client = new Crouter();
+
+const run = await client.nodes.parse(
+  {
+    prompt: 'Read package.json and report its name and version.',
+    output_schema: z.object({ name: z.string(), version: z.string() }),
+    cwd: '/path/to/repo',
+    profile: 'my-app',
+    kind: 'general',
+    model: 'anthropic/strong',
+    deadline: '10m',
+  },
+  { signal },
+);
+
+if (run.kind === 'result') console.log(run.output_parsed.name);
+else if (run.reason === 'declined') console.warn(run.declined?.reason);
+else console.error(run.reason, run.detail);
+```
+
+## What moved where
+
+| Before | After |
+|---|---|
+| `generate({ … })` | `client.nodes.parse({ … })` |
+| `local()` / `env: local()` | `new Crouter()` — the client is the connection |
+| `local({ autostart: false })` | `new Crouter({ autostart: false })` |
+| `env.daemon()` + `new CrtrClient(…)` | `new Crouter(env.connection())` — see [Docker environment](./docker.md) |
+| `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 |
+| the `Environment` interface | deleted; nothing implements it |
+
+## The result union changed
+
+`generate()` returned a three-way union of its own invention. `parse()` returns the settled `NodeOutcome` the daemon already defines — the same union the wire has, not a translation of it.
+
+| `generate()` | `parse()` |
+|---|---|
+| `{ kind: 'result', value, nodeId, reportPath }` | `{ kind: 'result', output_parsed, structured_result, final_report_path, … }` |
+| `{ kind: 'declined', reason, nodeId }` | `{ kind: 'failure', reason: 'declined', declined: { reason, code, retryable } \| null, … }` |
+| `{ kind: 'failure', reason, detail, nodeId }` | `{ kind: 'failure', reason, detail, … }` |
+
+A decline is now a `failure` with `reason: 'declined'`, so narrow on `run.reason === 'declined'` rather than `run.kind === 'declined'`. It carries more than the old shape did: the agent's own code and a `retryable` flag.
+
+`value` became `output_parsed`, and `reportPath` became `final_report_path`.
+
+Every `NodeOutcomeDTO` carries the wire field `node_id`.
+
+## `signal` actually cancels now
+
+`generate()` raced an abort against a promise it could not cancel. `parse()` passes the signal to `fetch`, so aborting stops the in-flight request and raises `APIUserAbortError`.
+
+Aborting still stops **your client waiting**, not the run. Call `client.nodes.cancel(id)` to stop the agent, or give it a `deadline` so the daemon stops it for you.
+
+## Progress reporting
+
+`onEvent` emitted three notifications: node created, report pushed, settled. Two of its three are available in phase 1 without it:
+
+- The node is created when `client.nodes.create()` returns — you hold the node.
+- 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.
+
+## `CrtrClient` is no longer yours to construct
+
+The SDK does not re-export `CrtrClient` — the raw client is an implementation detail of `Crouter`. If you were constructing one to reach a route the SDK does not wrap, use `client.request()` instead; see [Resource map](./resources.md#the-escape-hatch).

package/docs/sdk/nodes.md

@@ -0,0 +1,193 @@
+# `client.nodes`
+
+Phase 1, 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.
+
+There is one name for it — `client.nodes`. There is no `client.responses` alias. A node has a canvas identity, a kind, a working directory, a profile, a deadline, reports, subscriptions, children, and a lifecycle; naming it `responses` would promise `previous_response_id`, `output_text`, `tools`, and `store` semantics that do not exist here.
+
+## Methods
+
+| Method | Route | Phase | Notes |
+|---|---|---|---|
+| `nodes.create(params)` | `POST /v1/nodes` | 1 | Returns immediately with the node; it is already running. |
+| `nodes.retrieve(id)` | `GET /v1/nodes/{id}` | 1 | |
+| `nodes.list(query?)` | `GET /v1/nodes` | 1 | Returns an array, as the daemon does. |
+| `nodes.outcome(id, { wait })` | `GET /v1/nodes/{id}/outcome?wait=` | 1 | One long poll, `wait` 0–25 s. Returns the wire envelope with `state: 'pending' | 'settled'`. |
+| `nodes.waitForOutcome(id, opts?)` | repeats the above | 1 | Loops until settled. Honours `signal`; no implicit time bound. |
+| `nodes.createAndWait(params, opts?)` | create + wait | 1 | |
+| `nodes.parse(params, opts?)` | create + wait + typed result | 1 | [See below](#parse-and-structured-output). |
+| `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). |
+
+Action methods keep the product's literal name (`fork`, `revive`, `promote`, `yield`) rather than being renamed into a generic verb.
+
+## 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.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `prompt` | `string` | The run's entire brief. |
+| `kind` | `string` | Persona. Omit for the profile's default. |
+| `model` | `string` | Durable model override. |
+| `profile` | `string` | The store, memory, and purview the run uses. An application passes **its own** profile here. |
+| `cwd` | `string` | Where the request came from. |
+| `pin_cwd` | `string` | Pin the node to this directory regardless of `cwd`. |
+| `situational_context` | `string` | Ambient context kept out of the visible prompt. |
+| `deadline` | `string` (`1h30m`) | Wall clock from spawn. Expiry cancels the node and records `deadline_exceeded`. |
+| `output_schema` | `string \| JsonSchema \| { toJSONSchema(): JsonSchema }` | Widened from the wire's JSON string; the SDK serializes. A zod v4 object satisfies the third form. |
+| `root` | `boolean` | No parent, no subscription. An application's run is a root. |
+| `root_lifecycle` | `'terminal' \| 'resident'` | `terminal` for a bounded run; `resident` for one a person will open and keep. |
+| `mode` | `'base' \| 'orchestrator'` | Whether the node works hands-on or fans out to children. |
+| `name` | `string` | Display label. |
+| `description` | `string` | Display description. |
+| `parent` | node id | Graph placement. An external caller leaves this unset. |
+| `creator` | node id | Graph placement. An external caller leaves this unset. |
+| `worktree` | `string \| boolean` | Create a managed git worktree for the run. |
+| `fork_from` | `string` | Start from an existing conversation. |
+| `no_kickoff` | `boolean` | Create the node without sending the first message. |
+| `node_id` | `string` | Spawn at an exact id. A collision answers `409 node_id_exists`. |
+| `prefer_warm` | `boolean` | Serve from the warm pool when the launch tuple matches. |
+| `outcome_delivery` | `{ action, payload? }` | Arm outcome delivery at birth. |
+
+`node_id` is how you make a create safely retryable. Retry with the same id and a duplicate fails loudly with `409 node_id_exists` instead of quietly spawning a second agent — which is why the client never retries a `POST` for you. See [Errors](./errors.md).
+
+## Outcomes
+
+`waitForOutcome`, `createAndWait`, and `parse` return the settled `NodeOutcome` — the same union the API defines, not a translation of it.
+
+| Wire | Narrow on | Carries |
+|---|---|---|
+| `kind: 'result'` | `outcome.kind === 'result'` | `structured_result`, `final_report_path`, and on `parse` a typed `output_parsed` |
+| `kind: 'failure'`, `reason: 'declined'` | `outcome.reason === 'declined'` | `declined: { reason, code, retryable } \| null` — the agent honestly refused the schema |
+| `kind: 'failure'`, any other `reason` | anything else | `detail: NodeOutcomeDetailV1 \| null` — `deadline_exceeded`, a provider fault, a wedge |
+
+**Agent-side outcomes are returned, never thrown.** A decline carries a typed reason, a code the agent chose, and a `retryable` flag; routing that through an exception would discard the payload and make the happy path lie about what happened. Only transport faults, daemon errors, and your own abort throw.
+
+```ts
+const outcome = await client.nodes.waitForOutcome(node.node_id, { signal });
+
+switch (true) {
+  case outcome.kind === 'result':
+    console.log(outcome.structured_result, outcome.final_report_path);
+    break;
+  case outcome.reason === 'declined':
+    console.warn(outcome.declined?.reason, outcome.declined?.retryable);
+    break;
+  default:
+    console.error(outcome.reason, outcome.detail);
+}
+```
+
+### `outcome()` versus `waitForOutcome()`
+
+`nodes.outcome(id, { wait })` is one long poll: the daemon holds the request open for up to `wait` seconds (0–25) and answers `{ node_id, state: 'pending' | 'settled', outcome, node_status, deadline_at }`. `outcome` is `null` while `state` is `'pending'`. Use it when your own loop owns the timing — a job runner that wants to do other work between polls, or a UI that shows a heartbeat.
+
+`nodes.waitForOutcome(id, opts?)` repeats that poll until the node settles. It applies **no implicit time bound**: an agent that runs for an hour is polled for an hour. Bound it from either side — pass a `deadline` to `create` so the daemon cancels the run, or pass a `signal` so your client stops waiting.
+
+```ts
+for (;;) {
+  const poll = await client.nodes.outcome(node.node_id, { wait: 25 });
+  if (poll.state === 'settled' && poll.outcome !== null) {
+    console.log(poll.outcome);
+    break;
+  }
+  // update your UI or job heartbeat here
+}
+```
+
+## `parse()` and structured output
+
+```ts
+import { z } from 'zod';
+
+const run = await client.nodes.parse({
+  prompt: 'Summarize the failing tests in this repo.',
+  cwd: '/path/to/repo',
+  output_schema: z.object({ failures: z.array(z.string()), root_cause: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.root_cause);
+else if (run.reason === 'declined') console.warn(run.declined?.reason);
+```
+
+`ParsedOutcome<T>` is `NodeOutcome & { output_parsed: T | null }`, discriminated so `output_parsed` is non-null exactly when `kind === 'result'`.
+
+`output_parsed` is `structured_result` typed to the schema you passed. A Zod schema uses its inferred output type; a Standard Schema uses `~standard.types.output`. A JSON-Schema literal and any other object with `toJSONSchema()` are accepted and serialized, but their `output_parsed` type is `unknown`. The SDK does not re-validate the result — the daemon already enforces the schema when the agent submits it, so a second validation pass would only produce a second set of error messages for the same rejection. There is no helper equivalent to OpenAI's `zodTextFormat`.
+
+A candidate from Basis's real structured SDK result:
+
+```json
+{
+  "tmp": "k1",
+  "type": "claim",
+  "slug": "config-memories-in-project",
+  "text": "All applet configuration memories belong in project memories.",
+  "quote": "All configuration memories should be in the project memories. We know that.",
+  "speaker": "Me",
+  "confidence": "green"
+}
+```
+
+## Sending a follow-up
+
+`nodes.message(id, body)` appends to a node's inbox. A dormant node wakes to read it; a running node picks it up at its next turn boundary.
+
+```ts
+await client.nodes.message(node.node_id, { body: 'Also check the integration lane.' });
+```
+
+## Stopping a run
+
+| Call | Effect |
+|---|---|
+| `nodes.interrupt(id)` | Stops the current turn. The node stays on the canvas and can be messaged or revived. |
+| `nodes.cancel(id, body?)` | Tears the node down along with the subtree it exclusively owns. Terminal. |
+
+Aborting a `signal` you passed to `waitForOutcome` stops **your client waiting**. It does not stop the node. Call `cancel` for that.
+
+## Nested resources
+
+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.
+
+```ts
+const reports = await client.nodes.reports.list(node.node_id, { limit: 10 });
+for (const report of reports) console.log(report.tier, report.body);
+```
+
+## Pagination
+
+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).

package/docs/sdk/resources.md

@@ -0,0 +1,71 @@
+# 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 |
+
+## Excluded from the typed surface
+
+These `/v1` routes get no SDK method, with the reason. They are still reachable through `client.request()`.
+
+| Routes | Why |
+|---|---|
+| `/v1/focuses…` | A focus maps a node to a tmux pane. An SDK caller has no tmux. It stays on `/v1` for the viewer. |
+| `POST /v1/nodes/{id}/mail/claim`, `…/mail/acknowledge` | These are how a node's own broker takes delivery of its inbox. An external caller claiming another node's mail would consume deliveries that node then never sees. |
+| `POST /v1/nodes/{id}/attach` | Returns the host-local path to a broker's viewer socket. A remote or browser caller cannot open that path, and [Streaming](./streaming.md) is the application-facing way to watch a node. |
+| Broker operations, broker recovery, node faults | The broker's own control plane — session binding, settle directives, park completion, turn recording, provider-retry mutation, fault recording, model commit. They exist so the one process hosting a node can coordinate with crtrd about that node's runtime. An external caller invoking them introduces a second writer to state the broker and the daemon coordinate between themselves. |
+
+## The escape hatch
+
+Nothing on `/v1` is unreachable. A route that is excluded above, or one added to the daemon after this SDK version was published, is reachable directly:
+
+```ts
+client.request(method, path, body?, options?)
+```
+
+It carries the same authentication, the same retry policy, and the same error mapping as every generated method — it is untyped, not unsupported.
+
+```ts
+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.

package/docs/sdk/streaming.md

@@ -0,0 +1,124 @@
+> **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 });
+
+stream.on('node.output_text.delta', (e) => process.stdout.write(e.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
+```
+
+| 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. |
+
+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.
+
+## Events
+
+Each event carries `node_id` and a `sequence_number` in addition to the fields listed.
+
+| Event | `data` |
+|---|---|
+| `node.output_text.delta` | `{ node_id, sequence_number, delta }` |
+| `node.output_text.done` | `{ node_id, sequence_number, text }` |
+| `node.tool_call.started` | `{ node_id, sequence_number, tool_call_id, tool, summary }` |
+| `node.tool_call.completed` | `{ node_id, sequence_number, tool_call_id, tool, status: 'ok' \| 'error', summary }` |
+| `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.settled` | `{ node_id, sequence_number, outcome }` — terminal; the daemon ends the response after it |
+| `error` | `{ error: { code, message, details? } }` — terminal |
+
+`summary` on a tool-call event is a capped rendering of the arguments, never the raw arguments.
+
+**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.
+
+## The route
+
+```
+GET /v1/nodes/{id}/events        Accept: text/event-stream
+    ?after=<sequence_number>     resume from a cursor (optional)
+```
+
+Server-sent events: one record per event as `event: <type>`, `data: <JSON>`, blank line, plus `: keepalive` comment lines every 15 s. Authentication is the daemon's existing rule — filesystem permission on the unix socket, bearer token over TCP.
+
+### What you get depending on the node's state
+
+| Node state when you call | What the stream does |
+|---|---|
+| Already settled | 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.
+
+## 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.
+
+| 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. |
+| 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. |
+| 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
+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
+      }
+      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;
+  }
+}
+```
+
+`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.
+
+## 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.321",
+  "version": "0.3.323",
   "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.321",
+  "version": "0.3.323",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.321",
+      "version": "0.3.323",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,20 +5206,20 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.321",
+      "version": "0.3.323",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.321",
+      "version": "0.3.323",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.321",
+      "version": "0.3.323",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.295"
+        "@north-light/crouter-api": "^0.3.321"
       }
     }
   }

package/scripts/install-runtime.mjs

@@ -166,7 +166,9 @@ async function validatePublished(root, id) {
 }
 
 async function pack(archiveDir) {
-  const output = await run('npm', ['pack', '--json', '--pack-destination', archiveDir], PACKAGE_ROOT, true);
+  // Errors still print; the prepack/postpack banners and notices do not, because
+  // on a fresh install this runs inside the user's first `crtr` command.
+  const output = await run('npm', ['pack', '--json', '--loglevel=error', '--foreground-scripts=false', '--pack-destination', archiveDir], PACKAGE_ROOT, true);
   const packed = JSON.parse(output);
   if (!Array.isArray(packed) || typeof packed[0]?.filename !== 'string') throw new Error('npm pack did not report an archive');
   return join(archiveDir, packed[0].filename);
@@ -416,7 +418,8 @@ async function install() {
     // Humanloop's postinstall only prewarms its external termrender cache; runtime rendering retries lazily with a plaintext fallback.
     const installEnv = { ...process.env };
     delete installEnv.npm_config_allow_scripts;
-    await run('npm', ['ci', '--omit=dev', '--ignore-scripts'], stage, false, installEnv);
+    // stdout is captured and dropped (npm's "added N packages" summary); errors keep stderr.
+    await run('npm', ['ci', '--omit=dev', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'], stage, true, installEnv);
     await patchPiTreeRootOrdering(stage);
     await smokeValidate(stage);
     const pkg = JSON.parse(await readFile(join(stage, 'package.json'), 'utf8'));
@@ -473,7 +476,8 @@ async function install() {
     } catch (error) {
       process.stderr.write(`runtime generation GC skipped: ${error.message}\n`);
     }
-    process.stdout.write(`Installed immutable crouter runtime generation ${id}\n`);
+    // stderr, not stdout: on a fresh install this runs inside the user's first `crtr` command, which may be `--json`.
+    process.stderr.write(`Installed immutable crouter runtime generation ${id}\n`);
     return { generation: id, version: pkg.version, selected };
   } finally {
     if (temporary) await rm(temporary, { force: true });