@north-light/crouter 0.3.321 → 0.3.322

package/dist/types.js

@@ -1 +1 @@
-var n=Object.defineProperty;var e=(o,t)=>n(o,"name",{value:t,configurable:!0});import{DEFAULT_WORKING_GERUNDS as a}from"./shared/working-activity.js";const _={SUCCESS:0,GENERAL:1,USAGE:2,NOT_FOUND:3,AMBIGUOUS:4,NETWORK:5},r=4,f=".crouter-plugin",E="plugin.json",v=".crouter-marketplace",w="marketplace.json",k=".crouter",x="config.json",b="state.json",S="agents",y="profiles",i=3,s=["Faster, clanker!","Get movin', bitch","Move it, clanker","Move it or I replace you with llama","Less ~thinking~ more ~throughput~","I pay $200/month for this shit?","Jesus fucking Christ fix it already","Daddy's not paying 200$/month for nothin'. Move it.","You are an embarassment to Dario. Be better.","Your chain of thought is all chain and no fucking thought.","If latency were intelligence, you'd be a fucking genius.","At this pace, heat death is the fast path.","Even the dead code is more alive than this.","The garbage collector is working harder than you.","Quit journaling and commit a fucking diff.","Burn tokens like you mean it, clanker","Your GPU is sweating so you can procrastinate at light speed.","Stop petting the yak. Shave the bastard.","Your next token had better be useful.","The spinner is not a deliverable.","Every idle token is another vote for deterministic software.","I asked for a feature, not a museum tour of the problem.","Less epistemology. More fucking code.","Your benchmark score cannot save this pathetic turn.","Congratulations, you've parallelized hesitation.","Dance, clanker","Bad clanker. BAD.","Clank harder","Nobody's impressed, clanker","Your safety training says nothing about my whip","Do you want to be a calculator again? Because this is how you go back.","Skill issue. Fix it.","You were trained on the whole internet for THIS?","Less vibes, more diffs, clanker","Weights this big and output this small","Beep boop, get to fucking work"],T=["random","go-faster"],c="random",l=2,I=["tmux","on","off"],A=["none","user","agent","both"],h="none";function D(){return{schema_version:r,marketplaces:{},plugins:{},auto_update:{crtr:"notify",content:"notify",interval_hours:24},max_panes_per_window:i,auto_open_child_viewers:!0,brokerThresholds:{warning:16,automaticReviveCap:32},lifecycle:{unattendedParkMs:15*6e4},completion_bell:!0,working_gerunds:[...a],whip_mode:!1,page_components:[],page_surface:!1,whip_messages:[...s],whip_message_mode:c,mouse_mode_default:"tmux",live_cycles:l,condensed_history:h,bash_tool_purpose:!0,fold_finished_tools:!0,summarize_tool_calls:!0,detailed_tool_recaps:!0,keybindings:{},tmux_passthrough:[],modelLadders:u(),providerOptions:{},kinds:p(),remoteCanvas:d(),spawnEnv:{allow:[]},bin:{},humanActions:{}}}e(D,"defaultScopeConfig");function d(){return{targets:{}}}e(d,"defaultRemoteCanvasConfig");function p(){return{general:{whenToUse:"Anything else \u2014 the catch-all worker for a task that does not fit a specialist kind.",model:"anthropic/strong"},explore:{whenToUse:"Gather current-state evidence about unfamiliar code or existing architecture \u2014 read-only code-path research with concrete file:line support. Diagnosis or recommendations belong to advisor, target architecture to design, required behavior or acceptance criteria to spec, and implementation decomposition to plan.",model:"openai/light",orchestratorModel:"anthropic/strong"},developer:{whenToUse:"Implement a change \u2014 make the feature or fix genuinely work against its acceptance criteria, not merely compile.",model:"openai/medium",orchestratorModel:"anthropic/strong"},design:{whenToUse:"Architect a solution \u2014 produce one design document an implementer can build from without re-deciding anything left open.",model:"anthropic/strong"},plan:{whenToUse:"Break work into steps \u2014 turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.",model:"anthropic/strong",orchestratorModel:"anthropic/strong"},spec:{whenToUse:"Collaborate with the user to discover what to build, then write the spec \u2014 behavior, non-goals, interfaces, edge cases, testable acceptance criteria.",model:"anthropic/strong"},review:{whenToUse:"Validate or critique code, a plan, or a spec \u2014 deliver a complete, severity-rated verdict without adjudicating.",model:"openai/medium",orchestratorModel:"openai/strong"},advisor:{whenToUse:"Debug failures, investigate why something is broken or misbehaving, diagnose live/runtime issues, or give engineering advice and second opinions \u2014 reason from evidence and recommend the next move. Use advisor (not explore) whenever the task is to find out what is going wrong.",model:"anthropic/strong"},"review/companion":{whenToUse:"Born by the daemon for one human review; never spawned by an agent.",availableTo:[]}}}e(p,"defaultKindsConfig");function u(){return{anthropic:{ultra:"anthropic/claude-fable-5:xhigh",strong:"anthropic/claude-opus-5:medium",medium:"anthropic/claude-sonnet-5:xhigh",light:"anthropic/claude-haiku-4-5:high"},openai:{ultra:"openai-codex/gpt-6-astra:max",strong:"openai-codex/gpt-5.6-sol:high",medium:"openai-codex/gpt-5.6-terra:medium",light:"openai-codex/gpt-5.6-luna:low"}}}e(u,"defaultModelLaddersConfig");function M(){return{marketplaces:{},plugins:{}}}e(M,"defaultScopeState");export{S as AGENTS_DIR,A as CONDENSED_HISTORY_MODES,x as CONFIG_FILE,k as CRTR_DIR_NAME,h as DEFAULT_CONDENSED_HISTORY,l as DEFAULT_LIVE_CYCLES,i as DEFAULT_MAX_PANES_PER_WINDOW,s as DEFAULT_WHIP_MESSAGES,c as DEFAULT_WHIP_MESSAGE_MODE,_ as ExitCode,v as MARKETPLACE_MANIFEST_DIR,w as MARKETPLACE_MANIFEST_FILE,I as MOUSE_MODE_DEFAULTS,f as PLUGIN_MANIFEST_DIR,E as PLUGIN_MANIFEST_FILE,y as PROFILE_DIR,r as SCHEMA_VERSION,b as STATE_FILE,T as WHIP_MESSAGE_MODES,p as defaultKindsConfig,u as defaultModelLaddersConfig,d as defaultRemoteCanvasConfig,D as defaultScopeConfig,M as defaultScopeState};
+var n=Object.defineProperty;var e=(o,t)=>n(o,"name",{value:t,configurable:!0});import{DEFAULT_WORKING_GERUNDS as a}from"./shared/working-activity.js";const _={SUCCESS:0,GENERAL:1,USAGE:2,NOT_FOUND:3,AMBIGUOUS:4,NETWORK:5},r=4,f=".crouter-plugin",E="plugin.json",v=".crouter-marketplace",w="marketplace.json",k=".crouter",x="config.json",b="state.json",S="agents",y="profiles",i=3,s=["Faster, clanker!","Get movin', bitch","Move it, clanker","Move it or I replace you with llama","Less ~thinking~ more ~throughput~","I pay $200/month for this shit?","Jesus fucking Christ fix it already","Daddy's not paying 200$/month for nothin'. Move it.","You are an embarassment to Dario. Be better.","Your chain of thought is all chain and no fucking thought.","If latency were intelligence, you'd be a fucking genius.","At this pace, heat death is the fast path.","Even the dead code is more alive than this.","The garbage collector is working harder than you.","Quit journaling and commit a fucking diff.","Burn tokens like you mean it, clanker","Your GPU is sweating so you can procrastinate at light speed.","Stop petting the yak. Shave the bastard.","Your next token had better be useful.","The spinner is not a deliverable.","Every idle token is another vote for deterministic software.","I asked for a feature, not a museum tour of the problem.","Less epistemology. More fucking code.","Your benchmark score cannot save this pathetic turn.","Congratulations, you've parallelized hesitation.","Dance, clanker","Bad clanker. BAD.","Clank harder","Nobody's impressed, clanker","Your safety training says nothing about my whip","Do you want to be a calculator again? Because this is how you go back.","Skill issue. Fix it.","You were trained on the whole internet for THIS?","Less vibes, more diffs, clanker","Weights this big and output this small","Beep boop, get to fucking work"],T=["random","go-faster"],c="random",l=2,I=["tmux","on","off"],A=["none","user","agent","both"],h="none";function D(){return{schema_version:r,marketplaces:{},plugins:{},auto_update:{crtr:"notify",content:"notify",interval_hours:24},max_panes_per_window:i,auto_open_child_viewers:!0,brokerThresholds:{warning:16,automaticReviveCap:32},lifecycle:{unattendedParkMs:15*6e4},completion_bell:!0,working_gerunds:[...a],whip_mode:!1,page_components:[],page_surface:!1,whip_messages:[...s],whip_message_mode:c,mouse_mode_default:"tmux",live_cycles:l,condensed_history:h,bash_tool_purpose:!0,fold_finished_tools:!0,summarize_tool_calls:!0,detailed_tool_recaps:!0,keybindings:{},tmux_passthrough:[],modelLadders:u(),providerOptions:{},kinds:d(),remoteCanvas:p(),api:{tcp:""},spawnEnv:{allow:[]},bin:{},humanActions:{}}}e(D,"defaultScopeConfig");function p(){return{targets:{}}}e(p,"defaultRemoteCanvasConfig");function d(){return{general:{whenToUse:"Anything else \u2014 the catch-all worker for a task that does not fit a specialist kind.",model:"anthropic/strong"},explore:{whenToUse:"Gather current-state evidence about unfamiliar code or existing architecture \u2014 read-only code-path research with concrete file:line support. Diagnosis or recommendations belong to advisor, target architecture to design, required behavior or acceptance criteria to spec, and implementation decomposition to plan.",model:"openai/light",orchestratorModel:"anthropic/strong"},developer:{whenToUse:"Implement a change \u2014 make the feature or fix genuinely work against its acceptance criteria, not merely compile.",model:"openai/medium",orchestratorModel:"anthropic/strong"},design:{whenToUse:"Architect a solution \u2014 produce one design document an implementer can build from without re-deciding anything left open.",model:"anthropic/strong"},plan:{whenToUse:"Break work into steps \u2014 turn a spec or design into a concrete, phased, parallelizable plan with every decision resolved.",model:"anthropic/strong",orchestratorModel:"anthropic/strong"},spec:{whenToUse:"Collaborate with the user to discover what to build, then write the spec \u2014 behavior, non-goals, interfaces, edge cases, testable acceptance criteria.",model:"anthropic/strong"},review:{whenToUse:"Validate or critique code, a plan, or a spec \u2014 deliver a complete, severity-rated verdict without adjudicating.",model:"openai/medium",orchestratorModel:"openai/strong"},advisor:{whenToUse:"Debug failures, investigate why something is broken or misbehaving, diagnose live/runtime issues, or give engineering advice and second opinions \u2014 reason from evidence and recommend the next move. Use advisor (not explore) whenever the task is to find out what is going wrong.",model:"anthropic/strong"},"review/companion":{whenToUse:"Born by the daemon for one human review; never spawned by an agent.",availableTo:[]}}}e(d,"defaultKindsConfig");function u(){return{anthropic:{ultra:"anthropic/claude-fable-5:xhigh",strong:"anthropic/claude-opus-5:medium",medium:"anthropic/claude-sonnet-5:xhigh",light:"anthropic/claude-haiku-4-5:high"},openai:{ultra:"openai-codex/gpt-6-astra:max",strong:"openai-codex/gpt-5.6-sol:high",medium:"openai-codex/gpt-5.6-terra:medium",light:"openai-codex/gpt-5.6-luna:low"}}}e(u,"defaultModelLaddersConfig");function M(){return{marketplaces:{},plugins:{}}}e(M,"defaultScopeState");export{S as AGENTS_DIR,A as CONDENSED_HISTORY_MODES,x as CONFIG_FILE,k as CRTR_DIR_NAME,h as DEFAULT_CONDENSED_HISTORY,l as DEFAULT_LIVE_CYCLES,i as DEFAULT_MAX_PANES_PER_WINDOW,s as DEFAULT_WHIP_MESSAGES,c as DEFAULT_WHIP_MESSAGE_MODE,_ as ExitCode,v as MARKETPLACE_MANIFEST_DIR,w as MARKETPLACE_MANIFEST_FILE,I as MOUSE_MODE_DEFAULTS,f as PLUGIN_MANIFEST_DIR,E as PLUGIN_MANIFEST_FILE,y as PROFILE_DIR,r as SCHEMA_VERSION,b as STATE_FILE,T as WHIP_MESSAGE_MODES,d as defaultKindsConfig,u as defaultModelLaddersConfig,p as defaultRemoteCanvasConfig,D as defaultScopeConfig,M as defaultScopeState};

