@north-light/cli 0.0.0 → 0.3.414

package/docs/sdk/getting-started.md

@@ -0,0 +1,224 @@
+---
+title: Getting started
+description: 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 [Client construction](./client.md)).
+
+## 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 [Errors](./errors.md).
+
+## 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: [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)
+- Running the daemon in a container instead: [Docker environment](./docker.md)

package/docs/sdk/guides/README.md

@@ -0,0 +1,19 @@
+---
+title: SDK recipes
+description: 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 |
+|---|---|---|
+| [Typed extraction](./typed-extraction.md) | You need one structured answer and no follow-up. | A typed object or an explicit failure. |
+| [Event-driven assistant](./event-driven-assistant.md) | Events arrive over time from a webhook, queue, or watcher. | A resident node that wakes for each event. |
+| [Fan-out pipeline](./fan-out-pipeline.md) | One task needs independent research before a synthesis. | An orchestrator's final report. |
+| [Human approval](./human-approval.md) | A person must decide before work continues. | A node resumed by an inbox answer. |
+| [Apps on crouter cloud](./apps-on-crouter-cloud.md) | 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`. |
+| [Apps with many users](./apps-with-many-users.md) | 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/docs/sdk/guides/apps-on-crouter-cloud.md

@@ -0,0 +1,115 @@
+---
+title: Apps on crouter cloud
+description: 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 [Apps with many users](./apps-with-many-users.md).
+
+## 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` ([Learn when a person's grant changes](../client.md#learn-when-a-persons-grant-changes)) 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/docs/sdk/guides/apps-with-many-users.md

@@ -0,0 +1,59 @@
+---
+title: Apps with many users
+description: 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 [When a refresh is refused](../client.md#when-a-refresh-is-refused) 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 [Learn when a background run ends](../client.md#learn-when-a-background-run-ends). See [Client construction](../client.md#an-app-connection-and-refresh).
+
+## 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 [`client.memory`](../memory.md)): 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 [Streaming](../streaming.md#following-the-reply-to-one-message).

package/docs/sdk/guides/event-driven-assistant.md

@@ -0,0 +1,24 @@
+---
+title: Event-driven assistant
+description: When an assistant must react to later webhook, queue, or file-watcher events, read this because a resident node sleeps until nodes.message delivers the next event.
+---
+
+# Event-driven assistant
+
+Use this recipe for an assistant that reacts to an event source instead of ending after one request. Run `npx tsx examples/guides/event-driven-assistant.ts /path/to/repo`, then type events into standard input to stand in for a webhook handler or file watcher.
+
+<include lang="ts">../../../examples/guides/event-driven-assistant.ts</include>
+
+The external source owns detection. When it receives an event, it calls `nodes.message(nodeId, { body })`. `no_kickoff` leaves the resident node waiting for the first event, while `situational_context` tells it how to handle every event. A dormant resident node wakes for the message; a running node reads it at its next turn boundary. Keep the returned node id with the application so each later event reaches the same context and memory. The agent pushes one update report per event, which the application reads through `nodes.reports.list` and prints. The application checks for a fatal node fault rather than waiting forever for a report that cannot arrive.
+
+The agent does not poll or schedule a timer: the daemon wakes it on each message, and it goes dormant after reporting. This console program polls for the report associated with the event it just sent; an application with its own event loop can also consume the node's event stream. Ctrl-C calls `nodes.cancel()` only because this interactive example needs an explicit way to stop.
+
+Observed against the local daemon with `GUIDE_MODEL=openai-codex/gpt-6-sol:high` after sending `Build completed with 2 failing checks: lint and unit tests.`:
+
+```text
+assistant node: 3zl47w7d-mud5amcx-67978c9b
+Type an event and press Enter. Press Ctrl-C to stop the assistant.
+The build completed, but **lint and unit tests failed**. Inspect the two failing check logs first to identify the errors.
+```
+
+Use a resident node only when future events belong to the same ongoing assistant. For bounded work, use [typed extraction](./typed-extraction.md). See [lifecycle and wakes](../../concepts/lifecycle-and-wakes.md) for why waiting is free and [why a daemon](../../concepts/why-a-daemon.md) for why the process can outlive the terminal that started it.

package/docs/sdk/guides/fan-out-pipeline.md

@@ -0,0 +1,24 @@
+---
+title: Fan-out pipeline
+description: When independent parts of one job need separate agent work before one synthesis, read this because an orchestrator can spawn children, wait for reports, and publish a final result while the SDK streams progress.
+---
+
+# Fan-out pipeline
+
+Use this recipe when one result needs independent investigation first. Run `npx tsx examples/guides/fan-out-pipeline.ts /path/to/repo`; it asks an orchestrator to inspect a package through two children, prints live text and pushed reports, then prints the final reports retained on the node.
+
+<include lang="ts">../../../examples/guides/fan-out-pipeline.ts</include>
+
+`nodes.stream()` creates the orchestrator and observes it. It does not run the orchestration in your process: the node owns its children, waits for their pushed reports, and produces the synthesis. The stream gives your application live output and reports; `nodes.reports.list()` gives it the durable report view after settlement.
+
+Keep orchestration inside the canvas when children need the canvas's report delivery, durable waits, and a parent that can be inspected or resumed. Keep it in your application when tasks are simple independent calls and the application already owns their scheduling and aggregation. Do not use an orchestrator merely because a task is long; it earns the extra structure only when child work can run independently.
+
+A local run created `j6amiqxs-mud4drnk-330da196`; after its two children reported, `waitForOutcome()` returned:
+
+```text
+{ "kind": "result", "reason": "finalized" }
+```
+
+The same run's `nodes.stream()` observer ended during a dormant gap before it could print this outcome. A separate daemon fix is correcting that observer behavior; the example remains the intended streamed shape, but its streamed path has not yet been observed end to end.
+
+See [nodes and the canvas](../../concepts/nodes-and-the-canvas.md) for reports and durable identities, and [profiles, kinds, and modes](../../concepts/profiles-kinds-and-modes.md) for the base-versus-orchestrator decision.

package/docs/sdk/guides/human-approval.md

@@ -0,0 +1,24 @@
+---
+title: Human approval
+description: When a person must approve or reject work before an agent continues, read this because the SDK can create an inbox request whose answer wakes the requesting node.
+---
+
+# Human approval
+
+Use this recipe when a decision belongs to a person, not a timeout or an agent guess. Run `npx tsx examples/guides/human-approval.ts /path/to/repo`; it prints an inbox ticket id. Answer the page in the crtr human inbox and the worker wakes with that answer before it reports its result.
+
+<include lang="ts">../../../examples/guides/human-approval.ts</include>
+
+The application creates the page through `client.human.requests.create()` and names the worker as `requester_node_id`. `delivery.reply: true` makes the settled answer travel back to that node. The page's `UserQuestion` supplies a known response shape, so the person sees an explicit approve or reject decision instead of an unstructured prompt.
+
+The worker is terminal because this is a bounded approval run: it waits after setup, wakes when the person answers, then publishes its final result. The pending human request keeps that wait durable. The application does not poll the node or invent a fallback deadline; the human reply is a canvas event. `client.human.inbox` can list, inspect, and answer inbox tickets when your application provides its own human interface.
+
+Observed against the local daemon after an approve response:
+
+```text
+approval ticket: a643479ca7a79758bf86f32d24bd8c9b22e16509cd60996c5e4fe0bc5f097d45
+Answer it in the crtr human inbox. The worker will wake with the response.
+worker outcome: result
+```
+
+See [lifecycle and wakes](../../concepts/lifecycle-and-wakes.md) for the wake model and [scopes and trust](../../concepts/scopes-and-trust.md) for why the daemon, rather than the application, owns delivery of the answer.

package/docs/sdk/guides/typed-extraction.md

@@ -0,0 +1,24 @@
+---
+title: Typed extraction
+description: When an application needs one bounded structured answer with no follow-up, read this because nodes.parse returns a typed outcome union instead of hiding agent failures.
+---
+
+# Typed extraction
+
+Use this recipe to extract a small fact set from files in one working directory. Run it with `npx tsx examples/guides/typed-extraction.ts /path/to/repo`; it prints a package name and version or exits with an explicit agent outcome.
+
+<include lang="ts">../../../examples/guides/typed-extraction.ts</include>
+
+`nodes.parse()` creates a terminal root, waits for it, and returns the structured result typed from the Zod schema. The schema belongs at the boundary where your application consumes the answer, not in a second parser after the run.
+
+Observed against the local daemon in this checkout:
+
+```text
+package @north-light/cli@0.3.332
+```
+
+Handle every outcome arm. A result contains `output_parsed`; a decline says the agent could not honestly meet the schema; another failure carries its reason and detail. Transport and daemon failures still throw, so let those reach your normal application error handling.
+
+**From an app.** An app holding a person's connection does the same thing with `runs.parse({prompt, output_schema})`, which returns the run outcome union (`finalized` with `output_parsed` typed from the schema, `declined` with `details`, `canceled`, `deadline_exceeded`, `runtime_error`). It also covers `run_idle` and questions. See [Apps on crouter cloud](./apps-on-crouter-cloud.md#getting-a-result-back-from-a-run).
+
+This is the right shape for bounded work: one prompt, one answer, and no future message. If a user or external event must return to the same agent later, use a resident node instead. See [nodes and the canvas](../../concepts/nodes-and-the-canvas.md) for why an SDK node has durable identity, and [lifecycle and wakes](../../concepts/lifecycle-and-wakes.md) for the terminal-versus-resident decision.

package/docs/sdk/memory.md

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