@north-light/crouter 0.3.329 → 0.3.331

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

@@ -0,0 +1,112 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Errors, this knowledge should be read
+  because **An agent's own outcome is returned, never thrown.** A run that
+  declined the schema, hit its deadline, or crashed comes back as a settled
+  `NodeOutcome` from `waitForOutcome`, `createAndWait`, or `parse`. Narrow on it
+  — see [[crouter-sdk/nodes]].
+---
+
+# Errors
+
+## What throws and what does not
+
+**An agent's own outcome is returned, never thrown.** A run that declined the schema, hit its deadline, or crashed comes back as a settled `NodeOutcome` from `waitForOutcome`, `createAndWait`, or `parse`. Narrow on it — see [[crouter-sdk/nodes]].
+
+Exceptions are for the layer underneath: the SDK rejected an invalid local identifier or configuration, the daemon refused the request, the connection failed, the request timed out, or you aborted.
+
+## Classes and mappings
+
+Every class below extends `APIError`, which carries `status`, `code`, `message`, `details`, and `headers`.
+
+| Condition | Class |
+|---|---|
+| SDK configuration error | `CrouterError` with `status: 0`, `code: 'crouter_error'` |
+| HTTP 400 | `BadRequestError` |
+| HTTP 401 | `AuthenticationError` |
+| HTTP 403 | `PermissionDeniedError` |
+| HTTP 404 | `NotFoundError` |
+| HTTP 409 | `ConflictError` |
+| HTTP 413, 422 | `UnprocessableEntityError` |
+| HTTP 429 | `RateLimitError` |
+| HTTP 504 or code `request_timeout` | `APIConnectionTimeoutError` (extends `APIConnectionError`) |
+| Other HTTP ≥ 500 | `InternalServerError` |
+| Code `daemon_unavailable`, `transport_error`, `daemon_request_interrupted`, or `daemon_health_unavailable`; or a non-API transport failure | `APIConnectionError` |
+| Code `request_aborted` | `APIUserAbortError` |
+| Any other daemon response | `APIError` |
+
+A terminal SSE `error` event other than `stream_gap` rejects `NodeStream.finalOutcome()` and the iterator with `APIError` carrying that event's code, message, and details. `stream_gap` is delivered as an event and the stream continues. See [[crouter-sdk/streaming]].
+
+```ts
+import { ConflictError, NotFoundError, APIConnectionError } from '@north-light/crouter-sdk';
+
+try {
+  await client.nodes.create({ prompt, node_id: 'my-run-42' });
+} catch (error) {
+  if (error instanceof ConflictError && error.code === 'node_id_exists') {
+    // the run already exists — attach to it instead of spawning a second one
+    return client.nodes.waitForOutcome('my-run-42');
+  }
+  if (error instanceof NotFoundError) throw new Error('no such node');
+  if (error instanceof APIConnectionError) throw new Error('the daemon is not reachable');
+  throw error;
+}
+```
+
+The subclasses add **no fields**. `status` and `code` on the base class already decide everything there is to branch on. They exist so that `catch (error) { if (error instanceof NotFoundError) … }` — what an OpenAI SDK user writes without thinking about it — works here too.
+
+## Identifier validation
+
+The SDK validates path-segment identifiers before it makes a request. Invalid node ids, cron ids, bash-job ids, human-request ids, inbox ticket ids, provider names, and profile names throw `TypeError` locally. Node ids apply to core node calls, lifecycle calls, and nested node resources. `nodes.events()` returns a `NodeStream` synchronously, so its invalid-id `TypeError` rejects `stream.node`, `stream.finalOutcome()`, and iteration instead. File paths are not identifiers; invalid or relative file paths reach the daemon and return its mapped API error. `nodes.outcome(id, { wait })` separately throws `RangeError` when `wait` is not an integer from 0 through 25.
+
+## Memory requests
+
+| Condition | Class, status, and code |
+|---|---|
+| `retrieve` or `resolve` names a document that does not exist, including a document deleted earlier | `NotFoundError`, 404 `memory_document_not_found` |
+| `history` names a document with no document or revision history | `NotFoundError`, 404 `not_found` |
+| History is requested for a builtin or plugin document | `BadRequestError`, 400 `usage` |
+| A mutation directly sets protected frontmatter (`kind`, `when-and-why-to-read`, `origin`, or `last-updated`) | `BadRequestError`, 400 `invalid_request` |
+| An update would make no change | `BadRequestError`, 400 `usage` |
+| A node-targeted caller lacks `memory:read` or `memory:write` | `PermissionDeniedError`, 403 `scope_denied` |
+
+Invalid names, invalid scope combinations, invalid limits, builtin mutation selections, and invalid search combinations are also `BadRequestError` responses. Builtin and plugin documents cannot be mutated; no code should treat a 400 refusal as a successful write.
+
+## The wire body
+
+The daemon answers an error with:
+
+```json
+{ "error": { "code": "node_id_exists", "message": "…", "details": { } } }
+```
+
+`code` is the stable, machine-readable identity — `node_id_exists`, `daemon_unavailable`, `request_timeout`, `node_dormant`. Branch on it. There is no separate `type` field and no `param` field.
+
+## Retries
+
+`maxRetries` defaults to `2`, with exponential backoff. It applies to:
+
+- connection errors, and
+- HTTP 429 and 5xx responses, **on `GET`, `HEAD`, and `DELETE` only**.
+
+**`POST` and `PATCH` are never retried automatically.** Creating a node, delivering a message, and pushing a report are not idempotent, and a mutation whose response was interrupted may already have been applied — replaying it would spawn a second agent, deliver a second message, or push a second report.
+
+If you want a create that survives a retry, pass `node_id`. A duplicate then fails loudly with `409 node_id_exists` instead of quietly running twice:
+
+```ts
+const runId = `invoice-${invoice.id}`;
+
+try {
+  await client.nodes.create({ prompt, node_id: runId, root: true });
+} catch (error) {
+  if (!(error instanceof ConflictError && error.code === 'node_id_exists')) throw error;
+}
+
+const outcome = await client.nodes.waitForOutcome(runId);
+```
+
+Override the policy per request with `{ maxRetries: 0 }` or `{ maxRetries: 5 }`. Raising it on a `POST` still does not make the client retry that `POST`.
+
+## In-repo callers
+
+`ApiError` from `@north-light/crouter-api` is an alias of `APIError`, so existing crouter code and its transport checks keep working unchanged. Daemon handlers keep throwing `{ status, code, message }` and never name an SDK class — the hierarchy is one `status → constructor` table on the client side and nothing else depends on it.

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