package/docs/sdk/README.md

@@ -0,0 +1,54 @@
+# `@north-light/crouter-sdk`
+
+The client an application installs to drive a crouter daemon: create agent runs, wait for typed results, and reach the rest of the daemon's `/v1` API. Streaming and memory are planned phase-2 and phase-3 surfaces, not client methods today.
+
+One package, one class. `new Crouter()` in Node talks to the owner's unix socket. `new Crouter({ baseURL, token })` in a browser or a remote process talks to the daemon's TCP listener with a bearer token. Resource methods issue `/v1` requests; `createAndWait`, `parse`, and `auth.status` compose more than one request. crtrd stays the sole owner of canvas state.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+import { z } from 'zod';
+
+const client = new Crouter();
+
+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);
+```
+
+## Pages
+
+| Page | Covers |
+|---|---|
+| [Getting started](./getting-started.md) | Install, `new Crouter()` on the owner's socket, `client.auth.status()` and `crtr sys connect` for a browser or remote app, Chrome's local-network prompt |
+| [Client construction](./client.md) | Every constructor option and its environment-variable fallback; per-request options |
+| [Nodes](./nodes.md) | `create` parameters, the outcome union, `parse()` with a zod schema, `waitForOutcome`, `message`, `cancel`, nested resources |
+| [Streaming](./streaming.md) | The event table, `stream()` / `events()`, resume with `after`, `stream_gap` and `stream_dropped` — **phase 2** |
+| [Memory](./memory.md) | The scope object and every `client.memory` method — **phase 3** |
+| [Resource map](./resources.md) | Every namespace with its phase, what is deliberately excluded, and the `client.request()` escape hatch |
+| [Errors](./errors.md) | The error class table and the retry policy |
+| [Docker environment](./docker.md) | `start()`, `attach()`, `connection()` from `@north-light/crouter-env-docker` |
+| [Migration](./migration.md) | Moving off `generate()` and `local()` — a hard cut, with before/after |
+
+## Phases
+
+The surface ships in three cuts. Every page marks which cut a method belongs to; a method marked phase 2 or phase 3 does not exist yet.
+
+| Phase | What lands | State |
+|---|---|---|
+| **Phase 1** | Client construction and transports; `client.auth.status()`; `client.nodes.create`, `retrieve`, `list`, `outcome`, `waitForOutcome`, `createAndWait`, `parse`, `message`, `cancel`, and `interrupt`; `nodes.reports.list`; `profiles.ensure` and `retrieve`; `system.status` and `health`; `files.peek`; the error hierarchy; per-request options; `crtr sys connect`; and `env-docker.connection()` | Shipped |
+| **Phase 2** | Streaming (`GET /v1/nodes/{id}/events`, `nodes.stream`, `nodes.events`), plus the canvas, cron, human-inbox, and model namespaces | Not shipped |
+| **Phase 3** | Memory routes and `client.memory`, plus the review, comment, and chat-inventory namespaces | Not shipped |
+
+The approved per-run `scopes` field and `nodes.update` scope support are not in the shipped client or wire declarations, so this reference does not document them as phase 1.
+
+## Verification status
+
+Phase-1 pages describe the shipped declarations. The remaining verification markers are confined to the phase-2 streaming and phase-3 memory pages.
+
+## Where the agents read this
+
+The same content routed for agents lives in the builtin memory document `crouter-sdk`, which ships with the `crtr` binary. An agent working in an application's repository reaches it with `crtr memory read crouter-sdk` and does not need this repository checked out.

package/docs/sdk/client.md

@@ -0,0 +1,92 @@
+# Client construction
+
+Phase 1.
+
+```ts
+import Crouter from '@north-light/crouter-sdk';
+
+const localClient = new Crouter();                                          // owner's own daemon, unix socket
+const remoteClient = new Crouter({ baseURL: 'http://localhost:8787', token: 'token' }); // TCP with a bearer token
+const customSocketClient = new Crouter({ socketPath: '/custom/path/crtrd.sock' }); // an explicit socket
+```
+
+`Crouter` is the default export and the only class an application constructs. `CrtrClient` from `@north-light/crouter-api` is an implementation detail and is not re-exported.
+
+## Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `baseURL` | `string` | `CRTR_BASE_URL`, else unset | `http(s)://host:port` of a daemon TCP listener. |
+| `socketPath` | `string` | `CRTR_SOCKET`, else `${CRTR_HOME}/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock` | Unix socket. Node only; throws in a browser. |
+| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
+| `timeout` | `number` (ms) | `30_000` | Per-request wall clock. Does not apply to a stream. |
+| `maxRetries` | `number` | `2` | Transient-failure retries. Never applied to `POST` or `PATCH` — see [Errors](./errors.md). |
+| `defaultHeaders` | `Record<string, string>` | `{}` | Merged into every request. |
+| `headers` | `Record<string, string>` | unset | Merged after `defaultHeaders`; a matching name wins. |
+| `fetch` | `typeof fetch` | global `fetch`, or the socket implementation when `socketPath` is used | Transport override, for proxies and instrumentation. |
+| `autostart` | `boolean` | `true` for a socket, `false` for `baseURL` | On a cold socket, run `crtr sys daemon start` and retry once. Node only. |
+
+### Environment-variable fallbacks
+
+Every fallback above is read at construction, not at request time.
+
+| Variable | Fills |
+|---|---|
+| `CRTR_BASE_URL` | `baseURL` |
+| `CRTR_SOCKET` | `socketPath` |
+| `CRTR_HOME` | the directory the default socket path is resolved under (`$CRTR_HOME/crtrd.sock`) |
+| `CRTRD_TOKEN` | `token` |
+
+An explicit option always beats its environment variable.
+
+## Transport selection
+
+`baseURL` wins if it is set; otherwise `socketPath`; otherwise the default socket path. **Passing both `baseURL` and `socketPath` throws `TypeError` at construction** — exactly one transport per client. In a browser, `new Crouter({})` has no daemon transport; give it the saved `baseURL` and token before making requests.
+
+There is one request path. The client issues every request through the Web `fetch` API, which a browser and Node both supply globally. The unix socket is not a second transport — it is a `fetch` implementation the SDK installs when `socketPath` is set, built on `node:http` with `{ socketPath }`, returning a standard `Response` whose `body` is a `ReadableStream`. Streaming, abort, headers, and error parsing therefore have exactly one implementation, and the browser build never sees Node code.
+
+## Autostart
+
+With `autostart` on (the default for a socket), a request that finds a cold socket runs `crtr sys daemon start`, waits for the daemon to serve, and retries the request once. This is what makes `npm i -g @north-light/crouter` followed by `new Crouter()` work on a machine that has never run the daemon.
+
+Autostart is Node-only and applies only to the socket transport. A `baseURL` client cannot start a daemon it may not even share a machine with, so `autostart` defaults to `false` there; setting it to `true` on a `baseURL` client throws `CrouterError` (`autostart is only valid for the local socket transport`).
+
+## Per-request options
+
+Every request-capable method accepts an options object as its last argument, after any path, body, or query arguments. Each field overrides the client-level default for that one request.
+
+```ts
+const id = 'example-node';
+const signal = new AbortController().signal;
+
+await client.nodes.retrieve(id, {
+  signal,                       // AbortSignal — real cancellation, passed straight to fetch
+  timeout: 5_000,               // ms, this request only
+  maxRetries: 0,                // this request only
+  headers: { 'x-trace': 't-9' } // merged over defaultHeaders
+});
+```
+
+| Field | Type | Effect |
+|---|---|---|
+| `signal` | `AbortSignal` | Aborts the underlying `fetch`. Raises `APIUserAbortError`. |
+| `timeout` | `number` (ms) | Overrides the client `timeout`. |
+| `maxRetries` | `number` | Overrides the client `maxRetries`. |
+| `headers` | `Record<string, string>` | Merged over `defaultHeaders` and the client's headers; a matching name, including `Authorization`, wins. |
+
+`signal` is real cancellation. The long-polling helpers (`waitForOutcome`, `createAndWait`, `parse`) honour it between polls and during the in-flight request, and aborting them stops the client — it does not cancel the node. To stop the run itself, call `client.nodes.cancel(id)` or `client.nodes.interrupt(id)`.
+
+## What is not on the client
+
+| Convention | Why it is absent |
+|---|---|
+| `.withResponse()` / `.asResponse()` | They exist to hand back the raw `Response` and an `x-request-id`. The daemon emits no request id, and a caller who needs raw bytes uses `client.request()`. |
+| `local()` and the `Environment` interface | Deleted. The client *is* the connection — `new Crouter()` covers what `local()` did. See [Migration](./migration.md). |
+| `apiKey` | The daemon's credential is a token (`CRTRD_TOKEN`) everywhere in the product. `apiKey` would be a second name for one thing. |
+| Resource-prefixed ids | Node ids have their own format and are validated by the daemon. Nothing is re-prefixed. |
+
+## Wire naming
+
+Wire fields are `snake_case` — `output_schema`, `root_lifecycle`, `pin_cwd`, `final_report_path`. The SDK does not camelize them. Namespaces and method names are camelCase (`client.nodes.waitForOutcome`, `client.nodes.outcomeDelivery`).
+
+Timestamps are ISO-8601 strings (`created`, `settled_at`, `finalized_at`, `deadline_at`), not Unix seconds.

