@north-light/crouter 0.3.320 → 0.3.322

package/docs/sdk/getting-started.md

@@ -0,0 +1,160 @@
+# Getting started
+
+Phase 1.
+
+An agent run needs a crouter daemon (`crtrd`) to run it. The SDK is a client for that daemon — it never runs an agent itself. There are two ways to reach one: the unix socket on the machine you are running on, or a TCP listener with a bearer token.
+
+## 1. Install the runtime
+
+```bash
+npm i -g @north-light/crouter
+```
+
+That installs the `crtr` CLI and the `crtrd` daemon. You do not have to start the daemon: `new Crouter()` starts it for you on a cold socket (see `autostart` in [Client construction](./client.md)).
+
+## 2. Install the SDK in your application
+
+```bash
+npm i @north-light/crouter-sdk
+```
+
+One dependency. It re-exports every data type you need, so you do not also install `@north-light/crouter-api`.
+
+## 3. Node, on the owner's own daemon
+
+Pass nothing. The client resolves the same socket path the `crtr` CLI does, and starts the daemon if it is not already up.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+
+const client = new Crouter();
+
+const node = await client.nodes.create({
+  prompt: 'List the top-level directories here and say what each one is for.',
+  cwd: process.cwd(),
+  root: true,
+  root_lifecycle: 'terminal',
+});
+
+const outcome = await client.nodes.waitForOutcome(node.node_id);
+if (outcome.kind === 'result') console.log(outcome.final_report_path);
+```
+
+`root: true` says this run has no parent node and reports to nobody — which is what an application's run is. `root_lifecycle: 'terminal'` says it finishes and reaps; use `'resident'` for a run a person will open and keep talking to.
+
+## 4. A browser or a remote application
+
+A process that is not on the daemon's machine — or a page in a browser, which has no unix sockets at all — reaches the daemon over TCP with a bearer token. The token is the owner credential: whoever holds it can drive the whole surface.
+
+### Turn the listener on, once
+
+On the machine running the daemon:
+
+```bash
+crtr sys connect
+```
+
+This stores a listener address and generates a token if either is missing, then prints the base URL and token before handing the daemon over to a successor that boots with the listener on. It then logs in to the selected model provider when that provider has no usable credential. Run it again and, when the listener is up and that provider is ready, it prints the credentials and changes nothing.
+
+The command returns `base_url` and `token`. Use JSON output when a program or a setup UI needs those exact fields:
+
+```text
+$ crtr --json sys connect
+{"base_url":"http://127.0.0.1:8787","token":"<64-character bearer token>"}
+```
+
+### Check setup before generating
+
+Construct the client from the application's saved connection. On the first visit that value is absent, and `client.auth.status()` returns `'connect'` without a request. Once the user pastes the base URL and token printed by `crtr sys connect`, construct it again and call `status()` to check the selected provider.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+
+const saved = loadConnection(); // { baseURL: string; token: string } | null
+const client = new Crouter(saved ?? {});
+const status = await client.auth.status({ profile: 'my-app', cwd: '/path/to/repo' });
+
+if (status.next_step !== null) {
+  showSetupPanel({ step: status.next_step, instructions: status.instructions! });
+  return;
+}
+
+const run = await client.nodes.createAndWait({
+  prompt: 'What changed in this repo today?',
+  cwd: '/path/to/repo',
+  profile: 'my-app',
+  root: true,
+});
+```
+
+`status()` returns `next_step: 'connect'` when the application has no daemon transport, when the saved bearer token is rejected, or when the saved base URL cannot be reached. It returns `next_step: 'login'` when the daemon resolves the selected run to a provider without a ready credential. In both cases, display `instructions`: it names the exact `crtr sys connect` action and, for a login, the provider. When `status()` receives `profile`, `cwd`, `kind`, or `model`, the login instruction passes those selectors to `crtr sys connect`; use the text unchanged. A daemon that is still starting is connected with `next_step: null`; inspect `status.daemon.startup_phase` and wait for it to become `ready` before starting a run.
+
+An isolated auth-status probe returned:
+
+```json
+{
+  "no_request": {
+    "next_step": "connect",
+    "requests": 0
+  },
+  "missing": {
+    "provider": "anthropic",
+    "credential": "missing",
+    "next_step": "login",
+    "instructions": "Run `crtr sys connect --cwd /private/tmp/crouter-sdk-auth-proof.P3fSWg/empty --model anthropic/claude-opus-5` to log in to anthropic."
+  },
+  "ready": {
+    "provider": "anthropic",
+    "credential": "ready",
+    "next_step": null
+  }
+}
+```
+
+The root entry of the SDK is browser-safe: it imports nothing from `node:*`. The unix-socket code is reached only through a dynamic import taken when `socketPath` is set, so a browser bundle never resolves it.
+
+### Cross-origin calls
+
+The daemon answers the browser's `OPTIONS` preflight with `Access-Control-Allow-Origin: *` and allows the `authorization` and `content-type` headers, and every authorized response carries the same origin header. This happens **only when a token is set** — an unauthenticated listener stays same-origin, because otherwise any page the user visits could drive their daemon.
+
+The credential is a header your application already holds, never a cookie, so the daemon sends no `Access-Control-Allow-Credentials`.
+
+### Chrome's local-network permission
+
+A page served over HTTPS that calls `http://localhost:<port>` is governed by Chrome's Local Network Access permission. The browser prompts the user once per site; the daemon needs **no special response header** for it — ordinary CORS plus a secure context is the whole requirement. See [developer.chrome.com/blog/local-network-access](https://developer.chrome.com/blog/local-network-access).
+
+Tell your users what the prompt is for. A prompt that appears with no explanation gets dismissed, and the dismissal is sticky.
+
+## 5. A typed result
+
+`parse()` creates the run, waits for it to settle, and types the structured result against the schema you gave it.
+
+```ts
+import { z } from 'zod';
+
+const run = await client.nodes.parse({
+  prompt: 'Read package.json here and report its name and version.',
+  cwd: '/path/to/repo',
+  output_schema: z.object({ name: z.string(), version: z.string() }),
+});
+
+if (run.kind === 'result') {
+  console.log(run.output_parsed.name, run.output_parsed.version);
+} else if (run.reason === 'declined') {
+  console.warn('the agent refused the schema:', run.declined?.reason);
+} else {
+  console.error('the run failed:', run.reason, run.detail);
+}
+```
+
+`output_parsed` is non-null on a result. A Zod schema supplies its inferred output type; a Standard Schema supplies `~standard.types.output`. A JSON-Schema literal or any other `{ toJSONSchema() }` object is accepted but makes `output_parsed` `unknown`.
+
+An outcome is returned, never thrown — including a decline and a failure. Only transport faults, daemon errors, and your own abort throw. See [Errors](./errors.md).
+
+## Where to go next
+
+- Every constructor option and environment-variable fallback: [Client construction](./client.md)
+- Checking the daemon connection and selected provider before a run: `client.auth.status()` above
+- The full create-parameter table and the outcome union: [Nodes](./nodes.md)
+- Watching a run as it works: [Streaming](./streaming.md) (phase 2)
+- Running the daemon in a container instead: [Docker environment](./docker.md)

