@north-light/cli 0.0.0 → 0.3.413

package/dist/builtin-memory/crouter-sdk/guides/event-driven-assistant.md

@@ -0,0 +1,91 @@
+---
+kind: knowledge
+when-and-why-to-read: When an assistant must react to later webhook, queue, or
+  file-watcher events, read this because a resident node sleeps until
+  nodes.message delivers the next event.
+---
+
+# Event-driven assistant
+
+Use this recipe for an assistant that reacts to an event source instead of ending after one request. Run `npx tsx examples/guides/event-driven-assistant.ts /path/to/repo`, then type events into standard input to stand in for a webhook handler or file watcher.
+
+```ts
+import Crouter from '@north-light/sdk';
+import { resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const assistant = await client.nodes.create({
+  name: 'event assistant',
+  cwd,
+  model: process.env.GUIDE_MODEL,
+  root: true,
+  root_lifecycle: 'resident',
+  no_kickoff: true,
+  situational_context: `You are a standing assistant. Each inbox message is an event from an external source. For each event, briefly state what happened and one useful next action, then push that response as an update report with crtr push update. Do not push final. End the turn and go dormant after reporting. Do not poll or schedule a timer: another event will arrive as a message.`,
+});
+
+console.log(`assistant node: ${assistant.node_id}`);
+console.log('Type an event and press Enter. Press Ctrl-C to stop the assistant.');
+
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let stopping: Promise<void> | undefined;
+
+function stop(): Promise<void> {
+  if (stopping !== undefined) return stopping;
+  input.close();
+  stopping = client.nodes.cancel(assistant.node_id).then(() => undefined);
+  return stopping;
+}
+
+process.once('SIGINT', () => {
+  void stop().catch((error: unknown) => {
+    console.error(error);
+    process.exitCode = 1;
+  });
+});
+
+for await (const line of input) {
+  if (stopping !== undefined) break;
+  if (line.trim() === '') continue;
+  try {
+    const previous = (await client.nodes.reports.list(assistant.node_id, { limit: 1 }))[0]?.id;
+    if (stopping !== undefined) break;
+    await client.nodes.message(assistant.node_id, { body: line });
+    while (stopping === undefined) {
+      const report = (await client.nodes.reports.list(assistant.node_id, { limit: 1 }))[0];
+      if (stopping !== undefined) break;
+      if (report !== undefined && report.id !== previous) {
+        console.log(report.body);
+        break;
+      }
+      const state = await client.nodes.retrieve(assistant.node_id);
+      if (stopping !== undefined) break;
+      if (state.fault?.retry.disposition === 'fatal' || state.status === 'dead' || state.status === 'canceled') {
+        throw new Error(`assistant stopped without reporting: ${state.fault?.message ?? state.status}`);
+      }
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+  } catch (error) {
+    if (stopping === undefined) throw error;
+  }
+}
+
+await stop();
+```
+
+The external source owns detection. When it receives an event, it calls `nodes.message(nodeId, { body })`. `no_kickoff` leaves the resident node waiting for the first event, while `situational_context` tells it how to handle every event. A dormant resident node wakes for the message; a running node reads it at its next turn boundary. Keep the returned node id with the application so each later event reaches the same context and memory. The agent pushes one update report per event, which the application reads through `nodes.reports.list` and prints. The application checks for a fatal node fault rather than waiting forever for a report that cannot arrive.
+
+The agent does not poll or schedule a timer: the daemon wakes it on each message, and it goes dormant after reporting. This console program polls for the report associated with the event it just sent; an application with its own event loop can also consume the node's event stream. Ctrl-C calls `nodes.cancel()` only because this interactive example needs an explicit way to stop.
+
+Observed against the local daemon with `GUIDE_MODEL=openai-codex/gpt-6-sol:high` after sending `Build completed with 2 failing checks: lint and unit tests.`:
+
+```text
+assistant node: 3zl47w7d-mud5amcx-67978c9b
+Type an event and press Enter. Press Ctrl-C to stop the assistant.
+The build completed, but **lint and unit tests failed**. Inspect the two failing check logs first to identify the errors.
+```
+
+Use a resident node only when future events belong to the same ongoing assistant. For bounded work, use [[crouter-sdk/guides/typed-extraction]]. See [[crouter-concepts/lifecycle-and-wakes]] for why waiting is free and [[crouter-concepts/why-a-daemon]] for why the process can outlive the terminal that started it.