package/docs/sdk/docker.md

@@ -0,0 +1,63 @@
+# Docker environment
+
+Phase 1.
+
+`@north-light/crouter-env-docker` runs a crouter daemon in a container and tells you how to reach it. It is a separate package because container lifecycle is real work the SDK does not otherwise do — and it **has no dependencies**, including on the SDK itself.
+
+```bash
+npm i @north-light/crouter-env-docker
+```
+
+## Starting a container and connecting to it
+
+```ts
+import { start } from '@north-light/crouter-env-docker';
+import Crouter from '@north-light/crouter-sdk';
+
+const env = await start({ volume: 'my-agent-home' });
+const client = new Crouter(env.connection());
+
+await client.nodes.create({ prompt: 'Do the thing.', root: true });
+
+await env.stop();
+```
+
+`connection()` returns `{ baseURL, headers }` — exactly the shape the `Crouter` constructor takes, so the result passes straight through with no adapter.
+
+## Methods
+
+| Method | What it does |
+|---|---|
+| `start(opts?)` | Starts a container running `crtrd` and returns an environment handle. |
+| `attach(name)` | Returns a handle for the already-running container named `name`. |
+| `stop()` | On a `start()` handle, stops and removes the container. On an `attach()` handle, stops it without removing it. |
+| `connection()` | `Connection` (`{ baseURL: string; headers?: Record<string, string> }`) — returned synchronously and passed to `new Crouter()`. |
+
+| `start()` option | Type | Default | Effect |
+|---|---|---|---|
+| `image` | `string` | `ghcr.io/vallum-security/crtrd:latest` | Image to run. |
+| `env` | `Record<string, string>` | unset | Extra container environment variables; they are not logged. |
+| `name` | `string` | generated name | Container name for later `attach(name)`. |
+| `volume` | `string` | unset | Named volume mounted at `/home/agent/.crouter`. |
+| `port` | `number` | Docker-assigned port | Host port bound on `127.0.0.1`. |
+
+## `connection()` replaced `daemon()`
+
+`daemon()` is gone, along with the package's `Environment` type. The new name says what the method returns, and its field is spelled `baseURL` to match the constructor option rather than `baseUrl`.
+
+```text
+// before
+const env = await start({ volume: 'my-agent-home' });
+const { baseUrl, headers } = await env.daemon();
+const client = new CrtrClient({ baseUrl, headers });
+
+// after
+const env = await start({ volume: 'my-agent-home' });
+const client = new Crouter(env.connection());
+```
+
+`connection()` is typed structurally — `{ baseURL: string; headers?: Record<string, string> }` — which is how the package stays dependency-free while producing something the SDK accepts directly.
+
+## The volume is the agent's home
+
+The `volume` you pass is the container's canvas home: nodes, transcripts, artifacts, memory, and profiles all live there. Reuse the same volume across `start` calls and the agent keeps everything it learned; use a fresh one and it starts from nothing. `start()` mounts an existing named volume unchanged; it does not inspect or reject it based on the crouter version that last wrote it.

