@north-light/cli 0.0.0-stage → 0.3.413

package/docs/sdk/streaming.md

@@ -0,0 +1,216 @@
+---
+title: Streaming
+description: Follow assistant text, tool activity, reports, and outcomes as an agent runs.
+---
+
+# 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.
+
+## Forwarding a run to a browser
+
+The app server keeps the runtime token and connection; the browser connects only to the app. The app server calls `forwardRunEvents(client, runId, {after: cursorFromRequest(request), signal: request.signal})` and returns the Fetch `Response`. After a host cuts the browser connection, EventSource sends its last SSE id as `Last-Event-ID`; `cursorFromRequest` prefers it over the URL's `after` query parameter.
+
+Every forwarded run event is an unnamed SSE record with its `sequence_number` as `id` and the complete event object as `data`. Receive all event types with one handler:
+
+```ts
+const source = new EventSource(`/api/runs/${runId}/events?after=${cursor}`);
+source.onmessage = ({data}) => {
+  const event = JSON.parse(data);
+  if (event.type === 'stream.refused') { showRefusal(event.error); source.close(); return; }
+  if (event.type === 'stream.reconnecting') { showConnectionFailure(event.error); return; }
+  if (event.type === 'stream.reconnected') { clearConnectionFailure(); return; }
+  if (event.type === 'stream.idle') { source.close(); markIdle(event.cursor); return; } // reopen on your own trigger
+  showRunEvent(event);
+};
+```
+
+The four `stream.*` records are forwarded-stream notices, not daemon run events; they have no `sequence_number` or SSE id.
+
+`stream.idle` (`{type: 'stream.idle', cursor}`) means the runtime closed the stream after 60 s with no running turn and no new event. The helper writes it and then ends the response, so a browser `EventSource` would otherwise reconnect at once and keep a hosted runtime awake indefinitely. Close the `EventSource` on `stream.idle` and reopen it with `after=cursor` on your own trigger: the person sends a message, or your server handles a run notice (see `verifyRunNotice`). A `stream.refused` carries the full error envelope, including `stream_gap`'s `details.latest_sequence` and `details.earliest_sequence`. The helper ends that response after a refusal. The SDK does not recover a gap by skipping missing events.
+
+When the page reloads mid-reply or gets `stream_gap`, the app reads `runs.trace(runId)` through its server and shows each node's `in_progress_message` (`{thinking, text}` or `null`) as that node's open message. The trace's `latest_sequence` is read consistently with its conversations and open messages. Resume `runs.events(runId, {after: trace.latest_sequence})` (or forward with that cursor); do not use a separately read `runs.get` cursor. Continue appending new deltas to the open message, but replace its thinking or text with the complete content repeated by `node.thinking.done` or `node.output_text.done`. This shows the message from its beginning without duplicating content. `runs.get` and every `runs.list` entry expose `latest_sequence` and `last_activity_at`; a cursor equal to `latest_sequence` is not a gap even when older events have expired.
+
+## Following the reply to one message
+
+A chat app sends a message and shows the answer to it. `runs.reply(runId, sent, {signal?})` takes what `runs.message` returned and follows only the turn that delivers that message:
+
+```ts
+const sent = await client.runs.message(runId, 'What did the report say?');
+for await (const event of client.runs.reply(runId, sent)) {
+  if (event.type === 'text.delta') append(event.delta);
+  if (event.type === 'turn.completed' && event.error) showError(event.error); // {code: 'content_refused' | 'model_error', message}
+}
+// or collect it: text as it streams, then the whole text and how the turn ended
+const {text, ended, error, outcome} = await client.runs.reply(runId, sent).collect({onDelta: (delta) => append(delta)});
+// ended: 'completed' | 'error' (error set) | 'waiting_on_user' | 'settled' (outcome set)
+```
+
+It reads `runs.events(runId, {after: sent.sequence_number})`, skips child nodes' events, starts at the root's `node.turn.started` whose `input.message_ids` holds `sent.message_id`, and yields:
+
+| Event | Fields | From |
+|---|---|---|
+| `text.delta` | `delta` | `node.output_text.delta` |
+| `message.done` | `text` (the message's whole text, possibly empty), `stop_reason` | `node.output_text.done`, once per assistant message |
+| `turn.completed` | `run_status`, `stop_reason`, `error?`, `message_ids` | `node.turn.completed`; always last |
+| `run.settled` | `outcome` | `node.settled`, when the run settles before the turn completes; always last |
+
+Every event also carries its `sequence_number`. The reply ends after `turn.completed` or `run.settled` and closes its event stream. A resident run never settles when it goes idle, so a plain `runs.events` stream stays open, but a reply does not. `.text()` consumes the reply and resolves to the text of its `message.done` events joined with a blank line, so a turn that speaks, calls a tool and speaks again returns both texts. `.collect({onDelta?})` consumes the reply too: it passes each streamed piece to `onDelta`, starting a later assistant message's first piece with a blank line, and resolves to `RunReplyResult` `{text, ended, error?, outcome?}`, where `text` is the trimmed messages joined with a blank line. `ended` is `completed` (text may be empty when the model wrote nothing), `error` (the turn's last message failed; `error` says why), `waiting_on_user` (the turn ended on a question to the person), or `settled` (the run settled first; `outcome` says how). `.text({onDelta?})` is `collect`'s `text`. A reply can be consumed once.
+
+Several messages delivered in one turn, including a `start_turn: false` message that joined it, all resolve to that turn. To have a reply to the run's first message, pass it as `runs.start({prompt, message})` and follow `runs.reply(run.run_id, run.message!)`: a message stored with the run always joins the first turn. A refused or failed model call ends the turn with an empty `message.done` (`stop_reason: 'error'`) and `turn.completed.error`; the run stays usable, and `runs.get` shows the same error as `last_turn_error` until a later turn completes without one. A provider failure the runtime retries on its own (connection, rate limit, overloaded) does not end the reply: the recovery attempt continues the same turn, so the reply yields its answer and one `turn.completed` without an error, and only a turn whose retries run out ends with `model_error`. An interrupt, `runs.cancel`, or a closed node ends the turn with `stop_reason: 'aborted'` and no error. An expired cursor throws `APIError` with code `stream_gap`; aborting `signal` rejects with `APIUserAbortError`.
+
+## A quiet run: `event: idle`
+
+A runtime that sleeps when nothing holds a connection to it ends a run's SSE stream after 60 s in which the run has no running turn and no new event: it sends `event: idle` (`data: {}`) and closes. `RunStream` reports that and does not reconnect:
+
+```ts
+const stream = client.runs.events(runId, {after: cursor});
+for await (const event of stream) handle(event);
+const end = await stream.whenEnded(); // rejects on a transport failure or abort()
+if (end.reason === 'idle') {
+  // the run is quiet and nothing was missed; reopen later with client.runs.events(runId, {after: end.cursor})
+}
+```
+
+`stream.idle` and `stream.position` read the same facts synchronously. A settled run ends with `reason: 'settled'`; a transport error rejects as before. `runs.reply` reopens through an idle close on its own.
+
+## Typed run events
+
+`RunEvent`, exported by the SDK, is the union of every run event, discriminated on `type`. Its types are exactly the daemon's run event vocabulary, declared once. `RunEventOf<'node.turn.completed'>` picks one event, and `RunStream.on(type, listener)` passes the listener that event. An event type a newer daemon adds and this SDK does not declare is still delivered as-is.
+
+## The SDK surface
+
+```ts
+const stream = client.nodes.stream({ prompt: 'Fix the failing test', cwd }, { headers: { 'x-trace': 'run-9' } });
+
+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
+```
+
+| Member | Behaviour |
+|---|---|
+| `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/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
+
+Every event except `error` carries `node_id` and `sequence_number` in addition to the fields listed. `error` carries only its error object.
+
+| 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 }`, 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: '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 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.
+
+## 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 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 outcome.
+
+## Sequence, resume, and failure
+
+`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 | 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 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
+
+```ts
+import { APIError } from '@north-light/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') {
+        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 (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.

package/docs/sdk/testing.md

@@ -0,0 +1,163 @@
+---
+title: Testing your app
+description: FakeCloud from @north-light/sdk/testing — a fake directory and runtime your real OAuth2Client and Crouter talk to through fetch.
+---
+
+# Testing your app
+
+`@north-light/sdk/testing` exports `FakeCloud`, a fake crouter cloud: the directory (discovery, token refresh, JWKS) and each person's runtime (grant, runs, memory, providers, run notices). It answers through `fetch`. Your app's production path — `new OAuth2Client(...)`, `oauth.client(userId)`, `runs`, `memory`, `grant`, `providers`, `watchRuns`, `watchGrants`, `onRefusal`, `forwardRunEvents`, `verifyRunNotice` — runs against it unchanged. The only differences from production are the `fetch` and `issuer` you pass in.
+
+There is no mock `Crouter`. An object typed as `Crouter` would re-implement `RunReply`, `RunStream`, the watchers, retries and error mapping, so your tests would check a copy of the SDK instead of the SDK. FakeCloud fakes only the wire, so every SDK behaviour under test is the one you ship.
+
+The subpath is Node-only (it uses `node:crypto`), adds no dependency, and imports no test framework: it works with `node:test`, vitest, jest or anything else. Nothing listens on a port.
+
+## Setup
+
+```ts
+import { OAuth2Client, MemoryConnectionStore } from '@north-light/sdk';
+import { FakeCloud } from '@north-light/sdk/testing';
+
+const cloud = new FakeCloud({ clientId: 'doppel' });
+const store = new MemoryConnectionStore();                   // or your own ConnectionStore
+await cloud.connect(store, 'user:o1', { scopes: ['crtr:llm', 'crtr:act', 'sms:send'] });
+
+const oauth = new OAuth2Client({
+  clientId: 'doppel', issuer: cloud.issuer, fetch: cloud.fetch,
+  privateKey, redirectUri: 'https://app.test/callback', store,
+});
+const client = await oauth.client('user:o1');               // first call refreshes through the fake directory
+```
+
+`cloud.connect(store, userId, {scopes?, dependencies?})` makes the person's grant active (default scopes `crtr:llm`, `crtr:act`) and saves a `Connection` in your store with its access token already expired, so the first call refreshes through the directory exactly as in production.
+
+`cloud.crouter(userId)` returns a real `Crouter` on that person's runtime with a fresh token and no refresh. Refusals and refreshes never reach it. Use it only for code whose production signature takes a `Crouter`. Code that goes through `OAuth2Client` in production should go through `oauth.client` in tests too.
+
+Options: `new FakeCloud({clientId, issuer = 'https://directory.test', runtimeUrl = 'https://runtime.test' (or (userId) => url), runtimeId = 'runtime:test', runtimeClientId = 'runtime-client', runtimeVersion?, streamIdleMs = 60000, accountAppUriTemplate = '<issuer>/account/apps/{client_id}' (null omits it), runNotice?, isolatedRuns = 'available'})`.
+
+### Isolated runs
+
+The fake stands in for a crouter cloud guest, where the Linux root launcher always exists, so `runs.start({isolated: true})` starts a run by default and `run.params.isolated` is `true`. The checks `startRun` makes without the launcher are mirrored: `isolated` must be a boolean, `cwd` is accepted only with `isolated: true` and must be an absolute path inside the run's root folder, `/apps/<clientId>/nodes/<run id>` (else 400 `invalid_request`, `param: cwd`), and `worktree` is refused. Nothing in the fake enforces the sandbox itself (no network, no `files/` mount).
+
+`isolatedRuns: 'unavailable'` models a runtime without the launcher, such as a local daemon on a Mac: every isolated start answers 503 `isolated_unavailable` (`param: isolated`, retryable, so `runs.start` sends it three times before throwing). Use it to test your app's handling of that refusal.
+
+## Driving runs
+
+Nothing in the fake runs a model. A run stays `running` until your test drives it, either directly or through a responder:
+
+```ts
+cloud.runs.respond(({ run }) => run.reply(`echo: ${run.pending.at(-1)?.text ?? run.params.prompt}`));  // every user
+cloud.user('user:o1').runs.respond(null);                                          // per-user override
+```
+
+A responder gets `{run, kind: 'start' | 'message', messages}`. It is called after the fake answers a `run.start`, or a `run.message` with `start_turn` true, and never for an idempotent replay. A responder that throws is recorded in `cloud.responderErrors` and fails nothing else. An `async` responder can await your app's state mid-reply.
+
+`cloud.runs` and `cloud.user(id).runs` have one shape, `{all: FakeRun[], respond(fn)}`: `all` lists the runs in start order (a deleted run stays, with `deleted` set), so `expect(user.runs.all).toEqual([])` works. Each entry is a `FakeRun`:
+
+| Method | Effect |
+|---|---|
+| `reply(text, {chunks = 2, messageIds?})` | One turn: `node.turn.started`, text deltas, `node.output_text.done`, `node.turn.completed`. Delivers `messageIds` (default: every pending message). The run goes `idle` (`waiting_on_user` with an open question). |
+| `failTurn({code: 'model_error' \| 'content_refused', message})` | The same turn ending `stop_reason: 'error'`; `runs.get` shows `last_turn_error`; `runs.reply(...).collect()` ends `error`. |
+| `setActivity(activity, {at?})` | Fake-only: status `running` with this `activity` until the next event. The only way to reach `writing` or a streaming tool call. |
+| `settle(ending)` | `{result}`, `{declined: {reason, code, retryable}}`, `{failure: 'canceled' \| 'deadline_exceeded'}`, or `{runtimeError: reason}`. Emits `node.settled` with the outcome the runtime writes. |
+| `idle()` | Goes idle without a new turn (stopped without submitting). |
+| `ask({title, slots?})` | Opens a question (`waiting_on_user`); returns its id. Your app's `questions.answer` records the answer. |
+| `delete()` | As if the runtime deleted it: reads 404, streams close, its idempotency keys are dropped. |
+| `emit(type, fields, {nodeId?})` | Appends any run event; another `nodeId` is a child node's event. Status and activity re-derive from the log. |
+| `closeIdle()`, `expireEvents(upTo)` | Idle-close open streams now; drop old events so `stream_gap` is reachable. |
+
+Read-only members: `id`, `userId`, `params` (the `run.start` body, `isolated` and `cwd` included), `idempotencyKey`, `messages`, `pending`, `status`, `activity`, `outcome`, `result`, `lastTurnError`, `events`.
+
+What a turn's input is: `reply` and `failTurn` deliver `messageIds` (default: every pending message), and the turn's `node.turn.started` input text is those messages' text. A turn that delivers none (`messageIds: []`, or nothing pending) uses the run's `prompt` as its input on the run's first turn only, and an empty input after that; it still emits a full root turn with the text you pass. So `reply('', {messageIds: []})` is not a turn that answers nothing. To script a child node that works and answers nothing, or any event outside a root turn, use `emit(type, fields, {nodeId: 'child-1'})`: for example `run.emit('node.turn.started', {input: {text: 'x', message_ids: []}, entry_id: 'c1'}, {nodeId: 'child-1'})` followed by `node.turn.completed` with the same `nodeId`. Events with another `nodeId` never complete the app's `runs.reply`, which waits for the root's turn.
+
+Messages follow the runtime: `start_turn` true makes the run `running` at once and calls the responder; `start_turn` false only records it. A message to a run settled `canceled` or `deadline_exceeded` is refused 409 `run_settled`; to a run settled any other way it reopens the run. A deleted run answers 404.
+
+Idempotency follows the runtime too: the same `Idempotency-Key` with the same body replays the first answer (no new run, no responder call); the same key with a different body, or reused between `run.start` and `run.message`, is 409 `idempotency_conflict`. After a run is deleted, its start key creates a new run.
+
+## Grants and setup state
+
+`cloud.user(id).grant`: `state` (the `GrantGetDTO`, or null), `set({dependencies?, resolved_scopes?, spend_cap?})` (a new `rev`), `setup(provider, state, {message?})` (a dependency change without a `rev` bump), `sync()` (unchanged content: no version change, no wake), `revoke(code = 'grant_revoked')`, `restore(patch?)`.
+
+`grant.get` with `wait` and `since` is held until the version changes, exactly as the runtime holds it, so `oauth.watchGrants` works unmodified. `user.reads` lists the person's `grant.get` calls and `user.holding` counts reads held now.
+
+## Refusals
+
+- `user.refuse(code)` leaves the grant alone: the directory refuses each refresh with `code` (`grant_removed`, `grant_suspended`, `refresh_token_expired`, `refresh_token_reused`, `grant_revoked`), and tokens issued before the call get 401, so the next call refreshes and is refused. `refuse('ok')` clears it.
+- `grant.revoke('grant_removed')` deactivates the grant: calls answer 401 `grant_revoked`, held reads wake to it, open streams get an error frame, and the next refresh is refused with that code.
+- `user.expireTokens()` forces a refresh without a refusal.
+
+The real `OAuth2Client` handles all of it: your `onRefusal` runs with the refusal, the stored connection is removed, and the thrown error has `refusalOf(e)` set. `await cloud.refusalError(code)` returns that exact error for unit tests that need the value.
+
+## Memory and providers
+
+`user.memory.put({name, body, privacy = 'public', kind = 'knowledge', ...})` and `remove(name)`. Without `crtr:memory:manage:user` in the grant, only `public` documents are listed and others read as 404, as on the runtime. List items carry the full `MemoryListItem` fields.
+
+```ts
+cloud.providers.define('sms', { tools: { send: { group: 'send', handler: ({ userId, arguments: args }) => ({ sent: true }) } } });
+```
+
+A call is checked against the grant's `<provider>:<group>` scope (403 `scope_missing`). A handler that throws `FakeCloud.error({...})` answers that envelope; any other throw is 502 `provider_error`. `status: 'install_failed'` lists the provider with its `error` and answers calls 503 `provider_unavailable`.
+
+## Failures, gates and the directory
+
+`intercept(op, fn, {user?, times?})` runs `fn` before an operation; it may await, act, or return an answer. `failNext(op, answer, {user?, times = 1})` is the shorthand. `gate(op)` holds every matching request until you call the `release()` it returns. `op` is a runtime operation name (`run.start`, `grant.get`, `memory.list`, …), `'*'` for every runtime operation, or `directory.discovery`, `directory.token`, `directory.jwks`.
+
+| Answer | Runtime operation | `directory.discovery` | `directory.token` | `directory.jwks` |
+|---|---|---|---|---|
+| `'unreachable'` | fetch rejects; the SDK throws `APIConnectionError` | fetch rejects | fetch rejects; no `onRefusal` | fetch rejects; `verifyRunNotice` throws `RunNoticeError` |
+| a status number | that status with a runtime envelope | that status; discovery fails | that status; an `InternalServerError` for 5xx coded `invalid_request`, origin `directory`; connection kept | that status |
+| `FakeCloud.error({status, code, message?, origin?, retryable?, details?, param?})` | that envelope | not allowed | not allowed (use `user.refuse`) | not allowed |
+
+Retries are the SDK's, so a scripted failure the SDK retries is absorbed unless `times` covers every attempt. One SDK call makes these attempts (`maxRetries` defaults to 2; a call's `maxRetries` option changes it):
+
+| What the fake answers | Operations | SDK behaviour | `times` to surface it |
+|---|---|---|---|
+| 401 (any code) | every runtime operation called through `oauth.client` | refreshes the token once, then repeats the call once | 2 |
+| a status number ≥ 500, or 429 | GET and DELETE operations: `grant.get`, `run.get`, `run.list`, `run.delete`, `trace.get`, `question.get`, `memory.list`, `memory.get`, `provider.tools`, `profile.list` | retried `maxRetries` times with backoff (250 ms, 500 ms) | 3 |
+| `'unreachable'` | the same GET and DELETE operations | retried `maxRetries` times | 3 |
+| `FakeCloud.error({..., retryable: true})` (the default for a 503), or `'unreachable'` | `run.start`, `run.message` (keyed sends) | resent with the same `Idempotency-Key` `maxRetries` times, waiting 500 ms, 1 s (or the envelope's `retry_after_s`) | 3 |
+| a status number, or an envelope with `retryable: false` | `run.start`, `run.message` | not retried (a status number answers `retryable: false`) | 1 |
+| anything else | the other POSTs: `run.interrupt`, `run.cancel`, `run.rename`, `question.answer`, `provider.call` | never retried | 1 |
+| anything | `run.events` (the SDK's `RunStream`) | a retryable error reconnects from the cursor with backoff; a non-retryable one, `stream_error` or `stream_dropped`, ends the stream | `Infinity` for a retryable one |
+
+The rows compose: one 401 followed by three 500s on `grant.get` surfaces the 500 (the call repeated after the refresh has its own two retries), so a 401 surfaces only when the repeat gets one too. A test that wants an operation to fail no matter what scripts `times: Infinity` and removes it afterwards with `intercept`'s returned function, or calls `cloud.reset()`.
+
+Discovery is memoized per `OAuth2Client`. A test that fails discovery should use a fresh `FakeCloud` and `OAuth2Client`.
+
+A runtime outage on an ordinary call: `user.expireTokens(); cloud.failNext('directory.token', 503, {user})`. An unreachable runtime: `cloud.failNext('*', 'unreachable', {user, times: Infinity})`. With `runtimeVersion` older than the SDK's minimum, calls fail with `RuntimeVersionError` (426).
+
+## Run notices and forwarding
+
+```ts
+const cloud = new FakeCloud({ clientId: 'chat', runNotice: { url: 'https://app.test/run-notices', deliver: (request) => app.handleNotice(request) } });
+```
+
+The fake sends notices by the runtime's rules: one is owed when an event is appended with no `run.events` stream open, or when the last stream closes with events unread; a burst coalesces into one; up to three attempts; a 401 re-mints the token once; a 5xx, a thrown `deliver`, or no answer within 10 s is retried; any other status ends the send. A run whose person has no active grant is owed nothing. The waits default to 0 so tests stay fast. Pass the runtime's values (`retryWaitsMs: [3000, 5000]`, `ackGapMs: 5000`, `failGapMs: 60000`) to test timing. Every attempt is recorded in `cloud.notices`.
+
+In your route, pass the cloud's `fetch` to `verifyRunNotice`:
+
+```ts
+await verifyRunNotice(request, { runNoticeUrl, issuer: cloud.issuer, grantee: 'app:chat', fetch: cloud.fetch });
+```
+
+Keys are cached per `(issuer, fetch)`, and each cloud has its own signing key, so several clouds on one issuer verify independently. `forwardRunEvents` needs nothing special: it reads the fake's event stream, idle close included (`streamIdleMs`).
+
+## Two app processes
+
+Build two app instances (two `OAuth2Client`s) on the same `cloud`. They see the same runs, grants and held reads. If they keep separate stores, the second refresh with a superseded token is refused `refresh_token_reused`, as it would be in production; a shared store with `lock` prevents it.
+
+## Asserting
+
+- `cloud.calls`: every runtime request as `{userId, op, runId, questionId, method, path, query, body, idempotencyKey, status, at}`.
+  - `userId` is the bearer token's `sub` whenever it names a person this cloud knows (created by `connect` or `user(id)`), whatever their grant or refresh-token state, so a call refused 401 still carries it. It is `null` only for a missing or undecodable bearer, or a `sub` the cloud has never seen.
+  - `runId` is the run the call addresses: the path's id for `run.get`, `run.message`, `run.events`, `run.interrupt`, `run.cancel`, `run.delete`, `run.rename` and `trace.get` (as sent, even when no such run exists), and for `question.get` and `question.answer` the run holding the question (null when none of the caller's runs does). `questionId` is the path's id on the two question operations. Both are `null` on every other operation.
+  - `body` is a parsed copy for your assertions; mutating it from an intercept is not a supported way to change what the fake handles.
+- `cloud.directoryCalls` and `cloud.refreshes`: directory requests, with `answer` (`ok`, a refusal code, a status or `unreachable`).
+- `run.params`, `run.messages`, `run.idempotencyKey`: what your app sent.
+- `cloud.notices`: every notice attempt, with its decoded token claims and your route's status.
+- `cloud.reset()` clears runs, calls, intercepts, responders, memory, idempotency keys and notices, and keeps grants and refresh tokens so stored connections stay valid.
+
+## Fidelity
+
+FakeCloud is checked against the real runtime on every crouter release: one set of conformance scenarios runs on the fake and on the real app listener (run start and idempotency, messages, reply streams, long-poll, every settle outcome, delete, the event stream's edges, grant holds, memory, providers, run notices). Two behaviours are fake-only because the runtime cannot be scripted that way: a successful provider call (the real side needs an installed provider), and `setActivity`. An isolated run that starts is checked only against `startRun`'s documented checks: the real listener in the suite runs without the Linux root launcher, so on it the `isolatedRuns: 'unavailable'` refusal is what is conformance-checked.
+
+Not faked: sign-in (`authorizeUrl`, `exchangeCode`, ID tokens — start from `cloud.connect`), token revocation, the owner and local-daemon surface (`nodes`, `canvas`, `crons`, `files`, …), and several apps on one cloud. `trace.get`, `run.rename`, `run.interrupt` and `profile.list` answer the right shape only.

package/package.json

@@ -1,6 +1,162 @@
 {
   "name": "@north-light/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.413",
+  "description": "crtr — agent runtime with memory, plugins, and marketplaces",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "workspaces": [
+    "packages/*",
+    "apps/*"
+  ],
+  "bin": {
+    "crtr": "bin/crtr",
+    "crouter": "bin/crouter",
+    "crtrd": "bin/crtrd",
+    "crtr-launcher": "bin/crtr-launcher"
+  },
+  "imports": {
+    "#api/*": {
+      "crtr-src": "./src/api/*.ts",
+      "default": "./dist/api/*.js"
+    },
+    "#clients/*": {
+      "crtr-src": "./src/clients/*.ts",
+      "default": "./dist/clients/*.js"
+    },
+    "#commands/*": {
+      "crtr-src": "./src/commands/*.ts",
+      "default": "./dist/commands/*.js"
+    },
+    "#core/*": {
+      "crtr-src": "./src/core/*.ts",
+      "default": "./dist/core/*.js"
+    },
+    "#daemon/*": {
+      "crtr-src": "./src/daemon/*.ts",
+      "default": "./dist/daemon/*.js"
+    },
+    "#pi-extensions/*": {
+      "crtr-src": "./src/pi-extensions/*.ts",
+      "default": "./dist/pi-extensions/*.js"
+    },
+    "#prompts/*": {
+      "crtr-src": "./src/prompts/*.ts",
+      "default": "./dist/prompts/*.js"
+    },
+    "#types": {
+      "crtr-src": "./src/types.ts",
+      "default": "./dist/types.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    },
+    "./api": {
+      "import": "./dist/api/index.js",
+      "types": "./dist/api/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/__tests__/**",
+    "bin",
+    "docs",
+    "scripts/postinstall.mjs",
+    "scripts/patch-pi-tree-root-ordering.mjs",
+    "scripts/install-runtime.mjs",
+    "scripts/lib/isolation-env.mjs",
+    "scripts/lib/pack-args.mjs",
+    "scripts/lib/update-target.mjs",
+    "scripts/lib/runtime-deps-key.mjs",
+    "scripts/runtime-smoke.mjs",
+    "scripts/build-native-linux.mjs",
+    "scripts/ensure-native-linux.mjs",
+    "src/native/linux/addon.c",
+    "packages/crouter-identity/package.json",
+    "packages/crouter-identity/dist",
+    "!packages/crouter-identity/dist/**/__tests__/**",
+    "scripts/pack-minify.mjs",
+    "scripts/runtime-lock.mjs",
+    "scripts/self-update.mjs",
+    "runtime.lock.json"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "build:native:linux": "node scripts/build-native-linux.mjs",
+    "activate": "npm run build && npm run install-runtime && crtr sys daemon restart",
+    "activate:pull": "git pull && npm install && npm run activate",
+    "build:api": "tsc -p packages/crouter-api/tsconfig.json",
+    "build:env-docker": "tsc -p packages/crouter-env-docker/tsconfig.json",
+    "build:sdk": "npm run build:api && npm run build:identity && tsc -p packages/crouter-sdk/tsconfig.json",
+    "build:plugin": "tsc -p packages/crouter-plugin/tsconfig.json",
+    "typecheck:pi-packages": "npx tsc -p src/builtin-pi-packages/pi-crtr-extensions/tsconfig.json",
+    "test:runtime-packaging": "node --test scripts/runtime-smoke.test.mjs scripts/pack-args.test.mjs scripts/ensure-native-linux.test.mjs scripts/release-version.test.mjs",
+    "test:build-output": "node scripts/build-concurrency-test.mjs",
+    "check:cli-no-canvas": "node scripts/check-cli-no-canvas.mjs",
+    "check:cli-cold-start": "node scripts/check-cli-cold-start.mjs",
+    "check:cli-leaf-load": "node scripts/check-cli-leaf-load.mjs",
+    "check:daemon-no-barrel": "node scripts/check-daemon-no-barrel.mjs",
+    "check:quote-style": "node scripts/check-quote-style.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "install-runtime": "node scripts/install-runtime.mjs",
+    "prepack": "node scripts/runtime-lock.mjs prepack && node scripts/pack-minify.mjs prepack && node scripts/ensure-native-linux.mjs prepack",
+    "postpack": "node scripts/pack-minify.mjs postpack && node scripts/runtime-lock.mjs postpack",
+    "dev": "tsx --conditions=crtr-src src/cli.ts",
+    "link": "npm link",
+    "prepublishOnly": "npm run build",
+    "test": "CRTR_NO_DAEMON_AUTOSTART=1 node --conditions=crtr-src --import tsx/esm --import ./scripts/test-env-scrub.mjs --test --test-concurrency=$(node -p 'Math.max(4, require(`node:os`).availableParallelism() - 1)') --test-timeout=10000 ${CRTR_TEST_SHARD:+--test-shard=$CRTR_TEST_SHARD} 'src/**/__tests__/*.test.ts'",
+    "test:integration": "npm run build:api && CRTR_NO_DAEMON_AUTOSTART=1 node --conditions=crtr-src --import tsx/esm --import ./scripts/test-env-scrub.mjs --test --test-concurrency=$(node -p 'Math.min(8, Math.max(2, require(`node:os`).availableParallelism() - 1))') --test-timeout=60000 ${CRTR_TEST_SHARD:+--test-shard=$CRTR_TEST_SHARD} 'src/**/__tests__/integration/*.test.ts' 'packages/crouter-sdk/src/**/__tests__/integration/*.test.ts' 'packages/crouter-plugin/src/**/__tests__/integration/*.test.ts'",
+    "test:seam": "npm run build && npm run test:seam:built",
+    "test:sdk": "npm run build:api && npm run build:identity && node --conditions=crtr-src --import tsx/esm --test --test-timeout=60000 'packages/crouter-sdk/src/__tests__/*.test.ts' 'packages/crouter-sdk/src/__tests__/integration/*.test.ts'",
+    "test:sdk:pg": "node -e \"if (!process.env.TEST_DATABASE_URL) { console.error('test:sdk:pg needs TEST_DATABASE_URL (a disposable PostgreSQL), e.g. docker run --rm -d -e POSTGRES_PASSWORD=pw -p 127.0.0.1:55432:5432 postgres:18-alpine; TEST_DATABASE_URL=postgres://postgres:pw@127.0.0.1:55432/postgres'); process.exit(1) }\" && node --conditions=crtr-src --import tsx/esm --test --test-timeout=60000 'packages/crouter-sdk/src/**/__tests__/**/*.pg.test.ts'",
+    "test:seam:built": "CRTR_NO_DAEMON_AUTOSTART=1 node --import ./scripts/test-env-scrub.mjs --test --test-concurrency=$(node -p 'Math.min(4, Math.max(2, require(`node:os`).availableParallelism() - 2))') --test-timeout=180000 ${CRTR_TEST_SHARD:+--test-shard=$CRTR_TEST_SHARD} 'dist/**/__tests__/seam/*.test.js'",
+    "test:all": "npm test && npm run test:integration && npm run test:seam",
+    "test:isolated": "node scripts/test-isolated.mjs",
+    "build:identity": "tsc -p packages/crouter-identity/tsconfig.json"
+  },
+  "overrides": {
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-agent-core": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Northlight-Systems/crouter.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@north-light/identity": "0.3.413",
+    "@earendil-works/pi-agent-core": "0.99.1",
+    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-coding-agent": "0.99.1",
+    "@earendil-works/pi-tui": "0.99.1",
+    "cron-parser": "^5.6.0",
+    "esbuild": "^0.27.7",
+    "jose": "^6.2.12",
+    "proper-lockfile": "4.1.2",
+    "string-width": "^7.0.0",
+    "tar": "^7.5.22",
+    "typescript": "^5.7.0",
+    "undici": "8.10.2",
+    "ws": "^8.21.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/pg": "^8.23.1",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/ws": "^8.18.1",
+    "pg": "^8.23.1",
+    "tsx": "^4.0.0"
+  }
+}