@@ -0,0 +1,51 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need `client.files`, this knowledge should be
+  read because `client.files` reads, writes, and lists host files through the
+  daemon.
+---
+
+# `client.files`
+
+`client.files` reads, writes, and lists host files through the daemon.
+
+```ts
+const source = await client.files.read('/absolute/path/to/input.txt');
+const written = await client.files.write('/absolute/path/to/output.txt', source.content);
+const directory = await client.files.list('/absolute/path/to');
+```
+
+Every `path` is absolute. Relative paths and `~` are not expanded. File paths are sent to the daemon unchanged; the daemon checks that they are absolute and returns a mapped API error when they are not.
+
+Every method accepts ordinary request options in its final object: `headers`, `signal`, `timeout`, and `maxRetries`. `read` and `write` add `encoding`; `list` adds `limit`.
+
+## Read
+
+```ts
+await client.files.read(path, { encoding: 'utf8', timeout: 5_000 });
+await client.files.read(path, { encoding: 'base64' });
+```
+
+`read(path, options?)` returns `Promise<FilePeekDTO>`, `{ path, content, truncated }`, through `GET /v1/files/peek`. It captures at most 512 KiB of file bytes. `truncated: true` means `content` is only the prefix. Request `base64` for binary content.
+
+## Write
+
+```ts
+const result = await client.files.write(path, content, { encoding: 'utf8' });
+// result is { path, bytes_written }
+await client.files.write(path, bytes.toString('base64'), { encoding: 'base64' });
+```
+
+`write(path, content, options?)` returns `Promise<FileWriteDTO>`, `{ path, bytes_written }`. Writes create parent directories and atomically replace the target. If `path` is an existing symlink, the daemon resolves it and atomically replaces its destination; the symlink remains. Decoded content above 1 MiB is refused with `UnprocessableEntityError` carrying `status: 413` and `code: 'file_too_large'`; it is never truncated or partially written.
+
+## List
+
+```ts
+const result = await client.files.list(path, { limit: 100 });
+```
+
+`list(path, options?)` returns `Promise<FileListDTO>`, `{ path, entries, truncated }`, for one directory level. Each entry has `name`, `type: 'file' | 'dir' | 'other'`, `size`, and ISO-8601 `modified`. `limit` must be a positive integer; the default is 1000. `truncated: true` means the directory had more entries than the requested limit.
+
+## Authority
+
+The token is the owner credential. Anyone holding it can already create an agent with a bash tool, so these methods run with the daemon user's authority and do not provide a restricted file area.

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