package/dist/builtin-memory/crouter-sdk/guides/fan-out-pipeline.md

@@ -0,0 +1,57 @@
+---
+kind: knowledge
+when-and-why-to-read: When independent parts of one job need separate agent work
+  before one synthesis, read this because an orchestrator can spawn children,
+  wait for reports, and publish a final result while the SDK streams progress.
+---
+
+# Fan-out pipeline
+
+Use this recipe when one result needs independent investigation first. Run `npx tsx examples/guides/fan-out-pipeline.ts /path/to/repo`; it asks an orchestrator to inspect a package through two children, prints live text and pushed reports, then prints the final reports retained on the node.
+
+```ts
+import Crouter from '@north-light/sdk';
+import { resolve } from 'node:path';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const stream = client.nodes.stream({
+  name: 'research pipeline',
+  cwd,
+  root: true,
+  root_lifecycle: 'terminal',
+  mode: 'orchestrator',
+  deadline: '10m',
+  prompt: `Research the package in this directory. Spawn two focused children: one should inspect package.json and one should inspect the README. Wait for their reports, reconcile them, then push a final report with the package name, purpose, and one risk or unknown.`,
+});
+
+const node = await stream.node;
+console.log(`orchestrator node: ${node.node_id}`);
+
+for await (const event of stream) {
+  if (event.type === 'node.output_text.delta') process.stdout.write(event.delta);
+  if (event.type === 'node.report.pushed') console.log(`\nreport: ${event.report.body}`);
+}
+
+const outcome = await stream.finalOutcome();
+const reports = await client.nodes.reports.list(node.node_id, { limit: 10 });
+console.log(`\nfinal outcome: ${outcome.kind}`);
+for (const report of reports) console.log(`[${report.tier}] ${report.body}`);
+
+if (outcome.kind !== 'result') process.exitCode = 1;
+```
+
+`nodes.stream()` creates the orchestrator and observes it. It does not run the orchestration in your process: the node owns its children, waits for their pushed reports, and produces the synthesis. The stream gives your application live output and reports; `nodes.reports.list()` gives it the durable report view after settlement.
+
+Keep orchestration inside the canvas when children need the canvas's report delivery, durable waits, and a parent that can be inspected or resumed. Keep it in your application when tasks are simple independent calls and the application already owns their scheduling and aggregation. Do not use an orchestrator merely because a task is long; it earns the extra structure only when child work can run independently.
+
+A local run created `j6amiqxs-mud4drnk-330da196`; after its two children reported, `waitForOutcome()` returned:
+
+```text
+{ "kind": "result", "reason": "finalized" }
+```
+
+The same run's `nodes.stream()` observer ended during a dormant gap before it could print this outcome. A separate daemon fix is correcting that observer behavior; the example remains the intended streamed shape, but its streamed path has not yet been observed end to end.
+
+See [[crouter-concepts/nodes-and-the-canvas]] for reports and durable identities, and [[crouter-concepts/profiles-kinds-and-modes]] for the base-versus-orchestrator decision.

package/dist/builtin-memory/crouter-sdk/guides/human-approval.md

