@north-light/cli 0.0.0-stage → 0.3.413

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

@@ -0,0 +1,113 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Errors, this knowledge should be read
+  because Handle API and connection errors separately from settled agent
+  outcomes.
+---
+
+# 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.
+
+An error without `origin` was produced by the SDK because the request reached no server (runtime, router, or directory). Show it as a connection failure, never as a refusal. An OAuth ID token that fails verification (signature, issuer, audience, expiry, or a missing or mismatched nonce), or a sign-in-only answer with no ID token, raises the SDK-only `CrouterError` code `id_token_invalid`. A directory JWKS that can't be fetched or is malformed is not `id_token_invalid`: that error is thrown as is. `oauth_exchange_mismatch` means the wrong exchange call was used: `exchangeCode` on a sign-in-only answer, or `exchangeIdentity` on an answer that carries a connection. `oauth_nonce_missing` means `exchangeIdentity` was called without the `nonce` from `authorizeUrl`. `not_connected` means `oauth.client(userId)` (or a refresh) found no stored connection for that person: show "sign in again". `refusal_handler_reentry` means an `onRefusal` handler called `oauth.client` (or a refresh) for the same person whose connection was just refused; see [[crouter-sdk/client]]. When the directory refuses the app's client assertion (`invalid_client`) on `exchangeCode`, a refresh, or `revoke`, `OAuth2Client` throws an `APIError` with code `unauthorized` and status 401. It is an `AuthenticationError`, including when the refusal comes from the token refresh inside a client returned by `oauth.client(userId)`. The message names the key id (`kid`) the SDK signed with and asks whether that key's public JWK is registered on the app's Sign-in tab. `details` is `{oauth_error: 'invalid_client', kid}`. For a key with no `kid`, `kid` is `null` and `details.key_thumbprint` holds the key's RFC 7638 thumbprint instead. See [[crouter-sdk/getting-started]].
+
+Every code the SDK raises itself is listed in `sdkErrorCodes`, and `CrouterError.code` is typed `SdkErrorCode`; both are exported from `@north-light/sdk/errors` alongside the daemon's `errorCodes` / `ErrorCode`. That subpath also exports `mapError(error)`, which turns a plain `APIError` into its status class below (`NotFoundError`, `ConflictError`, …), for test doubles that build errors by hand.
+
+For the full app-facing HTTP envelope and the SDK's fixed code tuples, see [[crouter-sdk/error-envelope]]. The socket/v0 wire body below is deliberately smaller.
+
+## 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'` |
+| The runtime is older than the SDK, or names no version. The hosting router or the runtime can refuse this *before* handling (the SDK sends `Crouter-Minimum-Runtime-Version`): nothing was accepted and no idempotency key was recorded. A hosted runtime is always refused first once the hosting router has this check. Only a runtime that is not behind such a router and is older than the check release handles the request first, and then the SDK raises after | `RuntimeVersionError` with `status: 426`, `code: 'runtime_version_unsupported'`; `sdkVersion` and `runtimeVersion` (or `null`) name both, and it is never retryable. See [[crouter-sdk/release-notes]] |
+| 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/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.
+
+## Scoped tokens
+
+| Condition | Class, status, and code |
+|---|---|
+| The bearer token's ceiling lacks the scope a route needs, or `nodes.create` asks for `scopes` outside it (`details.scopes` lists them) | `PermissionDeniedError`, 403 `scope_denied` |
+| A scoped token reaches an owner-only route (daemon restart, attach, broker internals, canvas prune, profile pause/resume/delete, model credential install) | `PermissionDeniedError`, 403 `owner_only` |
+
+## 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 not retried automatically, with two exceptions: `runs.start` and `runs.message`.** Creating a node 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 or push a second report.
+
+`runs.start` and `runs.message` carry an `Idempotency-Key` header: the SDK generates one key per call (or uses the `idempotencyKey` option you pass) and reuses it on every retry of that call. The daemon records the key in the same transaction that accepts the request and holds it for 24 hours, so a retry after a lost response returns the original result and delivers once. Reusing a key with a different body is refused with `409 idempotency_conflict`. Both calls retry transport failures and retryable refusals. A key the SDK generates does not survive a restart of your process: to dedupe a send across restarts, derive `idempotencyKey` from your own message id.
+
+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` other than `runs.start` and `runs.message` still does not make the client retry that `POST`.
+
+## In-repo callers
+
+`ApiError` from `@north-light/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,50 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Files, this knowledge should be read because
+  Read, write, and list 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,226 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Getting started, this knowledge should be
+  read because Connect to a local or remote daemon and run your first agent with
+  the SDK.
+---
+
+# 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/cli
+```
+
+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/sdk
+```
+
+One dependency. It re-exports every data type you need, so you do not also install `@north-light/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/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. There are two kinds. The **owner token** is the owner credential: whoever holds it can drive the whole surface. A **scoped token** (`crtr sys connect --app <id> --scopes …`) carries a list of scopes that caps what its holder and every run it creates may do.
+
+### 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>"}
+```
+
+### A token that holds less than the owner
+
+```bash
+crtr sys connect --app my-app --scopes crtr:llm,crtr:act,crtr:memory:read:user
+```
+
+`--scopes` requires `--app` (the app id, without the `app:` prefix) and accepts only `crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:read:user`, `crtr:memory:read:app`, `crtr:memory:rw:app`, `crtr:files:read:user:.` and `crtr:files:rw:user:.`. This mints a new token for that app whose scope list is a ceiling, appends it to the same secrets store, prints it in place of the owner token, and always hands the daemon over (it reads tokens once, at boot). The ceiling is checked on every request that carries the token:
+
+- A scope-gated operation the ceiling lacks answers `403 scope_denied`. Creating, reviving, forking, messaging, or yielding a node needs `crtr:act`, as do `bash`, `files`, and creating a human request or review (there is no separate scope for human requests); arming or running a cron needs `crtr:schedule`; `/v1/llm` needs `crtr:llm`. `client.memory` has no scope of its own: it reads the person's documents filtered by privacy, and a grant holding `crtr:memory:manage:user` sees every level.
+- `nodes.create` with `scopes` outside the ceiling answers `403 scope_denied`; `details.scopes` lists the offending scopes. Omit `scopes` and the run gets the ceiling.
+- Owner-only operations — daemon restart, the attach viewer, broker internals, canvas prune, profile pause/resume/delete, model credential install — answer `403 owner_only` to any scoped token.
+
+What a scope does **not** do on a developer's machine: there is no OS sandbox. Scopes gate the daemon and the CLI; a run's own bash tool is ungated, and the daemon identifies a calling node by a field the caller declares, so a scope check bounds a well-behaved agent, not a hostile one. A scope the daemon does not check at any route is recorded on the run but not enforced; `sys connect` mints only the scopes listed above. There is no list or revoke verb yet; to retire a scoped token, remove it from the 0600 user secrets store and restart the daemon.
+
+### 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/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]].
+
+## Go live with an app key
+
+Register your app in the directory console, then generate its signing key on your app server:
+
+```bash
+npx @north-light/sdk keygen --app <client id>
+```
+
+This creates `local/app-key.json` with mode `0600` (keep it out of git) and prints the public JWK on stdout. With `--app`, `keygen` offers to add that public key to your app through your own `crtr` (`crtr cloud apps keys add`). It asks first and `--yes` skips the question; with no terminal to ask on (CI, piped input) and no `--yes`, it adds nothing. The upload only ever adds a key: it never replaces or retires the key your app already has. If `crtr` isn't installed or the add fails, `keygen` says why and prints the manual steps instead: click **Add key** on your app's **Sign-in** tab and paste the public JWK, or paste it under **Register an app** for a new app. An app authenticates only with its key: the directory issues no client secret. Use the saved private JWK for the OAuth connect flow:
+
+```ts
+import {readFile} from 'node:fs/promises';
+import {OAuth2Client} from '@north-light/sdk';
+
+const privateKey = JSON.parse(await readFile('local/app-key.json', 'utf8'));
+const oauth = new OAuth2Client({clientId, issuer, redirectUri, privateKey, store}); // store: your ConnectionStore
+const {url, codeVerifier, state, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:llm', 'crtr:act'], state: sessionState});
+// Save codeVerifier, state, nonce in the user's session; redirect them to url.
+const connection = await oauth.exchangeCode({code: callbackCode, codeVerifier, state: callbackState, expectedState: state, nonce});
+await store.save(connection);
+const client = await oauth.client(connection.userId); // Refreshes through the store from here on.
+```
+
+The directory accepts this key only after its public JWK is added to the app. Until then every `exchangeCode` and refresh throws an `AuthenticationError` (`code: 'unauthorized'`, status 401). Its message names the key id the SDK signed with and asks whether that key's public JWK is registered, and `error.details.kid` carries the same id.
+
+### Rotating your key
+
+An app can hold two active keys at once, and the directory accepts a sign-in signed by either one, so rotating a key has no downtime. Rotate in four steps:
+
+1. **Add the new key.** Generate it beside the current key file and add it to the app:
+
+   ```bash
+   npx @north-light/sdk keygen --out local/app-key-next.json --app <client id>
+   ```
+
+   Or run it without `--app` and paste the printed public JWK with **Add key** on the app's **Sign-in** tab. Both keys now work.
+2. **Switch.** Point `privateKey` at `local/app-key-next.json` and deploy.
+3. **Verify.** Complete one real sign-in through the callback, or refresh a stored connection. Opening your login route only redirects to the directory; it never reaches the token endpoint, so it proves nothing about the key.
+4. **Retire the old key.** On the **Sign-in** tab, or with `crtr cloud apps keys retire --app-id <client id> --kid <old kid>` (`crtr cloud apps keys list --app-id <client id>` shows the kids). Then delete the old key file.
+
+Until step 4 the old key is your rollback: point the app back at the old file and deploy. After you retire it, a sign-in signed with the old key fails with an `unauthorized` error that names the key as retired.
+
+An app registered with a **JWKS URL** instead of added keys rotates the same way through the URL: publish the new key there beside the old one, switch the app, verify, then remove the old key from the URL. The directory re-reads the URL within about a minute.
+
+## Where to go next
+
+- A complete local page that demonstrates streaming, structured output, and a plugin: localhost SDK demo (`examples/localhost-demo` in the crouter repository)
+- 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/guides/README.md