@@ -0,0 +1,169 @@
+---
+kind: knowledge
+when-and-why-to-read: "When you need Getting started, this knowledge should be
+  read because 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."
+---
+
+# 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 [[crouter-sdk/client]]).
+
+## 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 [[crouter-sdk/errors]].
+
+## Where to go next
+
+- Every constructor option and environment-variable fallback: [[crouter-sdk/client]]
+- Checking the daemon connection and selected provider before a run: `client.auth.status()` above
+- The full create-parameter table and the outcome union: [[crouter-sdk/nodes]]
+- Watching a run as it works: [[crouter-sdk/streaming]]
+- Running the daemon in a container instead: [[crouter-sdk/docker]]

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

@@ -0,0 +1,88 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need `client.memory`, this knowledge should be
+  read because Phase 3. `client.memory` reads and writes the memory documents
+  that shape an agent run. Every call names its target; the daemon never uses
+  its own working directory or environment to select memory.
+---
+
+# `client.memory`
+
+Phase 3. `client.memory` reads and writes the memory documents that shape an agent run. Every call names its target; the daemon never uses its own working directory or environment to select memory.
+
+```ts
+const page = await client.memory.list({ node: nodeId, kind: 'knowledge', limit: 50 });
+const document = await client.memory.retrieve('insights/capture', { node: nodeId, frontmatter: true });
+```
+
+## Target
+
+```ts
+type MemoryScope = {
+  node?: string;
+  cwd?: string;
+  profile?: string;
+  store?: 'node' | 'project' | 'profile' | 'user' | 'builtin';
+};
+```
+
+Pass `node` to use that node's working directory and profile. Do not combine it with `cwd` or `profile`. With no target, only user and builtin memory are searched. `store` restricts the request to one memory tier; `store: 'node'` requires `node`, and `store: 'profile'` requires a profile target. `create` defaults to the nearest project store when one is available, otherwise the user store. `update`, `delete`, and `move` resolve the existing document through normal scope precedence when `store` is omitted. `builtin` is read-only.
+
+When a request supplies `node`, its node row must hold `memory:read` for `list`, `retrieve`, `search`, `history`, and `resolve`, or `memory:write` for `create`, `update`, `delete`, and `move`. Calls without `node` are external application calls and are not narrowed by a node scope list.
+
+## Methods
+
+Every method accepts `RequestOptions` as its final optional argument (`signal`, `timeout`, `maxRetries`, and `headers`). A document name can contain `/`; the SDK encodes it as one path segment.
+
+| Method | Parameters | Result |
+|---|---|---|
+| `memory.list(query?, options?)` | `MemoryScope & { kind?, limit?, after? }`; `limit` is 1–100 (default 100) | `MemoryPage<MemoryDocSummaryDTO>` |
+| `memory.retrieve(name, query?, options?)` | `name`; `MemoryScope & { frontmatter? }` | `MemoryDocDTO` |
+| `memory.create(params, options?)` | `MemoryDocCreateRequest` | `MemoryDocDTO` |
+| `memory.update(name, params, options?)` | `name`; `MemoryDocUpdateRequest` | `MemoryDocDTO` |
+| `memory.delete(name, scope?, options?)` | `name`; `MemoryScope` | `MemoryDocDeletedDTO` |
+| `memory.move(name, params, options?)` | `name`; `MemoryDocMoveRequest` | `MemoryDocMovedDTO` |
+| `memory.search(params, options?)` | `MemorySearchRequest` | `MemoryPage<MemorySearchHitDTO>` |
+| `memory.history(name, query?, options?)` | `name`; `MemoryHistoryQuery` | `MemoryHistoryDTO` |
+| `memory.resolve(name, scope?, options?)` | `name`; `MemoryScope` | `MemoryDocRefDTO` |
+
+`MemoryDocCreateRequest` requires `name`, `kind`, `when_and_why_to_read`, and `body`; it also accepts `frontmatter`, `extensions`, and the scope fields. `MemoryDocUpdateRequest` requires `rationale`, which is stored in revision history rather than document text, and optionally accepts `body`, `frontmatter`, `extensions`, `unset`, and the scope fields. `MemoryDocMoveRequest` requires `to` and accepts the scope fields.
+
+`retrieve` returns the body by default. With `frontmatter: true`, its `body` is the complete document source. `MemoryDocDTO` also contains `frontmatter`, `representation` (`'leaf-file'` or `'directory-index'`), `links`, and any lint `findings`; document DTOs include their canonical name, kind, scope, extensions, path, store root, physical relative path, and any competing candidates. `resolve` returns the winning document's location and optional plugin name without reading its body.
+
+```ts
+await client.memory.create({
+  name: 'billing/refund-policy',
+  kind: 'knowledge',
+  when_and_why_to_read: 'When handling a refund request, read this because the eligibility window is not in the order record.',
+  body: 'Refunds are available for 60 days.',
+  profile: 'my-app',
+});
+
+await client.memory.update('billing/refund-policy', {
+  rationale: 'The eligibility window changed on 2026-01-04.',
+  body: 'Refunds are available for 90 days.',
+  profile: 'my-app',
+});
+```
+
+The daemon returns document text without expanding shell blocks. Builtin and plugin documents are read-only. `kind`, `when-and-why-to-read`, `origin`, and `last-updated` cannot be set or removed directly. Each mutation writes a complete before/after history record; delete leaves a tombstone. `retrieve` and `resolve` return `NotFoundError` with status 404 and code `memory_document_not_found` for a deleted document or an unknown name. Concurrent writes are last-write-wins.
+
+`search` uses ranked search by default. Set `body: true` to include document bodies in ranking, or `grep: true` for regular-expression line matches; `grep` and `body` cannot be combined, and `min_score` is only available in ranked search. Ranked hits contain `kind`, `score`, and `short_form`; grep hits contain `line` and `text`.
+
+`history` returns newest-first revision summaries, optionally with `diff`, or the full before/after record for one `revision`. A delete leaves history available through its tombstone.
+
+## Pages
+
+`list` and `search` return `{ object: 'list', data, has_more }` as a `MemoryPage`. A page has `hasNextPage()`, `getNextPage()`, and is async iterable across every page. The list cursor is the final document's canonical name. Ranked search uses the final hit's name; grep uses an opaque cursor that includes the match location, which the SDK handles.
+
+```ts
+const page = await client.memory.search({ query: 'refund window', node: nodeId });
+for (const hit of page.data) console.log(hit.name);
+
+if (page.hasNextPage()) {
+  const next = await page.getNextPage();
+}
+
+for await (const hit of page) console.log(hit.name);
+```

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

@@ -0,0 +1,118 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Migration from `generate()` and `local()`,
+  this knowledge should be read because **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.
+---
+
+# 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 [[crouter-sdk/docker]] |
+| `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()` — [[crouter-sdk/streaming]] |
+| 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 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 [[crouter-sdk/resources]].