package/docs/sdk/memory.md

@@ -0,0 +1,107 @@
+> **Phase 3 — not shipped.** Only `GET /v1/memory/resolve` exists on the daemon today. Every other route on this page is new work, blocked on extracting a memory service the CLI leaves currently hold inside their own `run()` functions. `client.memory` is not on the client yet.
+
+# `client.memory`
+
+Read and write the memory documents an agent run consults — the knowledge and preference documents that shape how a node behaves.
+
+## Scope: every request names its target
+
+A memory document's identity depends on where it is being read from. The CLI fills that in from its own process — its working directory, its profile, its node. **A daemon route must never do that**, because the daemon's own working directory is meaningless to a caller and would leak one caller's stores into another's read. So every memory call takes an explicit scope.
+
+```ts
+type MemoryScope = {
+  node?: string;      // node id — the daemon derives cwd and profile from the node row
+  cwd?: string;       // project stores discovered by walking up from here
+  profile?: string;   // profile store
+  store?: 'node' | 'project' | 'profile' | 'user' | 'builtin';  // restrict to one tier
+};
+```
+
+`node` is the convenient form: give a node id and the daemon reads that node's working directory and profile from canvas state.
+
+**With no scope at all, only the user-global and builtin stores are in view.** That is deliberate, not a default to lean on — pass the scope you mean.
+
+Stores resolve in precedence order: node → project (nearest first) → profile → user → builtin.
+
+## Methods
+
+| Method | Route | What it does |
+|---|---|---|
+| `memory.list(scope & { kind?, limit?, after? })` | `GET /v1/memory/docs` | A page of document summaries. |
+| `memory.retrieve(name, scope & { frontmatter? })` | `GET /v1/memory/docs/{name}` | One document with its body. |
+| `memory.create(params)` | `POST /v1/memory/docs` | `name`, `kind`, `when_and_why_to_read`, `body`, optional `frontmatter`/`extensions`, plus scope. |
+| `memory.update(name, params)` | `PATCH /v1/memory/docs/{name}` | `rationale` is **required**. |
+| `memory.delete(name, scope)` | `DELETE /v1/memory/docs/{name}` | Leaves a tombstone. |
+| `memory.move(name, { to, ...scope })` | `POST /v1/memory/docs/{name}/move` | Renames and rewrites inbound links. |
+| `memory.search(params)` | `POST /v1/memory/search` | A page of hits; `grep` mode returns line matches instead of scored documents. |
+| `memory.history(name, scope & { limit?, revision?, diff? })` | `GET /v1/memory/docs/{name}/history` | Revisions with their rationales. |
+| `memory.resolve(name, scope)` | `GET /v1/memory/resolve` | Which document a name resolves to for that target. The one route that exists today. |
+
+<!-- TODO(verify): run against a live daemon once phase 3 lands; confirm argument order and the exact parameter names on each method. -->
+
+```ts
+const page = await client.memory.list({ node: nodeId, kind: 'knowledge', limit: 50 });
+const doc  = await client.memory.retrieve('insights/capture', { node: nodeId, frontmatter: true });
+
+await client.memory.create({
+  name: 'billing/refund-policy',
+  kind: 'knowledge',
+  when_and_why_to_read: 'When handling a refund request, this should be read because the eligibility window is not derivable from the order record.',
+  body: '…',
+  profile: 'my-app',
+});
+
+await client.memory.update('billing/refund-policy', {
+  rationale: 'The window moved from 30 to 60 days on 2026-01-04.',
+  body: '…',
+  profile: 'my-app',
+});
+```
+
+A document name contains slashes (`insights/capture`) and is percent-encoded into a single path segment on the wire. The SDK does that for you.
+
+## What the routes enforce
+
+These invariants come from the CLI's behaviour and are preserved exactly:
+
+- `rationale` is required on every update and is stored **only in the history log**, never in the document text.
+- A no-op edit is refused.
+- `kind`, `when-and-why-to-read`, `origin`, and `last-updated` cannot be set directly through `frontmatter`.
+- Builtin and plugin documents are read-only.
+- The root project namespace is immutable.
+- A canonical-name collision is checked against both `<local>.md` and `<local>/INDEX.md`.
+- Every mutation appends a history record with the full before and after.
+- A delete leaves a tombstone.
+
+Lint runs per document on write and its findings ride back in the response. There is no corpus-lint route — `crtr memory lint` writes to stderr and sets an exit code, which is CLI behaviour with no SDK equivalent.
+
+## What the routes will not do
+
+**The daemon does not execute shell blocks.** `crtr memory read` expands embedded shell in a document; the route returns the document source **unexpanded**. A daemon running shell from document content on behalf of an HTTP caller is a code-execution path with no caller-visible boundary. Expansion stays in the CLI.
+
+**Gate predicates are not a security boundary.** When you pass `node`, the routes apply the document's gate — which decides what a given persona sees — and skip it when you do not. Access control is the credential you hold, not the gate.
+
+**Concurrent writes are last-write-wins.** Two callers mutating the same document produce one file and two history records. Multi-file moves with link rewriting are not atomic. This is also what two CLI processes do today; there is no lock.
+
+## Pagination
+
+`memory.list` and `memory.search` are the only routes in the SDK with a page envelope, because they are the only ones with a real cursor behind them. Documents are ordered by canonical name, which is stable, so the cursor is the last item's `name`.
+
+<!-- TODO(verify): run against a live daemon once phase 3 lands; confirm the page object's method names. -->
+
+```ts
+const page = await client.memory.search({ query: 'refund window', node: nodeId });
+
+for (const hit of page.data) console.log(hit.name, hit.score);
+
+if (page.hasNextPage()) {
+  const next = await page.getNextPage();
+}
+
+// or iterate across page boundaries
+for await (const hit of client.memory.search({ query: 'refund window', node: nodeId })) {
+  console.log(hit.name);
+}
+```
+
+The envelope is `{ object: 'list', data, has_more }`. There is no `first_id` or `last_id` — the cursor is on the item.