@@ -0,0 +1,79 @@
+---
+kind: knowledge
+when-and-why-to-read: When a person must approve or reject work before an agent
+  continues, read this because the SDK can create an inbox request whose answer
+  wakes the requesting node.
+---
+
+# Human approval
+
+Use this recipe when a decision belongs to a person, not a timeout or an agent guess. Run `npx tsx examples/guides/human-approval.ts /path/to/repo`; it prints an inbox ticket id. Answer the page in the crtr human inbox and the worker wakes with that answer before it reports its result.
+
+```ts
+import Crouter from '@north-light/sdk';
+import { resolve } from 'node:path';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const worker = await client.nodes.create({
+  name: 'approval worker',
+  cwd,
+  root: true,
+  root_lifecycle: 'terminal',
+  no_kickoff: true,
+});
+
+const request = await client.human.requests.create({
+  creator_cwd: cwd,
+  requester_node_id: worker.node_id,
+  delivery: { placement: 'panel', inbox: true, reply: true },
+  page: {
+    dialect: 'jsx',
+    source: `export default function Approval() {
+  return (
+    <Page title="Approve the release?" subtitle="The worker will continue with your choice.">
+      <UserQuestion
+        id="approval"
+        label="Release action"
+        body="Approve to continue the release, or reject to stop it."
+        mode="single"
+        options={[
+          { id: 'approve', label: 'Approve', recommended: true },
+          { id: 'reject', label: 'Reject' },
+        ]}
+      />
+    </Page>
+  );
+}`,
+  },
+});
+
+const ticket = await client.human.requests.retrieve(request.request_id);
+if (ticket.inbox_ticket_id === null) throw new Error('the approval request was not added to the inbox');
+
+await client.nodes.message(worker.node_id, {
+  body: `A human approval request is open. Wait for its reply. When it arrives, state whether the release was approved or rejected, then push a final report.`,
+});
+
+console.log(`approval ticket: ${ticket.inbox_ticket_id}`);
+console.log('Answer it in the crtr human inbox. The worker will wake with the response.');
+
+const outcome = await client.nodes.waitForOutcome(worker.node_id);
+console.log(`worker outcome: ${outcome.kind}`);
+if (outcome.kind !== 'result') process.exitCode = 1;
+```
+
+The application creates the page through `client.human.requests.create()` and names the worker as `requester_node_id`. `delivery.reply: true` makes the settled answer travel back to that node. The page's `UserQuestion` supplies a known response shape, so the person sees an explicit approve or reject decision instead of an unstructured prompt.
+
+The worker is terminal because this is a bounded approval run: it waits after setup, wakes when the person answers, then publishes its final result. The pending human request keeps that wait durable. The application does not poll the node or invent a fallback deadline; the human reply is a canvas event. `client.human.inbox` can list, inspect, and answer inbox tickets when your application provides its own human interface.
+
+Observed against the local daemon after an approve response:
+
+```text
+approval ticket: a643479ca7a79758bf86f32d24bd8c9b22e16509cd60996c5e4fe0bc5f097d45
+Answer it in the crtr human inbox. The worker will wake with the response.
+worker outcome: result
+```
+
+See [[crouter-concepts/lifecycle-and-wakes]] for the wake model and [[crouter-concepts/scopes-and-trust]] for why the daemon, rather than the application, owns delivery of the answer.

package/dist/builtin-memory/crouter-sdk/guides/typed-extraction.md

@@ -0,0 +1,55 @@
+---
+kind: knowledge
+when-and-why-to-read: When an application needs one bounded structured answer
+  with no follow-up, read this because nodes.parse returns a typed outcome union
+  instead of hiding agent failures.
+---
+
+# Typed extraction
+
+Use this recipe to extract a small fact set from files in one working directory. Run it with `npx tsx examples/guides/typed-extraction.ts /path/to/repo`; it prints a package name and version or exits with an explicit agent outcome.
+
+```ts
+import Crouter from '@north-light/sdk';
+import { resolve } from 'node:path';
+import { z } from 'zod';
+
+const client = new Crouter();
+const cwd = resolve(process.argv[2] ?? process.cwd());
+
+const extraction = await client.nodes.parse({
+  prompt: 'Read package.json in this directory. Return its name and version.',
+  cwd,
+  root: true,
+  root_lifecycle: 'terminal',
+  deadline: '5m',
+  output_schema: z.object({
+    name: z.string(),
+    version: z.string(),
+  }),
+});
+
+if (extraction.kind === 'result') {
+  console.log(`package ${extraction.output_parsed.name}@${extraction.output_parsed.version}`);
+} else if (extraction.reason === 'declined') {
+  console.error(`agent declined: ${extraction.declined?.reason ?? 'no reason supplied'}`);
+  process.exitCode = 2;
+} else {
+  console.error(`agent failed: ${extraction.reason}`, extraction.detail);
+  process.exitCode = 1;
+}
+```
+
+`nodes.parse()` creates a terminal root, waits for it, and returns the structured result typed from the Zod schema. The schema belongs at the boundary where your application consumes the answer, not in a second parser after the run.
+
+Observed against the local daemon in this checkout:
+
+```text
+package @north-light/cli@0.3.332
+```
+
+Handle every outcome arm. A result contains `output_parsed`; a decline says the agent could not honestly meet the schema; another failure carries its reason and detail. Transport and daemon failures still throw, so let those reach your normal application error handling.
+
+**From an app.** An app holding a person's connection does the same thing with `runs.parse({prompt, output_schema})`, which returns the run outcome union (`finalized` with `output_parsed` typed from the schema, `declined` with `details`, `canceled`, `deadline_exceeded`, `runtime_error`). It also covers `run_idle` and questions. See [[crouter-sdk/guides/apps-on-crouter-cloud]].
+
+This is the right shape for bounded work: one prompt, one answer, and no future message. If a user or external event must return to the same agent later, use a resident node instead. See [[crouter-concepts/nodes-and-the-canvas]] for why an SDK node has durable identity, and [[crouter-concepts/lifecycle-and-wakes]] for the terminal-versus-resident decision.

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

