@north-light/cli 0.0.0-stage → 0.3.413

package/dist/builtin-memory/crouter-sdk/release-notes.md

@@ -0,0 +1,209 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Release notes, this knowledge should be read
+  because Behavior changes in @north-light/sdk that an app must act on, newest
+  first.
+---
+
+# Release notes
+
+Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
+
+## 0.3.409
+
+### `@north-light/sdk/testing`: isolated runs start, `FakeCall.runId`, one `runs` shape (one breaking change)
+
+- `runs.start({isolated: true})` now starts a run on `FakeCloud`, as it does on a crouter cloud guest; it used to answer 503 `isolated_unavailable`. `run.params.isolated` records it, and a `cwd` outside the run's root folder is 400 `param: cwd`, as the runtime checks it. The new option `isolatedRuns: 'unavailable'` restores the 503 for testing that path. If you worked around the refusal by deleting `body.isolated` in an intercept, remove the intercept.
+- `FakeCall` gains `runId` and `questionId` (the ids the path addresses, else `null`), so tests no longer split `path`.
+- `FakeCall.userId` is now the bearer's person whenever the cloud knows them, including a person with no refresh token; it is `null` only for a missing or unknown bearer.
+- **Breaking:** `cloud.user(id).runs` is now `{all, respond}`, the same shape as `cloud.runs`, instead of an array carrying `respond`. Replace `user.runs[i]`, `user.runs.find(...)` and `[...user.runs]` with `user.runs.all…`.
+- `testing.md` documents every SDK retry that absorbs a `failNext` answer (401: `times: 2`; 5xx or 429 on GET and DELETE: `times: 3`; a retryable answer on `run.start` or `run.message`: `times: 3`), and how to script a child turn that answers nothing.
+
+## 0.3.408
+
+### `@north-light/sdk/testing` (additive)
+
+New `@north-light/sdk/testing`: `FakeCloud`, a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch`. It covers runs (events, replies, long-poll, idempotency, endings), grant watch, refusals, directory failures, memory, providers and run notices, and is checked against the real runtime on every release. Additive: `verifyRunNotice` accepts `fetch`. No behaviour change. See [[crouter-sdk/testing]].
+
+### `oauth.accountAppUrl()` (additive), and a failed discovery read is retried (behaviour fix)
+
+- New `OAuth2Client.accountAppUrl()` returns the app's page on the signed-in person's crouter cloud account, as the directory's discovery document advertises it (`account_app_uri_template`). Use it instead of building `<issuer>/account/apps/<client id>` yourself. It needs no user or connection and throws `CrouterError` naming the fault when the directory advertises no template or an invalid one. See [[crouter-sdk/client]].
+- **Behaviour fix:** `OAuth2Client`'s discovery read now times out after 10 seconds, and a read that failed or timed out is retried by the next call that needs it. Before, one failed read was kept for the client's life, so every later `authorizeUrl`, `exchangeCode`, refresh and `verifyIdToken` failed until the process restarted, and a hung directory stalled them indefinitely. A successful read is still kept for the client's life.
+
+## 0.3.405
+
+### Run notices, and `forwardRunEvents` stops on idle (additive; one behavior change)
+
+A hosted runtime that sleeps cannot be polled, so it tells your app when a run has output nobody is reading.
+
+- An app whose directory registration has a `run_notice_url` receives `POST <run_notice_url>` with `Authorization: Bearer <directory token>` and body `{run_id, latest_sequence}`, sent when events are appended to one of its runs and no `run.events` stream is open (or a stream ended with events unread). A notice carries no content and never keeps the runtime awake; if it cannot be delivered after three quick attempts the runtime logs `run_notice.failed` and drops it. A lost notice delays output until your app next reads from its cursor; it never loses output.
+- New `verifyRunNotice(request, {runNoticeUrl, issuer, grantee})` checks the token (signature, `iss`, `aud` = `runNoticeUrl`, `exp`, scope `crtr:run_notice`, `grantee`) and the body, and returns `{userId, runtime, runId, latestSequence}`. `runtime` comes from the token's `act.sub`, never the body. Any failure throws `RunNoticeError` (`status` 401): answer 401 and store nothing. Answer 2xx once the notice is stored; the same or a lower `latest_sequence` is a no-op.
+- **Behavior change:** when the runtime idle-closes the stream, `forwardRunEvents` now writes `data: {"type":"stream.idle","cursor":N}` and ends the response, instead of reconnecting. Browser code should close its `EventSource` on `stream.idle` and reopen with `after=cursor` on its own trigger (a send, or your notice handling).
+
+## 0.3.404
+
+### `crons.create` refuses or defaults a `cwd` the run cannot start in (additive, not breaking)
+
+In a hosted runtime every cron run is sandboxed and sees only the app's own folders, so a cron armed with any other `cwd` (the CLI's inherited `/`, for one) was accepted and then failed at every fire with `cwd is not mounted`.
+
+- `cwd` is now optional on `crons.create`. Omitted, it becomes the creating node's directory when the run can reach it, else the app's files directory.
+- New optional `cwd_is_default: true` marks a `cwd` you did not choose (a shell's current directory); an unreachable one is replaced by the same default instead of refused.
+- A `cwd` you chose that the run cannot reach is refused at create time with 400 `invalid_request` (`param: "cwd"`); nothing is stored. Pass a directory under the app's folders.
+- A runtime that does not sandbox cron runs (a local daemon on macOS) is unchanged. `cron.cwd` on the returned row is the directory the cron actually got.
+
+## 0.3.402
+
+### `RunStream` surfaces the runtime's idle close (additive, not breaking)
+
+A `run.events` SSE stream that ends with `event: idle` (0.3.401) used to look like any other close: `RunStream` dropped the frame and reconnected after 500 ms, which keeps a hosted runtime awake. Now the frame ends the stream and is reported, and the stream does not reconnect.
+
+- `stream.idle` is `true` once the runtime sent `event: idle` and closed. Iteration ends normally (no throw); `finalOutcome()` is not resolved, because the run did not settle.
+- `stream.position` is the `sequence_number` of the last event delivered (the `after` you passed until one arrives). Reopen with `runs.events(runId, {after: stream.position})` when you want to read again.
+- `stream.whenEnded()` resolves `{reason: 'settled' | 'idle', cursor}` (new export `RunStreamEnd`) and rejects with the failure or `APIUserAbortError`, so "idle", "run ended" and "transport error" are three distinct outcomes.
+- `runs.reply(...)` keeps waiting for its turn: it reopens from the cursor after an idle close, so a reply still ends on `turn.completed` or `run.settled`.
+- Nothing else changes: any close without the idle frame reconnects as before, and a consumer that ignores `idle` sees the iteration end where it used to see a reconnect. The frame is not a run event and is not delivered to `on(...)` listeners. `forwardRunEvents` still holds the browser's response through an idle close, reconnecting as before; use `runs.events` directly to let a hosted runtime sleep.
+
+## 0.3.401
+
+### Runtime sleep and wake support (additive, not breaking)
+
+The runtime gains what a sandbox that sleeps needs; no app-facing type or route an app calls changes, and no SDK pin has to move.
+
+- `GET /v1/due` (owner API, unix socket) returns `{busy, next_due_at}`: whether any node is mid-turn, a cron or bash job is running or any timed lane has work due now, and the earliest time any timed lane owes work. Every lane the daemon tick runs registers a due source or is declared busy-only; a test fails when a new lane does neither.
+- A `run.events` SSE stream now ends with `event: idle` (`data: {}`) and closes after 60 s in which the run has no running turn and no new event. The SDK's `RunStream` at this release still reconnects from its cursor as after any close; the next release surfaces the frame (see above).
+- A request carrying `Crtr-Defer-Head: 1` on the app listener whose response head is not ready 40 s after arrival gets `200 application/vnd.crtr.deferred-head`, then `crtr-deferred-head/1\n`, a `\n` every 15 s, one JSON line `{"status","headers"}`, and the real body unchanged. Requests without the header behave as before.
+- The daemon pulls grants on every detected resume (wall clock jumping over 2 s beyond the monotonic clock).
+
+## 0.3.400
+
+### Follow a person's grant with `oauth.watchGrants` (additive)
+
+`grant.get()` answers a new field, `version`: opaque, it changes exactly when `rev`, `resolved_scopes`, `spend_cap`, `payer` or `dependencies` changes. `grant.get({wait, since})` (`wait` an integer 1–25; anything else throws `RangeError` before sending) holds the read until the grant's `version` differs from `since` or `wait` seconds pass, and extends the request timeout by `wait`. A grant revoked or removed during the hold answers 401 `grant_revoked`. `oauth.watchGrants({users, onChanged, onError?, sweepMs?, concurrency?, wait?})` returns a `GrantWatcher` that follows the grants of the people `users()` names and calls `onChanged({userId, grant, previous})` level-triggered, at least once per version, so an app learns when a required provider's setup turns `ready` without a browser tab or a poll loop. New exports `GrantWatcher`, `GrantWatchOptions`, `GrantChanged`. Not breaking: nothing existing changes shape, and `RunWatcher` behaves exactly as before. The hold needs a runtime at this release and, for a hosted runtime, a hosting router that lets `GET /v1/grant?wait=N` through (before then a held read answers 504 after 10 s and the watcher backs off). See [[crouter-sdk/client]].
+
+## 0.3.399
+
+### `onActivity` no longer blocks the watcher
+
+In 0.3.398 the watcher awaited `onActivity` before its next read, so a slow or hung hook delayed that run's `onEnded`, held its `concurrency` slot, and kept `stop()` from resolving. The watcher now never awaits it: at most one call per run runs at a time, a newer reading taken meanwhile replaces any still waiting, and `stop()` does not wait for a call already running. A call can now finish after that run's `onEnded`: guard the write on the row still waiting on the run. Runs that leave `pending()` without an ending no longer keep their last phase in memory. See [[crouter-sdk/client]].
+
+## 0.3.398
+
+### `RunWatcher` reports live progress with `onActivity` (additive)
+
+`oauth.watchRuns({..., onActivity, activityWait?})` calls `onActivity({userId, runId, activity, run})` with each read of a still-`running` run whose `activity` differs from the last one handed over for that run (compared as JSON: `phase`, `tool.name`, `tool.summary`), so an app can show a progress badge from the watcher it already runs instead of a second `runs.get` per page read. It is never called for a run at rest. With `onActivity` set, running runs are read with `wait: activityWait` (integer 1–25, default 2) rather than 25, because the runtime's long-poll answers early only at rest. Best effort: a throwing `onActivity` goes to `onError` and is not retried, and `onEnded` delivery is unchanged. Not breaking: without `onActivity` the watcher behaves exactly as before. New exported type `RunActivityEvent`. See [[crouter-sdk/client]].
+
+## 0.3.397
+
+### A runtime older than the SDK is refused before it handles the request
+
+The SDK now sends `Crouter-Minimum-Runtime-Version: <SDK_VERSION>` on every request except `/healthz`. The hosting router in front of a hosted runtime, and a runtime at this release or later, answer a request that names a newer release than the runtime's with `RuntimeVersionError` (`status` 426, `code` `runtime_version_unsupported`) **before any handler runs**: nothing is accepted, no `Idempotency-Key` is recorded, and a retry after the runtime is rolled forward is a first send. Previously an older runtime handled the request and the SDK raised afterwards. Not breaking: no app code changes. An app that worked around the late check, such as a `runs.list` read before every send, can delete it once its runtimes are at or after this release behind a hosting router that has the check. Back off on `RuntimeVersionError` and retry under the same key. A browser app's preflight now lists `crouter-minimum-runtime-version` in `Access-Control-Allow-Headers`. See [[crouter-sdk/errors]].
+
+## 0.3.396
+
+### `RunObject.activity` has a `submitting_result` phase; `output_schema` runs need only `crtr:llm` (breaking)
+
+- **New phase `{phase: 'submitting_result'}`.** While the root agent writes or records its `output_schema` result, `runs.get(runId).activity` is `{phase: 'submitting_result'}`. It used to be `{phase: 'tool', tool: {name: 'bash', summary: 'crtr push result …'}}`. A `switch` on `activity.phase` that assumed the old set must handle the new value; an app that matched `crtr push result` in `tool.summary` should map this phase instead and delete that check.
+- **An `output_schema` run no longer needs `crtr:act`.** The agent submits through its `submit_result` tool, which needs no scope, so a run started with `scopes: ['crtr:llm']` can finish. Drop `crtr:act` from runs that only granted it so the agent could submit.
+- **A run without `crtr:act` is not offered `bash`.** Its agent never sees a shell tool that the runtime would refuse.
+
+## 0.3.395
+
+### `OAuth2Client` owns the connection store; one `onRefusal` for a dead connection (breaking)
+
+`OAuth2Client` now takes the app's `ConnectionStore` once, as `store` (required), plus an optional `onRefusal(refusal)` handler, and every refused refresh goes through that one handler: a request on a connected client, `refreshIdleConnections`, and the new `RunWatcher`. Apps no longer keep their own refusal table or delete dead connections themselves. See [[crouter-sdk/client]].
+
+- **`oauth.client(connection, store)` is now `await oauth.client(userId)`.** It loads the stored connection and returns a `ConnectedCrouter` (a `Crouter` with `userId` and `runtimeUrl`). Nothing stored throws `CrouterError` code `not_connected`. Save `exchangeCode`'s connection with `store.save(connection)` first.
+- **`oauth.refreshIdleConnections(store, {olderThanMs})` is now `oauth.refreshIdleConnections({olderThanMs})`** and returns `{refreshed, refused, failures}`. `RefreshFailure.reason` is removed: a refused connection is handled by `onRefusal`, removed, and counted in `refused`; `failures` holds only connections still stored (any other error, or a refusal whose handler threw).
+- **`refreshRefusal(error)` and the `RefreshRefusal` type are removed.** Use `onRefusal` (`refusal.kind` is `'removed' | 'paused' | 'reconnect'`, type `RefusalKind`) to act on the connection, and `refusalOf(error)` to answer one request.
+- **`ConnectionStore.lock` is now required, and `remove(userId, refreshToken)` is new and required.** `remove` deletes the row only while it still holds that refresh token and answers whether it deleted one. `MemoryConnectionStore` and `PostgresConnectionStore` implement both; a custom store must add them. The SDK never runs app code under `lock` and never throws out of it, so a Postgres store's transaction commits.
+- **`onRefusal` runs at least once per dead connection** (make it idempotent): after the store lock is released, then the SDK removes the connection (only while it still holds the refused token), then the caller's call rejects with the directory's `AuthenticationError`, on which `refusalOf(error)` returns the `Refusal`. If the handler throws, the connection is kept, the caller gets the refusal error with `cause` set to what the handler threw, the client does not latch it (the next call refreshes and runs the handler again), and `refreshIdleConnections` reports it in `failures`. A handler that calls `oauth.client` or a refresh for the same user throws `CrouterError` code `refusal_handler_reentry` instead of waiting on itself.
+- `refusalOf` returns a `Refusal` only for an error the SDK raised while refreshing a stored connection, not for every directory-origin `AuthenticationError`.
+- Concurrent refreshes in one process are shared per user and refresh token, so a client holding a newer token never joins an older refusal.
+
+**Callers to update:** crouter cloud's chat app (`first-party-apps/chat/src/directory-client.ts`, which builds `oauth.client(connection, store)`) and the context app (`first-party-apps/context/req-run.mjs`). Any app that called `refreshIdleConnections(store, …)`, read `RefreshFailure.reason`, or imported `refreshRefusal` must move to the shapes above.
+
+### `RunWatcher`: learn when a background run ends (additive)
+
+`oauth.watchRuns({pending, onEnded, onError?, sweepMs?, concurrency?})` returns a `RunWatcher` (`start()`, `nudge()`, `stop()`) that follows the runs `pending()` reads from the app's own rows with `runs.get(wait)` and calls `onEnded({userId, runId, ended, run})` when each comes to rest (`settled`, `idle`, `waiting_on_user`) or is deleted (`gone`, only for a 404 `not_found` from the runtime, never the router). Delivery is at least once per `(runId, status, latest_sequence)`: a delivered run is re-read once per sweep and delivered again only when that key changes (an `idle` run later canceled is delivered as `settled`). A throwing `onEnded` is retried after 5 s, doubling to 5 min. Runs are opened with `oauth.client(userId)`, so a refused connection reaches `onRefusal`. There is no runtime-to-app webhook: the runtime cannot mint an app-audience token, a directory relay would add a hop, and the app's rows already make a pull durable and work on localhost. See [[crouter-sdk/client]].
+
+## 0.3.394
+
+### `grant.get` dependencies are one `{ state, message?, next }` entry per provider (breaking)
+
+`GrantGetDTO.dependencies[provider]` was a bare `SetupState` string; it is now a `ProviderDependency` (exported from `@north-light/sdk` and `@north-light/api`): `{ state, message?, next }`. `state` is the setup state the string used to be. `message` is the provider's own sentence for `pending` and `failed` (its `message_pending` / `message_failed`), so delete any copy of a provider's prose your app hard-codes and show `message` instead. `next` is the absolute URL of the directory's setup page for that provider and your app; link the person there (append `return_to` with your registered redirect origin) instead of building the URL yourself. **Change every read of `dependencies[p]` to `dependencies[p].state`** (or `dependencies[p]?.state` where the entry may be missing), and carry `message` and `next` into your `provider_setup_pending` details. The runtime reads only this shape from the directory's grant sync: a runtime on this release paired with a directory that still sends bare strings reports `dependencies` as `{}`, so roll the directory change with it. See [[crouter-sdk/guides/apps-on-crouter-cloud]].
+
+## 0.3.393
+
+### The runtime orders grant state by revision; a failed grant check is `service_unavailable` (breaking)
+
+A runtime on this release requires the `rev` claim in every app access token, so it needs a directory that issues it; a token without `rev` is refused 401 `unauthorized`, "access token has no rev claim: the directory is older than this runtime". A freshly consented or re-consented grant is now authorized on the first call, with no wait: the runtime pulls grant state once whenever a token is newer than its mirror. **Delete any retry your app added for a 401 `grant_revoked` right after consent.** When that pull fails, the call answers 503 `service_unavailable` (`retryable: true`) instead of 401 `grant_revoked`, so a directory outage no longer looks like a refused connection. `service_unavailable` was already in `errorCodes`; app calls can now receive it. See [[crouter-sdk/client]].
+
+## 0.3.391
+
+### The SDK refuses a runtime older than itself (breaking)
+
+`@north-light/sdk` now accepts only a runtime at or above its own version, and fails loudly otherwise instead of handing an app data its types do not describe. Every runtime answer carries `Crouter-Runtime-Version`; when that version is older than `SDK_VERSION`, or the header is absent (every runtime before this release), the call throws `RuntimeVersionError` (`code: 'runtime_version_unsupported'`, `status: 426`, `retryable: false`) whose message and `sdkVersion` / `runtimeVersion` name both versions. A refusal without the header (a router in front of the runtime answering 401 or 503) is still raised as that refusal. There is no capability negotiation: `RunObject.activity` and every other field are typed for a runtime at this release. **Upgrade every runtime the app talks to before upgrading the SDK**, and pin the SDK to an exact version. A test double that fakes the runtime with `fetch` must send `Crouter-Runtime-Version` at the SDK's version on its 2xx answers. See [[crouter-sdk/errors]].
+
+### One release is one version set
+
+`@north-light/sdk@X` now depends on exactly `@north-light/api@X` and `@north-light/identity@X` instead of `^X`, so an exact SDK pin no longer floats its siblings to a later release.
+
+## 0.3.390
+
+### `runs.message` is idempotent and retried
+
+`runs.message` now sends an `Idempotency-Key` (one per call, reused on its retries; override with the new `idempotencyKey` option). The daemon records the key in the transaction that accepts the message and holds it for 24 hours: a replay returns the original result and delivers once, and the same key with a different body fails with `409 idempotency_conflict`. Because it is now safe, `runs.message` retries connection failures and retryable refusals, as `runs.start` already did. The router path (`/v1/runs/:id/messages` through the run routes) previously dropped the header and now honors it.
+
+## 0.3.383
+
+### Structured requests (additive)
+
+`client.structuredRequests` creates, reads, and settles durable structured requests with deadlines and one settlement.
+
+## 0.3.378
+
+### `Identity.picture` (additive)
+
+`Identity` and `profileFromClaims` carry `picture`, the account photo as an https URL, when the sign-in granted `profile` and the account has one.
+
+## 0.3.375
+
+### `runs.get` reports what a running run is doing (additive)
+
+`RunObject.activity` is `{phase: 'starting' | 'thinking' | 'writing' | 'between_turns'}` or `{phase: 'tool', tool: {name, summary}}` while the run is `running`, and `null` otherwise, so a polling app can show progress from `runs.get` without reading `runs.trace`. `runs.list` entries carry it too. See [[crouter-sdk/guides/apps-on-crouter-cloud]]. A test double that builds a `RunObject` literal must add `activity`.
+
+## 0.3.374
+
+### `Identity` carries the person's name (additive)
+
+A sign-in that grants the `profile` scope returns `name`, `givenName`, and `familyName` on `Identity` when the person has a name.
+
+## 0.3.373
+
+### `CrouterError.code` is typed `SdkErrorCode`
+
+Every code the SDK raises itself is now listed in `sdkErrorCodes` (exported with `SdkErrorCode` and `mapError` from `@north-light/sdk/errors`), and `CrouterError`'s `code` and constructor are typed with it. Runtime behavior is unchanged. **An app that constructs `new CrouterError(message, code)` with a code of its own, for example in a test double, no longer typechecks:** throw its own error class or an `APIError` instead. See [[crouter-sdk/errors]].
+
+### Run ergonomics (additive)
+
+`runs.start({prompt, message})` stores a first message that always joins the first turn, and returns it as `run.message` for `runs.reply`. `RunReply.collect({onDelta})` streams a reply and says how its turn ended; `text()` takes the same `onDelta`. `runs.listAll` and `memory.listAll` iterate every page. `refreshRefusal(error)` classifies a refused refresh, and each `refreshIdleConnections` failure carries it as `reason`. `authorizeUrl` takes `prompt: 'consent'`. `parsePrivateJwk` and `privateKeyFromFile` load the app's signing key. No existing call changes.
+
+## 0.3.371 (after 0.3.370)
+
+### A refused refresh says why: `grant_removed`, `grant_suspended`, `refresh_token_expired`
+
+When the directory refuses a connection's refresh token, the SDK now raises the directory's reason as its own code instead of `grant_revoked`:
+
+- `grant_removed`: the person removed your app or deleted their account, and the runtime deleted your app's data for them. This is the only code on which you may delete what you keep for that person.
+- `grant_suspended`: your app is paused for that person. Nothing was deleted; keep their data.
+- `refresh_token_expired`: the refresh token went 90 days unused. The grant is still active; reconnecting skips the consent page.
+
+Each is a 401 `AuthenticationError` with `retryable: false`, `userAction: 'reconnect'`, and `origin: 'directory'`, and the connected client from `oauth.client(...)` stops refreshing after it, as it already did for `grant_revoked` and `refresh_token_reused`. `errorCodes` and the `ErrorCode` type gain the three codes. The table of codes and app actions is in [[crouter-sdk/client]].
+
+**Behavior changes for existing apps:**
+
+- **If your app deletes a person's data on `grant_revoked`, switch it to `grant_removed`.** A removal no longer arrives as `grant_revoked`. `grant_revoked` stays (it is not deprecated) and now means only that the directory or runtime refused without naming a reason; never delete data on it.
+- **`grant_revoked` from the token endpoint is now a 401 `AuthenticationError`, not a 400 `BadRequestError`.** It previously carried the directory's HTTP 400 status; it now has status 401 like the rest of contract 2's `grant_revoked`. Code that checks `error instanceof BadRequestError` or `error.status === 400` for a refused refresh must check `error.code`, or `error.userAction === 'reconnect'`, instead.
+- If your app reconnects on `grant_revoked`, switch on `userAction === 'reconnect'`: every refused-refresh code carries it.
+
+An SDK older than this release maps the three new reasons to `grant_revoked`, so an app keeps its current behavior until it upgrades.

package/dist/builtin-memory/crouter-sdk/resources.md

@@ -0,0 +1,101 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Resource map, this knowledge should be read
+  because Find client namespaces, their daemon routes, and the raw request
+  escape hatch.
+---
+
+# Resource map
+
+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` |
+| `customObjects` | `register`, `publish`, `unregister`, `ack`, `receive` | `/v1/custom-objects…` |
+| `memory` | `list`, `listAll`, `get` | `GET /v1/memory`, `GET /v1/memory/document` |
+| `runs` | `start`, `get`, `list`, `listAll`, `message`, `interrupt`, `cancel`, `delete`, `rename`, `trace`, `events`, `reply`, `stream`, `wait`, `parse` | `/v1/runs…` |
+| `uploads` | `create` | `POST /v1/uploads` |
+| `attachments` | `link` | `GET /v1/attachments/link` |
+| `shares` | `create`, `list`, `delete` | `/v1/shares…` |
+| `questions` | `get`, `answer` | `/v1/questions/{id}…` |
+| `providers` | `tools`, `call` | `/v1/providers/tools`, `POST /v1/provider/call` |
+| `grant` | `get` (`wait`, `since`: hold until `version` changes) | `GET /v1/grant` |
+| `health` | `get` | `GET /v1/health` |
+
+`runs`, `uploads`, `attachments`, `shares`, `questions` and the app side of `grant` and `providers` are the application-facing API an app reaches through the app listener; see [[crouter-sdk/guides/apps-on-crouter-cloud]] and [[crouter-sdk/guides/apps-with-many-users]]. `memory` is the person's `public` documents ([[crouter-sdk/memory]]). `system.health` (`/healthz`) is the daemon's liveness check; `health.get` is the app listener's.
+
+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`.
+
+## Custom objects
+
+`client.customObjects` registers an external service or script as an object on the canvas, with a declared event catalog and a queue, URL or argv receiver, and publishes its events to the objects watching it. `register(body)` returns the object and, once, its publish token; `publish(ref, body)` sends one declared event (a custom object may publish with that token alone); `receive(ref, { after?, signal? })` is an async iterator over a queue receiver's deliveries and replays every unacknowledged delivery on each connect; `ack(ref, deliveryIds)` acknowledges them; `unregister(ref)` deletes the object. The same objects are managed from a terminal with `crtr custom-object` and watched with `crtr canvas watch`.
+
+## Files and bash
+
+[[crouter-sdk/files]] 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. [[crouter-sdk/bash]] 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
+
+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 [[crouter-sdk/streaming]] 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 the table above. Say so rather than building on the escape hatch.

package/dist/builtin-memory/crouter-sdk/streaming.md

@@ -0,0 +1,218 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Streaming, this knowledge should be read
+  because 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 [[crouter-sdk/errors]].
+
+## 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.