@north-light/crouter 0.3.320 → 0.3.322

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.320",
+  "version": "0.3.322",
   "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.320",
+  "version": "0.3.322",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.320",
+      "version": "0.3.322",
       "hasInstallScript": true,
       "license": "MIT",
       "workspaces": [
@@ -5206,20 +5206,20 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.320",
+      "version": "0.3.322",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.320",
+      "version": "0.3.322",
       "license": "UNLICENSED"
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.320",
+      "version": "0.3.322",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.295"
+        "@north-light/crouter-api": "^0.3.321"
       }
     }
   }