@@ -0,0 +1,20 @@
+---
+kind: knowledge
+when-and-why-to-read: When composing crouter SDK namespaces into an application,
+  read this because it helps you choose a complete runnable starting point.
+---
+
+# SDK recipes
+
+These recipes turn the SDK namespaces into complete applications: a bounded extraction, an assistant that waits for events, a research pipeline, a human approval step, and application-owned documents.
+
+| Recipe | Use it when | It ends with |
+|---|---|---|
+| [[crouter-sdk/guides/typed-extraction]] | You need one structured answer and no follow-up. | A typed object or an explicit failure. |
+| [[crouter-sdk/guides/event-driven-assistant]] | Events arrive over time from a webhook, queue, or watcher. | A resident node that wakes for each event. |
+| [[crouter-sdk/guides/fan-out-pipeline]] | One task needs independent research before a synthesis. | An orchestrator's final report. |
+| [[crouter-sdk/guides/human-approval]] | A person must decide before work continues. | A node resumed by an inbox answer. |
+| [[crouter-sdk/guides/apps-on-crouter-cloud]] | Your app starts runs on a person's runtime and needs typed data back. | A validated result from `runs.parse`, or an explicit decline or `run_idle`. |
+| [[crouter-sdk/guides/apps-with-many-users]] | People interact using separate runtime connections. | App-owned access controls, attribution, and per-person spending. |
+
+Start with typed extraction for a request/response job. Use a resident node when the same assistant should react again later. Use an orchestrator only when child work can proceed independently; otherwise keep the composition in your application.

