@north-light/cli 0.0.0 → 0.3.414

package/docs/sdk/nodes.md

@@ -0,0 +1,194 @@
+---
+title: Nodes
+description: Create agent runs, wait for outcomes, and parse structured results.
+---
+
+# `client.nodes`
+
+Shipped, except where a row says otherwise.
+
+A node is one agent run on the crouter canvas. It is asynchronous by construction: `create` returns as soon as the daemon has spawned it, and the run keeps working after your call returns.
+
+There is one name for it — `client.nodes`. There is no `client.responses` alias. A node has a canvas identity, a kind, a working directory, a profile, a deadline, reports, subscriptions, children, and a lifecycle; naming it `responses` would promise `previous_response_id`, `output_text`, `tools`, and `store` semantics that do not exist here.
+
+## Methods
+
+| Method | Route | Phase | Notes |
+|---|---|---|---|
+| `nodes.create(params)` | `POST /v1/nodes` | 1 | Returns immediately with the node; it is already running. |
+| `nodes.retrieve(id)` | `GET /v1/nodes/{id}` | 1 | |
+| `nodes.list(query?)` | `GET /v1/nodes` | 1 | Returns an array, as the daemon does. |
+| `nodes.outcome(id, { wait })` | `GET /v1/nodes/{id}/outcome?wait=` | 1 | One long poll, `wait` 0–25 s. Returns the wire envelope with `state: 'pending' | 'settled'`. |
+| `nodes.waitForOutcome(id, opts?)` | repeats the above | 1 | Loops until settled. Honours `signal`; no implicit time bound. |
+| `nodes.createAndWait(params, opts?)` | create + wait | 1 | |
+| `nodes.parse(params, opts?)` | create + wait + typed result | 1 | [See below](#parse-and-structured-output). |
+| `nodes.message(id, body)` | `POST /v1/nodes/{id}/messages` | 1 | Send a follow-up to a running or dormant node. |
+| `nodes.interrupt(id)` | `POST /v1/nodes/{id}/interrupt` | 1 | Stop the current turn, keep the node. |
+| `nodes.cancel(id, body?)` | `POST /v1/nodes/{id}/close` | 1 | Tears the node and its exclusive subtree down. `cancel` is the method name; `close` is the route. |
+| `nodes.update(id, patch)` | `PATCH /v1/nodes/{id}/config` | Shipped | |
+| `nodes.fork(id)` | `POST /v1/nodes/{id}/fork` | Shipped | |
+| `nodes.revive(id, body?)` | `POST /v1/nodes/{id}/revive` | Shipped | |
+| `nodes.promote(id, body?)` / `nodes.demote(id)` | matching routes | Shipped | Move a node between base and orchestrator mode. |
+| `nodes.recycle(id)` | `POST /v1/nodes/{id}/recycle` | Shipped | |
+| `nodes.yield(id, body?)` | `POST /v1/nodes/{id}/yield` | Shipped | |
+| `nodes.wait(id, body)` | `POST /v1/nodes/{id}/wait` | Shipped | |
+| `nodes.relaunchRoot(id)` | matching route | Shipped | |
+| `nodes.reviveAll()` | `POST /v1/nodes/revive-all` | Shipped | |
+| `nodes.stream(params, options?)` | create + `GET /…/events` | Shipped | [Streaming](./streaming.md). |
+| `nodes.events(id, options?)` | `GET /v1/nodes/{id}/events` | Shipped | [Streaming](./streaming.md). |
+
+Action methods keep the product's literal name (`fork`, `revive`, `promote`, `yield`) rather than being renamed into a generic verb.
+
+Every method in the table accepts `RequestOptions` as its final argument: `{ headers?, signal?, timeout?, maxRetries? }`. `nodes.stream(params, options?)` uses those options for create and stream opening, except that its stream has no wall-clock `timeout`; `nodes.events(id, options?)` takes `NodeEventsOptions`, which adds `after` and excludes `timeout`.
+
+## Create parameters
+
+Wire fields are `snake_case`. Every `NodeCreateParams` property is optional; `parse()` additionally requires `output_schema`. `NodeCreateParams` is the daemon's `CreateNodeRequest`, except `output_schema` also accepts an object. When neither `parent` nor `root` is supplied, the SDK sends `root: true`; otherwise fields pass through without camelizing.
+
+| Field | Type | Meaning |
+|---|---|---|
+| `prompt` | `string` | The run's entire brief. |
+| `kind` | `string` | Persona. Omit for the profile's default. |
+| `model` | `string` | Durable model override. |
+| `profile` | `string` | The profile the run uses: its project purview, environment and profile-owned documents. An application passes **its own** profile here. |
+| `cwd` | `string` | Where the request came from. |
+| `pin_cwd` | `string` | Pin the node to this directory regardless of `cwd`. |
+| `situational_context` | `string` | Ambient context kept out of the visible prompt. |
+| `deadline` | `string` (`1h30m`) | Wall clock from spawn. Expiry cancels the node and records `deadline_exceeded`. |
+| `output_schema` | `string \| JsonSchema \| { toJSONSchema(): JsonSchema }` | Widened from the wire's JSON string; the SDK serializes. A zod v4 object satisfies the third form. |
+| `root` | `boolean` | No parent, no subscription. An application's run is a root. |
+| `root_lifecycle` | `'terminal' \| 'resident'` | `terminal` for a bounded run; `resident` for one a person will open and keep. |
+| `mode` | `'base' \| 'orchestrator'` | Whether the node works hands-on or fans out to children. |
+| `name` | `string` | Display label. |
+| `description` | `string` | Display description. |
+| `parent` | node id | Graph placement. An external caller leaves this unset. |
+| `creator` | node id | Graph placement. An external caller leaves this unset. |
+| `scopes` | `string[]` | Per-run allow-list. Omit it to inherit every scope, or under a scoped token to receive that token's ceiling; a list outside the ceiling answers `403 scope_denied` with the offending scopes in `details.scopes`. Scopes are prefixed (`crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:…`, `crtr:files:…`); `crtr:act` requires `crtr:llm`, and the list must stay inside what the creator's grant holds. Some scopes are recorded rather than enforced, per the `CreateNodeRequest` contract. See [scoped tokens](./getting-started.md#a-token-that-holds-less-than-the-owner). |
+| `worktree` | `string \| boolean` | Create a managed git worktree for the run. |
+| `fork_from` | `string` | Start from an existing conversation. |
+| `no_kickoff` | `boolean` | Create the node without sending the first message. |
+| `node_id` | `string` | Spawn at an exact id. A collision answers `409 node_id_exists`. |
+| `prefer_warm` | `boolean` | Serve from the warm pool when the launch tuple matches. |
+| `outcome_delivery` | `{ action, payload? }` | Arm outcome delivery at birth. |
+
+`node_id` is how you make a create safely retryable. Retry with the same id and a duplicate fails loudly with `409 node_id_exists` instead of quietly spawning a second agent — which is why the client never retries a `POST` for you. See [Errors](./errors.md).
+
+## Outcomes
+
+`waitForOutcome`, `createAndWait`, and `parse` return the settled `NodeOutcome` — the same union the API defines, not a translation of it.
+
+| Wire | Narrow on | Carries |
+|---|---|---|
+| `kind: 'result'` | `outcome.kind === 'result'` | `structured_result`, `final_report_path`, and on `parse` a typed `output_parsed` |
+| `kind: 'failure'`, `reason: 'declined'` | `outcome.reason === 'declined'` | `declined: { reason, code, retryable } \| null` — the agent honestly refused the schema |
+| `kind: 'failure'`, any other `reason` | anything else | `detail: NodeOutcomeDetailV1 \| null` — `deadline_exceeded`, a provider fault, a wedge |
+
+**Agent-side outcomes are returned, never thrown.** A decline carries a typed reason, a code the agent chose, and a `retryable` flag; routing that through an exception would discard the payload and make the happy path lie about what happened. Only transport faults, daemon errors, and your own abort throw.
+
+```ts
+const outcome = await client.nodes.waitForOutcome(node.node_id, { signal });
+
+switch (true) {
+  case outcome.kind === 'result':
+    console.log(outcome.structured_result, outcome.final_report_path);
+    break;
+  case outcome.reason === 'declined':
+    console.warn(outcome.declined?.reason, outcome.declined?.retryable);
+    break;
+  default:
+    console.error(outcome.reason, outcome.detail);
+}
+```
+
+### `outcome()` versus `waitForOutcome()`
+
+`nodes.outcome(id, { wait })` is one long poll: the daemon holds the request open for up to `wait` seconds (0–25) and answers `{ node_id, state: 'pending' | 'settled', outcome, node_status, deadline_at }`. `outcome` is `null` while `state` is `'pending'`. Use it when your own loop owns the timing — a job runner that wants to do other work between polls, or a UI that shows a heartbeat.
+
+`nodes.waitForOutcome(id, opts?)` repeats that poll until the node settles. It applies **no implicit time bound**: an agent that runs for an hour is polled for an hour. Bound it from either side — pass a `deadline` to `create` so the daemon cancels the run, or pass a `signal` so your client stops waiting.
+
+```ts
+for (;;) {
+  const poll = await client.nodes.outcome(node.node_id, { wait: 25 });
+  if (poll.state === 'settled' && poll.outcome !== null) {
+    console.log(poll.outcome);
+    break;
+  }
+  // update your UI or job heartbeat here
+}
+```
+
+## `parse()` and structured output
+
+```ts
+import { z } from 'zod';
+
+const run = await client.nodes.parse({
+  prompt: 'Summarize the failing tests in this repo.',
+  cwd: '/path/to/repo',
+  output_schema: z.object({ failures: z.array(z.string()), root_cause: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.root_cause);
+else if (run.reason === 'declined') console.warn(run.declined?.reason);
+```
+
+`ParsedOutcome<T>` is `NodeOutcome & { output_parsed: T | null }`, discriminated so `output_parsed` is non-null exactly when `kind === 'result'`.
+
+`output_parsed` is `structured_result` typed to the schema you passed. A Zod schema uses its inferred output type; a Standard Schema uses `~standard.types.output`. A JSON-Schema literal and any other object with `toJSONSchema()` are accepted and serialized, but their `output_parsed` type is `unknown`. The SDK does not re-validate the result — the daemon already enforces the schema when the agent submits it, so a second validation pass would only produce a second set of error messages for the same rejection. There is no helper equivalent to OpenAI's `zodTextFormat`.
+
+A candidate from Basis's real structured SDK result:
+
+```json
+{
+  "tmp": "k1",
+  "type": "claim",
+  "slug": "config-memories-in-project",
+  "text": "All applet configuration memories belong in project memories.",
+  "quote": "All configuration memories should be in the project memories. We know that.",
+  "speaker": "Me",
+  "confidence": "green"
+}
+```
+
+## Sending a follow-up
+
+`nodes.message(id, body)` appends to a node's inbox. A dormant node wakes to read it; a running node picks it up at its next turn boundary.
+
+```ts
+await client.nodes.message(node.node_id, { body: 'Also check the integration lane.' });
+```
+
+## Stopping a run
+
+| Call | Effect |
+|---|---|
+| `nodes.interrupt(id)` | Stops the current turn. The node stays on the canvas and can be messaged or revived. |
+| `nodes.cancel(id, body?)` | Tears the node down along with the subtree it exclusively owns. Terminal. |
+
+Aborting a `signal` you passed to `waitForOutcome` stops **your client waiting**. It does not stop the node. Call `cancel` for that.
+
+## Nested resources
+
+Nested routes become nested properties.
+
+| Property | Methods | Phase |
+|---|---|---|
+| `nodes.reports` | `list` | Shipped |
+| `nodes.jobs` | `list`, `cancel` | Shipped |
+| `nodes.worktree` | `close`, `abandon` | Shipped |
+| `nodes.result` | `submit` | Shipped — only an agent inside a run calls this |
+
+`nodes.reports.list(id)` returns the agent's pushed progress reports, newest first. Use it when reports are the progress view your application needs; use [streaming](./streaming.md) for live output and tool-call events.
+
+```ts
+const reports = await client.nodes.reports.list(node.node_id, { limit: 10 });
+for (const report of reports) console.log(report.tier, report.body);
+```
+
+## Pagination
+
+List routes return what the daemon returns. `nodes.list`, `nodes.reports.list`, and `nodes.jobs.list` return plain arrays — there is no page object, no `hasNextPage()`, and no `after` cursor on them, because the daemon has no paging substrate behind those routes and an envelope there would promise a continuation that can never happen.
+
+## Identifier validation
+
+Methods that take a node id validate it before the request: core node methods, lifecycle methods, `nodes.reports`, `nodes.jobs`, `nodes.worktree`, and `nodes.result`. An invalid id throws `TypeError` locally and sends no request. `nodes.outcome(id, { wait })` also throws `RangeError` locally when `wait` is not an integer from 0 through 25.

package/docs/sdk/release-notes.md

@@ -0,0 +1,207 @@
+---
+title: Release notes
+description: 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 [Testing your app](./testing.md).
+
+### `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 [Link to the app's settings on crouter cloud](./client.md#link-to-the-apps-settings-on-crouter-cloud).
+- **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 [Learn when a person's grant changes](./client.md#learn-when-a-persons-grant-changes).
+
+## 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 [Learn when a background run ends](./client.md#learn-when-a-background-run-ends).
+
+## 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 [Learn when a background run ends](./client.md#learn-when-a-background-run-ends).
+
+## 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 [Errors](./errors.md).
+
+## 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 [When a refresh is refused](./client.md#when-a-refresh-is-refused).
+
+- **`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 [Learn when a background run ends](./client.md#learn-when-a-background-run-ends).
+
+## 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 [Waiting on a provider your app requires](./guides/apps-on-crouter-cloud.md#waiting-on-a-provider-your-app-requires).
+
+## 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 [An app connection and refresh](./client.md#an-app-connection-and-refresh).
+
+## 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 [Errors](./errors.md).
+
+### 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 [Showing a background run's progress](./guides/apps-on-crouter-cloud.md#showing-a-background-runs-progress). 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 [Errors](./errors.md).
+
+### 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 [When a refresh is refused](./client.md#when-a-refresh-is-refused).
+
+**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/docs/sdk/resources.md

@@ -0,0 +1,99 @@
+---
+title: Resource map
+description: 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 [Apps on crouter cloud](./guides/apps-on-crouter-cloud.md) and [Apps with many users](./guides/apps-with-many-users.md). `memory` is the person's `public` documents ([Memory](./memory.md)). `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
+
+[`client.files`](./files.md) reads through `GET /v1/files/peek`, atomically writes, and lists absolute host paths. Reads and lists report `truncated`; writes over 1 MiB are refused instead of truncated. [`client.bash`](./bash.md) runs one command in a required absolute working directory and returns non-zero exits as values.
+
+## Canvas
+
+`client.canvas.attention()`, `attentionCounts(body)`, `snapshot()`, `roster()`, and `prune(body)` each send their matching canvas route. `dashboard(query?)` composes `GET /v1/nodes` and `GET /v1/status`, because the daemon deliberately has no dashboard route. `client.canvas.history.search(body)`, `grep(body)`, `read(query)`, and `stats(body)` wrap the four history routes.
+
+## Crons
+
+`client.crons.create(body)`, `retrieve(id, query?)`, `list(query?)`, `pause(id, query?)`, `resume(id, query?)`, `run(id, query?)`, `delete(id, query?)`, and `poke()` retain the daemon's cron DTOs and snake_case query fields. `delete` is the SDK verb for the daemon's `DELETE /v1/crons/{id}` route.
+
+## Human requests and inbox
+
+`client.human.requests` exposes `create`, `retrieve`, `replace`, `respond`, `dismiss`, and `cancel`. `client.human.inbox` exposes `list`, `retrieve`, `respond`, `progress`, `cancel`, `history`, and `response`. The inbox methods preserve the page protocol's nested camelCase fields and the daemon envelope's snake_case fields.
+
+## Models
+
+`client.models.credentials.list()`, `install(provider, body)`, and `remove(provider)` wrap `/v1/model-auth`. `client.models.config.update(body)` sends `PUT /v1/model-config`. Credential material is accepted only by `install`; list responses remain sanitized daemon DTOs.
+
+## Identifier validation
+
+Methods with node, cron, bash-job, human-request, inbox-ticket, provider, or profile identifiers validate them before calling the daemon. Invalid values throw `TypeError` locally and send no request. This applies to node action methods and nested node resources, cron methods that take an id, `human.requests` methods that take an id, `human.inbox` methods that take a ticket id, `models.credentials.install` and `remove`, and profile `ensure` and `retrieve`. File paths are not subject to this identifier check; the daemon validates their absolute-path contract.
+
+## Excluded from the typed surface
+
+These `/v1` routes get no SDK method, with the reason. They are still reachable through `client.request()`.
+
+| Routes | Why |
+|---|---|
+| `/v1/focuses…` | A focus maps a node to a tmux pane. An SDK caller has no tmux. It stays on `/v1` for the viewer. |
+| `POST /v1/nodes/{id}/mail/claim`, `…/mail/acknowledge` | These are how a node's own broker takes delivery of its inbox. An external caller claiming another node's mail would consume deliveries that node then never sees. |
+| `POST /v1/nodes/{id}/attach` | Returns the host-local path to a broker's viewer socket. A remote or browser caller cannot open that path, and [Streaming](./streaming.md) is the application-facing way to watch a node. |
+| Broker operations, broker recovery, node faults | The broker's own control plane — session binding, settle directives, park completion, turn recording, provider-retry mutation, fault recording, model commit. They exist so the one process hosting a node can coordinate with crtrd about that node's runtime. An external caller invoking them introduces a second writer to state the broker and the daemon coordinate between themselves. |
+
+## The escape hatch
+
+Nothing on `/v1` is unreachable. A route that is excluded above, or one added to the daemon after this SDK version was published, is reachable directly:
+
+```ts
+client.request(method, path, body?, options?)
+```
+
+It carries the same authentication, the same retry policy, and the same error mapping as every generated method — it is untyped, not unsupported.
+
+```ts
+const focuses = await client.request<FocusDTO[]>('GET', '/v1/focuses');
+
+await client.request('POST', `/v1/nodes/${id}/some-new-route`, { field: 'value' }, { timeout: 5_000 });
+```
+
+If you find yourself reaching for `client.request()` for something an application genuinely needs, that route belongs in the table above. Say so rather than building on the escape hatch.