package/docs/sdk/migration.md

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

package/docs/sdk/nodes.md

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

package/docs/sdk/resources.md

@@ -0,0 +1,71 @@
+# Resource map
+
+Every namespace on the client, with the phase it lands in. A namespace marked phase 2 or phase 3 does not exist yet.
+
+Namespaces are camelCase. Verbs are `create`, `retrieve`, `list`, `update`, `delete`, and `cancel`, except where the product already has a literal name for the action (`fork`, `revive`, `promote`, `pause`, `poke`) — in which case the SDK uses that name.
+
+| Namespace | Methods | Routes | Phase |
+|---|---|---|---|
+| `nodes` | `create`, `retrieve`, `list`, `cancel`, `interrupt`, `message`, `outcome`, `waitForOutcome`, `createAndWait`, `parse` | `/v1/nodes…` | 1; remaining methods in 2 |
+| `nodes.reports` | `list` | `/v1/nodes/{id}/reports` | 1 (`create` in 2) |
+| `nodes.messages` | `list` | `/v1/nodes/{id}/messages` | 2 |
+| `nodes.artifacts` | `list` | `/v1/nodes/{id}/artifacts` | 2 |
+| `nodes.context` | `list` | `/v1/nodes/{id}/context` | 2 |
+| `nodes.transcript` | `retrieve` | `/v1/nodes/{id}/transcript` | 2 |
+| `nodes.session` | `retrieve` | `/v1/nodes/{id}/session` | 2 |
+| `nodes.snapshot` | `retrieve` | `/v1/nodes/{id}/snapshot` | 2 |
+| `nodes.subject` | `retrieve` | `/v1/nodes/{id}/subject` | 2 |
+| `nodes.outcomeDelivery` | `create`, `retrieve`, `delete` | `/v1/nodes/{id}/outcome-delivery` | 2 |
+| `nodes.subscriptions` | `create`, `delete` | `/v1/nodes/{id}/subscriptions` | 2 |
+| `nodes.jobs` | `list`, `cancel` | `/v1/nodes/{id}/jobs` | 2 |
+| `nodes.worktree` | `close`, `abandon` | `/v1/nodes/{id}/worktree/…` | 2 |
+| `nodes.result` | `submit` | `POST /v1/nodes/{id}/result` | 2 — only an agent inside a run calls this |
+| `profiles` | `ensure`, `retrieve` | `/v1/profiles…` | 1; remaining methods in 2 |
+| `auth` | `status` | `GET /v1/status`, then `GET /v1/model-auth/readiness` once the daemon is ready | 1 |
+| `system` | `status`, `health`, `restart`, `admit`, `migrate` | `/v1/status`, `/healthz`, `/v1/daemon/…` | 1 for `status` and `health`; 3 for the rest |
+| `files` | `peek` | `/v1/files/peek` | 1 |
+| `bash` | — | — | 2 — reserved; not on the client today |
+| `llm` | — | — | Reserved; unbuilt |
+| `providers` | — | — | Reserved; unbuilt |
+| `canvas` | `attention`, `attentionCounts`, `snapshot`, `roster`, `dashboard`, `prune` | `/v1/canvas…` | 2 |
+| `canvas.history` | `search`, `grep`, `read`, `stats` | `/v1/canvas/history/…` | 2 |
+| `crons` | `create`, `retrieve`, `list`, `pause`, `resume`, `run`, `delete`, `poke` | `/v1/crons…` | 2 |
+| `human.requests` | `create`, `retrieve`, `replace`, `respond`, `dismiss`, `cancel` | `/v1/human/requests…` | 2 |
+| `human.inbox` | `list`, `retrieve`, `respond`, `progress`, `cancel`, `history`, `response` | `/v1/human/inbox…` | 2 |
+| `models.credentials` | `list`, `install`, `remove` | `/v1/model-auth…` | 2 |
+| `models.config` | `update` | `PUT /v1/model-config` | 2 |
+| `memory` | `list`, `retrieve`, `create`, `update`, `delete`, `move`, `search`, `history`, `resolve` | `/v1/memory…` | 3 — [Memory](./memory.md) |
+| `human.reviews` | `create`, `retrieve`, `list`, `submit`, `cancel`, `document` | `/v1/human/reviews…` | 3 |
+| `human.reviews.comments` / `human.comments` | `create`, `list`, `retrieve`, `edit`, `resolve`, `reopen`, `delete`, `fork`, `events`, `ranges` | `/v1/human/…comments…` | 3 |
+| `human.inbox.feedbackComments` | `create`, `resolve` | `/v1/human/inbox/{ticket}/feedback-comments…` | 3 |
+| `models.chatInventory` | `retrieve(nodeId)`, `prospective(query)` | `/v1/nodes/{id}/chat-inventory`, `/v1/prospective-chat-inventory` | 3 |
+| `worktrees` | `listQuarantined` | `/v1/worktrees/quarantined` | 3 |
+
+## Excluded from the typed surface
+
+These `/v1` routes get no SDK method, with the reason. They are still reachable through `client.request()`.
+
+| Routes | Why |
+|---|---|
+| `/v1/focuses…` | A focus maps a node to a tmux pane. An SDK caller has no tmux. It stays on `/v1` for the viewer. |
+| `POST /v1/nodes/{id}/mail/claim`, `…/mail/acknowledge` | These are how a node's own broker takes delivery of its inbox. An external caller claiming another node's mail would consume deliveries that node then never sees. |
+| `POST /v1/nodes/{id}/attach` | Returns the host-local path to a broker's viewer socket. A remote or browser caller cannot open that path, and [Streaming](./streaming.md) is the application-facing way to watch a node. |
+| Broker operations, broker recovery, node faults | The broker's own control plane — session binding, settle directives, park completion, turn recording, provider-retry mutation, fault recording, model commit. They exist so the one process hosting a node can coordinate with crtrd about that node's runtime. An external caller invoking them introduces a second writer to state the broker and the daemon coordinate between themselves. |
+
+## The escape hatch
+
+Nothing on `/v1` is unreachable. A route that is excluded above, or one added to the daemon after this SDK version was published, is reachable directly:
+
+```ts
+client.request(method, path, body?, options?)
+```
+
+It carries the same authentication, the same retry policy, and the same error mapping as every generated method — it is untyped, not unsupported.
+
+```ts
+const focuses = await client.request<FocusDTO[]>('GET', '/v1/focuses');
+
+await client.request('POST', `/v1/nodes/${id}/some-new-route`, { field: 'value' }, { timeout: 5_000 });
+```
+
+If you find yourself reaching for `client.request()` for something an application genuinely needs, that route belongs in one of the tables above. Say so rather than building on the escape hatch.