package/dist/builtin-memory/crouter-sdk/guides/apps-on-crouter-cloud.md

@@ -0,0 +1,117 @@
+---
+kind: knowledge
+when-and-why-to-read: When an app starts runs on a person's runtime and needs
+  data back from the agent, read this because runs.parse returns a typed,
+  validated result and the transcript is not a data channel.
+---
+
+# Apps on crouter cloud
+
+An app holding a person's connection starts runs on their runtime with `runs.start`, follows them with `runs.events` or `runs.reply`, and reads them with `runs.get`. This page covers getting data back from a run. For connections and per-person access, see [[crouter-sdk/guides/apps-with-many-users]].
+
+## Getting a result back from a run
+
+Pass an `output_schema` and call `runs.parse`. The runtime arms the schema on the run's root agent. The agent must submit a value that validates against it. The run settles with that value, and `runs.parse` returns it as `output_parsed`, typed from your schema:
+
+```ts
+import {z} from 'zod';
+
+const Profile = z.object({
+  display_name: z.string(),
+  bio: z.string(),
+  facts: z.array(z.string()),
+});
+
+const outcome = await crouter.runs.parse({
+  prompt: 'Draft a public profile for me from my notes.',
+  output_schema: Profile,
+});
+
+if (outcome.kind === 'result') {
+  saveProfile(outcome.output_parsed); // {display_name, bio, facts}, typed from Profile
+} else if (outcome.reason === 'declined') {
+  // The agent could not honestly satisfy the schema.
+  const {reason, code, retryable} = outcome.details ?? {reason: 'declined', code: 'declined', retryable: false};
+  showDecline(reason, code, retryable);
+} else {
+  // canceled, deadline_exceeded, or runtime_error (details.crouter_reason)
+  showFailure(outcome.reason);
+}
+```
+
+The runtime validates the value before it records it. A submission that does not match is refused with its field errors and never appears in `runs.get`, an event, or a report, so the agent fixes it and resubmits. `output_schema` accepts a plain JSON Schema object or anything with `toJSONSchema()`, such as a Zod v4 object. The SDK sends it as a JSON object and validates nothing itself. A schema that is not an object, or is over 256 KB serialized, is refused with `invalid_request` and `param: 'output_schema'`, and no run is created. A submitted result can be at most 1 MiB. The agent submits with its `submit_result` tool, which needs no scope, so a run that only reasons and answers can be started with `scopes: ['crtr:llm']`. The same value is in `runs.get(runId).result`, which `runs.wait` returns unchanged, and on the run's `node.settled` event.
+
+Do not parse assistant text out of `runs.trace` to get data back. `runs.trace` is for showing a person the transcript. Its text is whatever the model said, not a value anything checked.
+
+## Showing a background run's progress
+
+An app that lets a run work in the background and polls it reads `runs.get(runId).activity` for a progress indicator. It is `null` unless `status` is `running`, and otherwise says what the run's root agent is doing now:
+
+| `phase` | The root agent is |
+| --- | --- |
+| `starting` | launching; its first turn has not begun |
+| `thinking` | reasoning, or waiting on the model before any output |
+| `tool` | calling a tool: `tool.name`, and `tool.summary` (the command's first line or the path it acts on, `null` while the call is still being written) |
+| `submitting_result` | writing or recording its `output_schema` result |
+| `writing` | streaming its answer text |
+| `between_turns` | between turns while the run still works: a child agent is running, a message is about to start the next turn, or the runtime is reminding it to submit its `output_schema` result |
+
+```ts
+const run = await crouter.runs.get(runId);
+const badge = run.activity?.phase === 'tool' ? `Running ${run.activity.tool.name}` : run.activity?.phase ?? run.status;
+```
+
+`activity` covers the root only, and it is read each time you call `runs.get`, so a phase shorter than your poll interval can be missed. `last_activity_at` is when any agent of the run last did something. Do not read `runs.trace` for progress: it returns every conversation. To show the text as it streams, follow `runs.events` or `runs.reply` instead of polling.
+
+## Bounding a run and handling `run_idle`
+
+No run is bounded in time until `deadline` lands. To bound one, pass a `signal` to `runs.parse` or `runs.wait`. When it aborts, the helper rejects with the signal's reason and leaves the run alone. Call `runs.cancel` if you want the run ended:
+
+```ts
+const controller = new AbortController();
+const timer = setTimeout(() => controller.abort(new Error('profile took too long')), 10 * 60_000);
+let runId: string | undefined;
+try {
+  const started = await crouter.runs.start({prompt, output_schema: Profile});
+  runId = started.run_id;
+  const run = await crouter.runs.wait(runId, {signal: controller.signal});
+  // …read run.status, run.outcome, run.result
+} catch (error) {
+  if (controller.signal.aborted && runId) await crouter.runs.cancel(runId);
+  throw error;
+} finally {
+  clearTimeout(timer);
+}
+```
+
+`runs.parse` rejects with `APIError` code `run_idle` when the agent stopped without submitting. The runtime reminds the agent of the schema up to three times in a row, then leaves the run `idle` with the schema still armed. The run is untouched: send `runs.message` to nudge the agent, which resets the reminders, or end the run with `runs.cancel`. A question from the run rejects with `waiting_on_user` unless you pass `onQuestion`. With `onQuestion`, `parse` answers each open question once and keeps waiting.
+
+## Waiting on a provider your app requires
+
+An app whose directory registration `requires` a provider (Doppel requires Context) needs that provider set up for the person before the operations that depend on it work. The runtime does not check this for you. `grant.get()` returns `dependencies`: one `ProviderDependency` per required provider, keyed by provider id, or `{}` when the app requires none. Read it on each request that needs the provider; do not store it.
+
+```ts
+import type { ProviderDependency } from '@north-light/sdk';
+
+// `ProviderDependency` is { state: SetupState; message?: string; next: string }.
+const { dependencies } = await runtime.grant.get();
+const context: ProviderDependency | undefined = dependencies['context'];
+if (context?.state !== 'ready') {
+  // Show the provider's own sentence and link its setup page; never hard-code either.
+  const setup = context && new URL(context.next);
+  setup?.searchParams.set('return_to', 'https://app.example.com'); // your registered redirect origin
+  // AppError: your app's own typed error (see the error envelope).
+  throw new AppError('provider_setup_pending', context?.message ?? 'Finish setting up Context, then try again.', {
+    status: 403,
+    retryable: false,
+    details: { provider: 'context', state: context?.state ?? 'not_started', message: context?.message, next: setup?.href },
+  });
+}
+```
+
+- `state` is `not_started` (the person has not done their part), `pending` (the provider is working), `ready`, or `failed`. To act when it turns `ready` (for example, start work the person was waiting on), follow it with `oauth.watchGrants` ([[crouter-sdk/client]]) instead of polling `grant.get()`.
+- `message` is the provider's own sentence for `pending` and `failed`, the same words the directory's setup page shows. It is absent for `not_started` and `ready`, so keep a short fallback for `not_started`.
+- `next` is the absolute URL of the directory's setup page for this provider and your app, where the person does their part or retries a failure. Append `return_to` (your app's registered redirect origin) so Continue on that page brings them back to you.
+- An entry is missing when the runtime has not synced the grant since the app's registration started requiring the provider; treat it as `not_started`.
+
+Refuse the dependent operation with `provider_setup_pending` (403, in `errorCodes`), carrying the entry's `state`, `message` and `next` in `details` so your front end can render them without another call.