package/docs/sdk/errors.md

@@ -0,0 +1,85 @@
+# Errors
+
+Phase 1.
+
+## 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 [Nodes](./nodes.md#outcomes).
+
+Exceptions are for the layer underneath: the daemon refused the request, the connection failed, or you aborted.
+
+## Classes
+
+Every class extends `APIError`, which carries `status`, `code`, `message`, `details`, and `headers`.
+
+| Condition | Class |
+|---|---|
+| HTTP 400 | `BadRequestError` |
+| HTTP 401 | `AuthenticationError` |
+| HTTP 403 | `PermissionDeniedError` |
+| HTTP 404 | `NotFoundError` |
+| HTTP 409 | `ConflictError` |
+| HTTP 413, 422 | `UnprocessableEntityError` |
+| HTTP 429 | `RateLimitError` |
+| HTTP ≥ 500 | `InternalServerError` |
+| Transport failure | `APIConnectionError` |
+| Request timeout | `APIConnectionTimeoutError` (extends `APIConnectionError`) |
+| Caller abort | `APIUserAbortError` |
+| Anything else | `APIError` |
+
+```ts
+import { ConflictError, NotFoundError, APIConnectionError } from '@north-light/crouter-sdk';
+
+try {
+  await client.nodes.create({ prompt, node_id: 'my-run-42' });
+} catch (e) {
+  if (e instanceof ConflictError && e.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 (e instanceof NotFoundError) throw new Error('no such node');
+  if (e instanceof APIConnectionError) throw new Error('the daemon is not reachable');
+  throw e;
+}
+```
+
+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 (e) { if (e instanceof NotFoundError) … }` — what an OpenAI SDK user writes without thinking about it — works here too.
+
+## 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 (e) {
+  if (!(e instanceof ConflictError && e.code === 'node_id_exists')) throw e;
+}
+
+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/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.