@@ -0,0 +1,49 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Memory, this knowledge should be read
+  because Read the person's public documents — knowledge and preferences about
+  you — from an app's server with client.memory.
+---
+
+# `client.memory`
+
+`client.memory` is the SDK's read-only view of the person's documents: the `knowledge` and `preference` documents owned by the person on the canvas (the same objects `crtr canvas read` shows them). The `memory` name and the `/v1/memory` routes are the API's names for this. An app reads the person's `public` documents with `memory.list` and `memory.get`, and needs no scope to do it. It never sees a `friends` or `private` memory, and cannot tell one from a memory that does not exist: both answer `404 not_found`. This list is what the app's agents can read in memory about you, so an app can show the person exactly which of their memories its agents draw on.
+
+```ts
+const page = await client.memory.list({ store: 'user' });
+for (const item of page.items) console.log(item.name, item.preview);
+
+const doc = await client.memory.get({ store: 'user', name: page.items[0].name });
+console.log(doc.body);
+```
+
+`store` is `'user'` (memory about you) in this release; any other value answers `400 invalid_request` with `param: "store"`. An app whose grant holds `crtr:memory:manage:user` (a first-party app) sees every privacy level.
+
+Reading records nothing: no watch, no `read` event, no audit row. Both methods are `GET` requests and follow the SDK's retry rule for safe requests.
+
+## List
+
+`list({store, path?, kind?, limit?, cursor?}, options?)` sends `GET /v1/memory` and returns `Promise<MemoryListPage>`, `{items, next_cursor}`.
+
+| Field | Meaning |
+|---|---|
+| `path` | A folder: lists documents whose name starts with `<path>/`, at any depth |
+| `kind` | `knowledge` or `preference`; both when omitted |
+| `limit` | 1 to 100; default 50 |
+| `cursor` | The previous page's `next_cursor`, with the same `store`, `path` and `kind` |
+
+Items are ordered by `name`. Each `MemoryListItem` is `{name, folder, kind, preview, summary, privacy, revision, created_at, updated_at}`: `name` has no `user/` prefix, `folder` is the name up to its last `/` (`""` at the top level), and `updated_at` is the current revision's time. Folders are not items, and deleted and unlisted documents are left out. `next_cursor` is `null` on the last page.
+
+`listAll(params, options?)` takes the same fields without `cursor` and yields every item across pages, fetching the next page only as you iterate; stop early with `break`:
+
+```ts
+for await (const item of client.memory.listAll({ store: 'user', path: 'work' })) render(item);
+```
+
+## Get
+
+`get({store, name}, options?)` sends `GET /v1/memory/document` and returns `Promise<MemoryDocument>`: a list item's fields plus `body`, `size`, `truncated` and `grantee`.
+
+- `body` is the current markdown as stored; `[[links]]` are not resolved. A body over 1 MiB is cut to its longest whole-character prefix of at most 1 MiB, with `truncated: true`; `size` is always the full length in UTF-8 bytes.
+- `grantee` is `app:<id>` of the app whose agent wrote the first revision, or `null` when the person wrote it.
+- An absent, deleted, `friends` or `private` name rejects with `NotFoundError` (`code: 'not_found'`); a malformed field rejects with `BadRequestError`.

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

@@ -0,0 +1,195 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Nodes, this knowledge should be read because
+  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 | [[crouter-sdk/streaming]]. |
+| `nodes.events(id, options?)` | `GET /v1/nodes/{id}/events` | Shipped | [[crouter-sdk/streaming]]. |
+
+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 [[crouter-sdk/getting-started]]. |
+| `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 [[crouter-sdk/errors]].
+
+## 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 [[crouter-sdk/streaming]] 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.