package/dist/builtin-memory/crouter-sdk/guides/apps-with-many-users.md

@@ -0,0 +1,61 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Apps with many users, this knowledge should
+  be read because Keep each person's runtime connection separate while building
+  an app where people interact.
+---
+
+# Apps with many users
+
+An app can bring people together without putting all of their agents or data on one runtime. **Each person's runtime holds that person's agents, memory, files, conversations, AI subscription, phone, and device.** Your app's server holds its user table keyed by the crouter cloud `sub`, one stored `Connection` per person in a `ConnectionStore` (runtime URL, rotating refresh token, grant id), in-app roles and settings, and data shared between users. Sign in with crouter cloud is the initial sign-in for every app user, including a visitor. Request the app's grants during sign-in from a person whose runtime your app will use. A visitor who only needs to be recognized signs in with identity only (see [Signing in a visitor](#signing-in-a-visitor)). crouter cloud permissions decide what your app can do on each person's runtime. Your app decides what its users can do to each other.
+
+Keep the connection and refresh token on the server, not in a visitor's browser. The server can call `providers.call` on a stored connection outside any run, even when nobody is present and the person is offline. Access tokens last 10 minutes; refresh tokens rotate on each use and expire after 90 days unused. Give `OAuth2Client` a persistent `ConnectionStore` with a cross-process lock as `store`, reach each person's runtime with `await oauth.client(userId)`, and schedule `oauth.refreshIdleConnections({ olderThanMs: 30 * 24 * 60 * 60 * 1000 })` on a timer. Act on a dead connection in one place, `onRefusal`, as [[crouter-sdk/client]] describes, and delete a person's data only on `grant_removed` (`kind: 'removed'`). Learn when a background run ends with `oauth.watchRuns(...)` instead of a poll loop: see [[crouter-sdk/client]]. See [[crouter-sdk/client]].
+
+## Signing in a visitor
+
+A visitor who only needs to be recognized, not connected, signs in with identity only. Request `openid`, adding `email` for their email and `profile` for their name and photo, and no runtime scope. The directory shows one line ("Know who you are on crouter cloud"), writes no grant, and answers with an ID token and an access token usable only at `/userinfo`: no refresh token, grant, or runtime URL. Finish that sign-in with `exchangeIdentity`, not `exchangeCode`:
+
+```ts
+const {url, codeVerifier, state, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'email', 'profile'], state: sessionState});
+// Save codeVerifier, state, and nonce in the visitor's session; redirect them to url.
+// On the callback, read them back from the session and finish the sign-in:
+const visitor = await oauth.exchangeIdentity({code: callbackCode, codeVerifier, state: callbackState, expectedState: state, nonce});
+visitor.sub;           // 'user:…', the same id a Connection.userId carries for this person
+visitor.email;         // present only when 'email' was requested and approved
+visitor.emailVerified; // the directory's email_verified, when email was approved
+visitor.name;          // 'Sam Rivera', present only when 'profile' was approved and the person has a name (never a phone number); also givenName, familyName
+visitor.picture;       // 'https://lh3.googleusercontent.com/…', present only when 'profile' was approved and the account has a Google photo; show initials otherwise
+```
+
+`exchangeIdentity` returns an `Identity`: `sub`, `email` and `emailVerified` when granted, `name`, `givenName`, `familyName` when `profile` was granted and the person has one, `picture` when `profile` was granted and the account has a photo (only an `https:` URL; any other value is dropped, though it stays in `claims`), and every verified claim in `claims`. The SDK checks the ID token's ES256 signature against the directory's JWKS, its issuer, that `aud` is your client id, that it has not expired, and that its `nonce` equals the one `authorizeUrl` returned. `nonce` is required. Any failure, including a response with no ID token, throws `CrouterError` code `id_token_invalid`; if the directory's JWKS can't be fetched or is malformed, that error is thrown as is, not `id_token_invalid`.
+
+An `Identity` is not a connection. It has no runtime URL, grant, or refresh token, nothing is stored in a `ConnectionStore`, and nothing refreshes; your app keeps its own session for the visitor. The visitor's runtime can't be called on their behalf. To act for the visitor later, send them through `authorizeUrl` again with the runtime scopes you need and finish with `exchangeCode`, which returns a `Connection`. Each call refuses the other's answer with code `oauth_exchange_mismatch`: `exchangeCode` on a sign-in-only answer, and `exchangeIdentity` on an answer that carries a connection. A visitor is never mistaken for a connected user. When `exchangeIdentity` refuses an answer that carries a connection, the directory has already recorded that grant; the SDK leaves it in place, and it shows in the person's approved apps until they or your app revoke it.
+
+## Whose action a call records
+
+When visitor A causes your server to call person B's runtime using **B's connection**, the runtime records the app as `grantee` and B as `sub`. It does not know or record that A caused the call. Even a request outside a run, with nobody present, has this attribution. Keep your own record of the app user and action when you need it; do not send an app-user identity as a runtime principal.
+
+A visitor chatting with B's clone starts an app run on **B's runtime and B's AI subscription**, using the app's grant from B. The app rate-limits visitors; B's per-app spend cap is the platform backstop. crouter cloud's developer terms allow spending B's connection because of another user's action **only for what B turned on in your app, limited per person**. crouter cloud records nothing about the other user. B can control the app's spend cap or remove the app.
+
+## The app's agent and documents
+
+A run your app starts is **your app's agent**, not a continuation of another app's agent. It starts in `/apps/<app>/files`, uses the person's AI under `crtr:llm`, and reaches your app's own documents (owned by `app:<your app>`) without a `crtr:memory` scope. Other people's or apps' data is not shared merely because the app has many users. Its grant's resolved permissions govern access to the person's files (`crtr:files:<access>:user:<dir>`), the person's documents (`crtr:memory:<access>:user`), another app's space (only where that app allows it), and another app's conversations (`crtr:conversations:read:app:<B>`).
+
+The exception for the person's documents is their **public** ones (owned by the person, read through [[crouter-sdk/memory]]): an app with an active grant can read these even without a user-memory scope. A third-party app cannot see `friends` or `private` documents, even with `crtr:memory:read:user`; they look absent from lists, searches, individual reads, history, and automatic loads. Only a holder of `crtr:memory:manage:user` (a first-party app), or the person, reads all three levels. A document without a privacy field reads as `private`. Public read access is not write access. Your app's own documents are separate and is not filtered by these levels.
+
+In v1, every run is sandboxed: its shell runs as the app's OS user and sees only the app's space and folders its permissions name. Memory and conversations are accessed through the daemon, not by opening their storage directly. Normal runs have network access. Start a run with `isolated: true` when the agent should have **no network** and **no `/apps/<app>/files` mount**: its cwd is its own node folder, and all children inherit the restriction. The shell, `crtr` commands, stored conversation, and daemon-mediated model calls still work; the run's `scopes` can narrow its commands. An isolated run cannot turn isolation off in a child or schedule, or use an outside cwd or worktree.
+
+**An isolated run can't see, or be seen by, the app's other runs**, so starting one isolated run per visitor conversation keeps visitors apart. A node of an isolated run reaches only its own run's nodes: the root and the children it spawns. Another run's nodes, documents, conversation, trace, events and node folder answer `not_found`, and they are left out of `runs.list`, `canvas list` and history search. Messaging, interrupting, cancelling or deleting another run also answers `not_found`. The app's other, non-isolated runs can't see into an isolated run either, though they still see each other. Each node of an isolated run gets its own home folder, `/apps/<app>/nodes/<node-id>/home`, in place of the shared `/apps/<app>/home`. No run's sandbox mounts every node folder in `/apps/<app>/nodes`, so a non-isolated run's shell can't read a visitor's folder either. Custom objects a node of an isolated run registers stay inside its run, and it can't spawn a child under, or fork, another run's node. An isolated run still reads your app's memory and the person's public memory. Your app's server is not confined: `runs.list` and `runs.trace` still cover every run, so your server can show the person each visitor's conversation. A scheduled job an isolated run creates starts a new isolated run, and that run can't see the run that created the schedule. When a call is refused by scope, a missing-scope error (`scope_missing` or `forbidden`) comes before any `not_found`, so the refusal reveals nothing about the target.
+
+On v0 (the Mac local runtime), there is no sandbox: a run's shell has the Mac user's access; scopes gate only daemon and CLI calls.
+
+`runs.message(runId, message, { start_turn: false })` stores an app-attributed message on an existing run **without starting, reviving, or reopening a turn**. The run's status does not change; the message is delivered at the start of the next turn, before that turn's input, and the trace marks it as `custom` / `app_message`. This lets an app add context for the agent to see on its next turn without waking it now. The default `start_turn: true` sends an ordinary follow-up.
+
+`runs.message` is safe to retry: the SDK sends an `Idempotency-Key` (one per call, reused across its own retries; pass `idempotencyKey` to choose it) and the daemon delivers a given key once for 24 hours. A replay returns the original result; the same key with different text, `start_turn`, or run is refused with `409 idempotency_conflict`. An app that queues sends and may crash between the call and recording success should derive `idempotencyKey` from its own message id.
+
+**A run's first prompt is always its first turn's input**, however soon after `runs.start` a message arrives:
+
+- With the default `start_turn: true`, a message sent before the first turn has started queues behind it: the agent answers the `runs.start` prompt in turn one and your message in turn two, in the order you sent them. So an app can start a run with standing instructions and send the user's first message at once, without waiting for the first turn to begin.
+- To answer a first message in the first turn, pass it with the prompt: `runs.start({prompt, message})` stores `message` with the run, so it always joins the first turn as context delivered ahead of the prompt (a `custom` / `app_message` entry), and the prompt is still that turn's input, so one reply covers both. The result's `message` is what `runs.reply` takes: `runs.reply(run.run_id, run.message!)`. A `runs.message(runId, message, {start_turn: false})` sent separately after `runs.start` joins the first turn only if it is stored before the run claims that turn's messages; sent later, it waits for the next turn.
+
+Follow the reply to your message with `runs.reply(runId, sent)`, where `sent` is what `runs.message` (or `runs.start` with `message`) returned; `.text()` gives its text, and `.collect({onDelta})` streams it and says how the turn ended. It matches the turn that lists the message's `message_id` in `node.turn.started.input.message_ids` and ends when that turn completes. See [[crouter-sdk/streaming]].