@north-light/cli 0.0.0 → 0.3.413

package/dist/builtin-memory/crouter-plugin/parameters.md

@@ -0,0 +1,31 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Parameters and handler input, this knowledge
+  should be read because Declare command parameters and infer their handler
+  input types.
+---
+
+# Parameters and handler input
+
+Parameter object keys become handler input keys. The generated manifest uses their kebab-case form: `appId` becomes `app-id`, while the handler receives `input.appId`.
+
+Every `param.*` builder takes constraint text first. Parameters are optional unless `required: true` is supplied. `repeatable: true` makes a string, integer, enum, or positional parameter an array. It cannot be used with boolean, path, or file parameters. A parameter with `default` remains optional in handler input because crtr applies that default while parsing its command line; the server does not apply it.
+
+| Builder | Handler value | Options |
+| --- | --- | --- |
+| `param.string(constraint, options?)` | `string` | `required`, `repeatable`, `default` |
+| `param.int(constraint, options?)` | `number` | `required`, `repeatable`, `default` |
+| `param.bool(constraint, options?)` | `boolean` | `required`, `default` |
+| `param.enum(choices, constraint, options?)` | a member of `choices` | `required`, `repeatable`, `default` |
+| `param.path(constraint, options?)` | `string` for `encoding: 'text'`, `Uint8Array` for `encoding: 'base64'` | `required`, `encoding` |
+| `param.file(constraint, options?)` (same as `field.file`) | `string` | `required` |
+| `param.positional(constraint, options?)` | `string` | `required`, `repeatable` |
+| `param.stdin(constraint, options?)` | `string` | `required` |
+
+`param.positional` is the one positional argument a leaf may have. `param.stdin` receives the command's standard input. `param.path` receives the contents of the local file named by the crtr caller, never the path string. Text is UTF-8. Base64 mode decodes the caller's file bytes into a `Uint8Array` before the handler runs.
+
+`param.file` declares a file parameter. The agent passes a runtime path. When a capability provider is called, the runtime uploads a copy and the handler receives a signed `https` download link as a string, valid for 15 minutes. The file's name is the link's last path segment. With a local `--endpoint` install, the handler receives the string the agent typed. Unlike `param.path`, the handler never receives the file contents inline. `param.file` and `field.file` return the same descriptor, so either works in `params`.
+
+The handler input is inferred from the parameter object with no manual annotation. In the `node_modules/@north-light/plugin/README.md`, `input` is inferred as `{ name: string; region?: 'us-east' | 'eu-west' }`. A required parameter is present, optional parameters can be absent, enum choices remain literal values, and repeatable parameters are arrays.
+
+`definePlugin` checks parameter descriptor objects when the module loads. A malformed hand-built descriptor throws `PluginDefinitionError` at that call. Use the builders instead of constructing descriptor objects.

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

@@ -0,0 +1,13 @@
+---
+kind: knowledge
+description: Driving a crouter daemon from an application with @north-light/sdk
+when-and-why-to-read: When you are writing or reviewing application code that runs a crtr agent — installing @north-light/sdk, constructing a client, creating a node, watching its event stream, reading its result or connecting a browser to a daemon — this reference should be read because `generate()` and `local()` were deleted, while the typed client keeps daemon transport and agent outcomes distinct.
+short-form: The ESM-only application-facing client for a crtrd daemon. Construction and transports, `client.nodes` create/wait/parse/stream, activity snapshots, phase-2 resources including files and bash, the returned-not-thrown outcome union, and error classes.
+surfaces:
+  - on: boot
+    at: name
+---
+
+# `@north-light/sdk`
+
+Read `crouter-sdk/README` for the SDK overview and the directory pages for the specific client surface. The directory listing names every page.

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

@@ -0,0 +1,92 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need SDK overview, this knowledge should be read
+  because Drive a crouter daemon from a Node or browser application with the
+  typed SDK.
+---
+
+# `@north-light/sdk`
+
+The ESM-only client an application installs to drive a crouter daemon: create agent runs, watch streamed events, wait for typed results, and reach the rest of the daemon's `/v1` API.
+
+One package, one class. `new Crouter()` in Node talks to the owner's unix socket. `new Crouter({ baseURL, token })` in a browser or a remote process talks to the daemon's TCP listener with a bearer token. Resource methods issue `/v1` requests; `createAndWait`, `parse`, and `auth.status` compose more than one request. crtrd stays the sole owner of canvas state.
+
+```ts
+import Crouter from '@north-light/sdk';
+import { z } from 'zod';
+
+const client = new Crouter();
+
+const run = await client.nodes.parse({
+  prompt: 'Summarize the failing tests in this repo.',
+  cwd: '/path/to/repo',
+  output_schema: z.object({ failures: z.array(z.string()), root_cause: z.string() }),
+});
+
+if (run.kind === 'result') console.log(run.output_parsed.root_cause);
+```
+
+## Go live with an app key
+
+Once you have installed the SDK and tried the local flow in [[crouter-sdk/getting-started]], generate the app's key on your server:
+
+```bash
+npx @north-light/sdk keygen --app <client id>
+```
+
+`keygen` saves the private JWK to `local/app-key.json` (mode `0600`); keep that file out of git. With `--app`, it offers to add the public key to your registered app through your own `crtr`, as an additional key that never replaces the current one. Otherwise, click **Add key** on the app's **Sign-in** tab and paste the public JWK printed on stdout (or paste it under **Register an app** for a new app). An app authenticates only with its key; the directory issues no client secret. On your server, load the saved key and pass it as `privateKey`:
+
+```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, state, codeVerifier, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:llm', 'crtr:act'], state: sessionState});
+// Save state, codeVerifier, nonce in the user's session, then redirect to url.
+const connection = await oauth.exchangeCode({code: callbackCode, state: callbackState, expectedState: state, codeVerifier, nonce});
+await store.save(connection);
+const client = await oauth.client(connection.userId); // Refreshes through the store from here on.
+```
+
+The directory rejects the key until its public JWK is added to the app. To change keys later, follow [[crouter-sdk/getting-started]]: add the new key, switch the app to it, verify a real sign-in, then retire the old key. An app can hold two active keys at once, so there is no downtime.
+
+## Pages
+
+| Page | Covers |
+|---|---|
+| [[crouter-sdk/getting-started]] | Install, `new Crouter()` on the owner's socket, `client.auth.status()` and `crtr sys connect` for a browser or remote app, Chrome's local-network prompt |
+| [[crouter-sdk/client]] | Every constructor option and its environment-variable fallback; per-request options |
+| [[crouter-sdk/nodes]] | `create` parameters, the outcome union, `parse()` with a zod schema, `waitForOutcome`, `message`, `cancel`, nested resources |
+| [[crouter-sdk/streaming]] | The event table, `stream()` / `events()`, the activity helper, resume with `after`, `stream_gap` and `stream_dropped` |
+| [[crouter-sdk/files]] | Absolute-path reads, writes, and one-level lists |
+| [[crouter-sdk/bash]] | One bounded command and its output result |
+| [[crouter-sdk/memory]] | `memory.list` and `memory.get`: an app reads the person's `public` documents with no scope |
+| [[crouter-sdk/resources]] | Every namespace (including `customObjects`, `runs`, `memory`, `shares`, `providers`) with its routes, what is deliberately excluded, and the `client.request()` escape hatch |
+| [[crouter-sdk/errors]] | The error class table and the retry policy |
+| [[crouter-sdk/docker]] | `start()`, `attach()`, `connection()` from `@north-light/env-docker` |
+| [[crouter-sdk/testing]] | `FakeCloud` from `@north-light/sdk/testing`: a fake directory and runtime your real `OAuth2Client` and `Crouter` talk to through `fetch` |
+| [[crouter-sdk/release-notes]] | Behavior changes an existing app must act on, newest first |
+| [[crouter-sdk/guides/apps-on-crouter-cloud]] | Typed results from app runs with `runs.parse`, declines, bounding a run, `run_idle`, and waiting on a provider your app requires |
+| [[crouter-sdk/guides/apps-with-many-users]] | Per-person runtime connections, app-owned user access, privacy, and spending |
+
+## Phases
+
+The surface ships in three cuts.
+
+| Phase | What lands | State |
+|---|---|---|
+| **Phase 1** | Client construction and transports; `client.auth.status()`; `client.nodes.create`, `retrieve`, `list`, `outcome`, `waitForOutcome`, `createAndWait`, `parse`, `message`, `cancel`, and `interrupt`; `nodes.reports.list`; `profiles.ensure` and `retrieve`; `system.status` and `health`; the error hierarchy; per-request options; `crtr sys connect`; and `env-docker.connection()` | Shipped |
+| **Phase 2 namespaces** | Node lifecycle, job, worktree, and result; canvas and canvas history; crons; human requests and inbox; models; `client.files.read` through `/v1/files/peek`, `write`, and `list`; and `client.bash.run` | Shipped |
+| **Phase 2 streaming** | `GET /v1/nodes/{id}/events`, `nodes.stream(params, options?)`, `nodes.events(id, options?)`, `NodeStream`, and the activity helper | Shipped |
+| **Phase 3** | The review, comment, and chat-inventory namespaces | Not shipped |
+
+The per-run `scopes` create field ships in phase 1. `nodes.update` scope support remains phase 2 and is not in the shipped client or wire declarations.
+
+## Verification status
+
+The SDK declarations and streaming examples are verified.
+
+## Where the agents read this
+
+The same content routed for agents lives in the built-in document `crouter-sdk`, which ships with the `crtr` binary. An agent working in an application's repository reaches it with `crtr canvas read crouter-sdk` and does not need this repository checked out.

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

@@ -0,0 +1,40 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Bash, this knowledge should be read because
+  Execute bounded shell commands through the daemon.
+---
+
+# `client.bash`
+
+`client.bash.run` executes one bounded `bash -c` command through the daemon.
+
+```ts
+const result = await client.bash.run({
+  command: 'printf "%s\\n" "$MESSAGE"',
+  cwd: '/absolute/path/to/project',
+  env: { MESSAGE: 'hello' },
+  timeout_s: 30,
+  profile: 'my-app',
+});
+
+if (result.exit_code !== 0) console.error(result.stderr);
+```
+
+`run(params, options?)` returns `Promise<BashRunDTO>`. Its final `options` object is the normal request-options object: `headers`, `signal`, `timeout`, and `maxRetries`.
+
+| Result field | Type | Meaning |
+|---|---|---|
+| `exit_code` | `number \| null` | Process exit code, or `null` after a timeout. A non-zero code is returned, not thrown. |
+| `signal` | `string \| null` | Signal that ended the process, when one did. |
+| `stdout` / `stderr` | `string` | Captured output prefix. |
+| `stdout_truncated` / `stderr_truncated` | `boolean` | Whether that output stream exceeded its 256 KiB capture limit. |
+| `timed_out` | `boolean` | `true` after the daemon terminates the process group for a timeout. |
+| `duration_ms` | `number` | Command duration in milliseconds. |
+
+`cwd` is required, absolute, and must name an existing directory. The daemon never uses its own working directory as a fallback. `timeout_s` defaults to 60, must be greater than 0, and cannot exceed 600. The SDK keeps the HTTP request open for the command timeout plus 15 seconds, unless its configured request timeout is already longer.
+
+Pass dynamic values through `env` and reference them from the command as `"$NAME"`, rather than interpolating them into shell source. The command receives the daemon's default-deny operational environment, selected profile environment, then your `env` values.
+
+## Authority
+
+The token is the owner credential. Anyone holding it can already create an agent with a bash tool, so this command runs with the daemon user's authority and does not provide a restricted command area.

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

@@ -0,0 +1,299 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need Client construction, this knowledge should
+  be read because Configure local socket and remote HTTP connections,
+  authentication, and request options.
+---
+
+# Client construction
+
+```ts
+import Crouter from '@north-light/sdk';
+
+const localClient = new Crouter();                                          // owner's own daemon, unix socket
+const remoteClient = new Crouter({ baseURL: 'http://localhost:8787', token: 'token' }); // TCP with a bearer token
+const customSocketClient = new Crouter({ socketPath: '/custom/path/crtrd.sock' }); // an explicit socket
+```
+
+`Crouter` is the default export and the only class an application constructs. `CrtrClient` from `@north-light/api` is an implementation detail and is not re-exported.
+
+## An app connection and refresh
+
+```ts
+import { OAuth2Client } from '@north-light/sdk';
+
+const oauth = new OAuth2Client({
+  clientId, privateKey, keyId, redirectUri, issuer, // issuer is required; no localhost fallback
+  store,                                            // where every person's Connection lives (see below)
+  onRefusal: async (refusal) => { /* see "When a refresh is refused" */ },
+});
+const {url, codeVerifier, state, nonce} = await oauth.authorizeUrl({scopes: ['openid', 'crtr:act'], state: sessionState});
+// Save codeVerifier, state, and nonce in the app session; redirect the user to url.
+const connection = await oauth.exchangeCode({code: callbackCode, codeVerifier, state: callbackState, expectedState: state, nonce});
+await store.save(connection);
+
+// Later, in any process that shares the store:
+const client = await oauth.client(connection.userId);
+```
+
+`oauth.client(userId)` loads the person's stored connection and returns a `ConnectedCrouter`: a `Crouter` on their runtime that refreshes its access token through the store, plus `userId` and `runtimeUrl` (the runtime it calls, as the stored connection names it). When nothing is stored for `userId` it throws `CrouterError` code `not_connected`: show "sign in again". `store` is required: `new OAuth2Client` without one throws a `CrouterError`.
+
+`exchangeCode` returns the person's `Connection` and is for a sign-in that requests runtime scopes. A sign-in-only request (`openid`, optionally with `email` and `profile`, and no runtime scope) gets no connection from the directory: finish it with `oauth.exchangeIdentity({code, codeVerifier, state, expectedState, nonce})`, which returns the verified `Identity` (`sub`, `email` when granted, `name`/`givenName`/`familyName` when `profile` was granted and the person has a name, `picture` (an https photo URL) when `profile` was granted and the account has a photo, and `claims`, typed `IdTokenClaims`, which the SDK also exports). When `scopes` is a literal list that includes `openid`, `authorizeUrl` types its `nonce` as `string`; a list held in a variable keeps its literal type only when declared `as const` (`const scopes = ['openid', 'email'] as const`). Pass `prompt: 'consent'` to `authorizeUrl` to show the directory's consent screen even when the person already approved these scopes. See [[crouter-sdk/guides/apps-with-many-users]]. `exchangeCode` given a sign-in-only answer throws `CrouterError` code `oauth_exchange_mismatch` and names `exchangeIdentity`.
+
+`state: callbackState` comes from the redirect query, while `expectedState` is the value saved in the app's session when `authorizeUrl()` ran. `exchangeCode` and `exchangeIdentity` refuse a missing or different value with `CrouterError` code `oauth_state_mismatch` **before** sending the code to the token endpoint. Persist the expected value across redirects and tie it to the user's session; never use the callback's `state` for both arguments.
+
+### Keep sign-in secrets out of HTTP logs
+
+If your app uses `nestjs-pino` / `pino-http`, its default serializers can log the full `/auth/callback?code=…&state=…` URL and query, plus response headers including the session `set-cookie` and a redirect `location` containing OAuth `state`. Redacting only authorization and cookie **request** headers does not protect these values. Use bounded serializers for *all* routes, not just the callback: log only request method, path without query string, and id; log only response status. For example:
+
+```ts
+LoggerModule.forRoot({
+  pinoHttp: {
+    serializers: {
+      req: (req: { method?: string; url?: string; id?: unknown }) => ({
+        method: req.method,
+        path: req.url?.split('?')[0],
+        id: req.id,
+      }),
+      res: (res: { statusCode?: number }) => ({ statusCode: res.statusCode }),
+    },
+    redact: ['req.headers.authorization', 'req.headers.cookie'],
+  },
+});
+```
+
+Do not add the raw query, URL, response headers, or body elsewhere in your logs. Test an auth callback and a redirect with representative secret values and assert that neither the code, state, nor session cookie appears in the output.
+
+`ConnectionStore` provides `load(userId)`, `save(connection)`, `lock(userId, fn)` and `remove(userId, refreshToken)`; it may also implement `listStale(before: Date)`. `lock` must hold across every process that shares the store and commit what `fn` wrote when `fn` resolves: the SDK reloads the connection, sends the refresh request only if no other process rotated its token, and saves the result while the lock is held. The SDK never runs your code (`onRefusal`) under the lock, and never throws out of it. `remove(userId, refreshToken)` deletes the connection only while it still holds that refresh token and answers whether it deleted a row; the SDK calls it under `lock` after a refused refresh's `onRefusal` resolves, so a connection a fresh sign-in saved meanwhile is kept. `MemoryConnectionStore` locks only within one process, and its lock is not reentrant; it is for local development and tests.
+
+For Postgres, install `pg` in the app and use the optional SDK subpath instead of writing the lock yourself:
+
+```ts
+import {Pool} from 'pg';
+import {PostgresConnectionStore} from '@north-light/sdk/stores/postgres';
+
+const store = new PostgresConnectionStore(new Pool({connectionString: process.env.DATABASE_URL}), {table: 'connection'});
+```
+
+Create the table before using it (or adapt this schema in a migration):
+
+```sql
+CREATE TABLE connection (
+  user_id text PRIMARY KEY,
+  runtime_url text NOT NULL,
+  refresh_token text NOT NULL,
+  grant_id text NOT NULL,
+  access_token text NOT NULL,
+  access_token_expires_at timestamptz NOT NULL,
+  id_token text,
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp()
+);
+CREATE INDEX connection_updated_at_idx ON connection (updated_at, user_id);
+```
+
+The store holds `pg_advisory_xact_lock` on a dedicated pooled connection for the entire refresh callback, including the token request and save. All workers must use the same database; provision pool capacity for concurrent refreshes, and do not set a transaction timeout shorter than a token request. `updated_at` records every save, not necessarily a refresh if your app also saves for another reason. The table holds credentials: restrict database access and encrypt backups. This subpath is isolated from the SDK's main import, so apps without Postgres do not load `pg`.
+
+`runtime_provisioning` means the user's runtime is still being set up; the SDK retries the token request.
+
+`service_unavailable` (503, `retryable: true`, `origin: 'runtime'`) on an app call means the runtime could not confirm the grant the access token names: the token carries a grant revision newer than the runtime's grant mirror, and the pull that would bring the mirror up to date failed. Nothing was refused and nothing ran. The SDK retries `GET`, `runs.start`, and `runs.message` on it; on any other call, retry it yourself. Never treat it as a refused connection.
+
+### When a refresh is refused
+
+When the directory refuses a stored connection's refresh token, the SDK runs your `onRefusal(refusal)` once the store lock is released, then removes the stored connection (only while it still holds the refused token), then rejects the call that needed the refresh with the directory's `AuthenticationError` (status 401, `type: 'authentication_error'`, `retryable: false`, `userAction: 'reconnect'`, `origin: 'directory'`). `refusalOf(error)` on that error returns the same `Refusal`. Every caller goes through this one place: a request on `oauth.client(userId)`, `refreshIdleConnections`, and a `RunWatcher`. A client whose connection was refused then raises the same error on every later call without contacting the directory; call `oauth.client(userId)` again after the person signs in.
+
+A `Refusal` is `{kind, code, userId, grantId, error}`. `kind` reads this table; `code` is the directory's code. **Delete what you keep for a person only on `grant_removed`** (`kind: 'removed'`). On every other code, keep it.
+
+| `code` | `kind` | What happened | What your app does |
+|---|---|---|---|
+| `grant_removed` | `removed` | The person removed your app, deleted their account, or a provider-connected registration disconnected them. The runtime has deleted your app's space, runs, schedules and shares. | You may delete what you keep for that person. Do not call `runs.delete`: the runs are already gone. If they connect again, they see the consent page and start fresh. |
+| `grant_suspended` | `paused` | Your app's access for that person is paused. Nothing was deleted; your app's sandboxes are stopped. | Keep everything you store for that person, stop calling for them, and show that the app is paused. If they connect again, the same grant comes back with every run, file and schedule. |
+| `refresh_token_expired` | `reconnect` | The refresh token went 90 days without use. The grant is still active. | Keep everything. Run the connect flow again; the consent page is skipped. Prevent it with `refreshIdleConnections` (below). |
+| `refresh_token_reused` | `reconnect` | Two of your app's processes raced on one refresh token, and the directory ended the grant's refresh tokens. The grant is still active. | Keep everything. Fix the store's `lock`, then reconnect (consent is skipped); without the fix the race recurs. |
+| `grant_revoked` | `reconnect` | The directory refused without naming a reason: a refresh token it never issued to your app, one your app revoked through `revoke`, or one whose record was purged. The runtime also answers `grant_revoked` when the grant is not active in its last sync; the connected client then refreshes once, so you normally receive the directory's specific code instead. | Keep everything and reconnect. Never delete data on `grant_revoked`: it does not say anything was removed. |
+
+In every case the SDK removes the stored connection after your handler resolves, because its refresh token can never work again; your handler does not delete it.
+
+```ts
+import { OAuth2Client, refusalOf } from '@north-light/sdk';
+
+const oauth = new OAuth2Client({
+  clientId, privateKey, keyId, redirectUri, issuer, store,
+  onRefusal: async ({kind, userId}) => {
+    if (kind === 'removed') await forgetUser(userId);      // the runtime already deleted the app's runs
+    else if (kind === 'paused') await markPaused(userId);  // keep everything
+    else await askToSignIn(userId);                        // keep everything
+  },
+});
+
+// In a request handler, answer the one request; the handler above already acted on the connection.
+try { await (await oauth.client(userId)).runs.start({prompt}); }
+catch (error) { if (refusalOf(error)) return showSignInAgain(); throw error; }
+```
+
+`onRefusal` runs **at least once** per dead connection: make it idempotent. Two processes can each be refused on the same token, and a handler that throws runs again. It runs outside the store lock, so it may take as long as it needs and may use the same database pool.
+
+- **If it throws**, the stored connection is kept, and the caller receives the directory's refusal error (not the handler's): `refusalOf(error)` is set and `error.cause` is what the handler threw. The client does not latch that refusal, so the next use of the connection refreshes, is refused again, and calls the handler again. `refreshIdleConnections` reports it in `failures`.
+- **It must not call the runtime for `refusal.userId`**: that connection is dead. `oauth.client(userId)` (or a refresh) for that same user inside the handler throws `CrouterError` code `refusal_handler_reentry` instead of waiting on itself. Calls for other users are fine. (Detection uses Node's `AsyncLocalStorage`; where it is unavailable the guard is off.)
+
+`refusalOf(error)` returns a `Refusal` only for an error the SDK raised while refreshing a stored connection. A 429, `cap_exhausted`, `scope_missing`, a runtime-origin `grant_revoked`, or an `invalid_client` refusal of your app's key is not a refused connection, and `refusalOf` returns `null` for it.
+
+### Keep offline users connected
+
+A refresh token expires after 90 days without refresh. Schedule a worker (for example, daily) to call `oauth.refreshIdleConnections({olderThanMs: 30 * 24 * 60 * 60 * 1000})`. It lists connections last saved before the cutoff, refreshes each through the store's cross-process `lock`, and returns `{refreshed, refused, failures}`. A refused connection goes through `onRefusal` and is removed, and is counted in `refused`. `failures` (`[{userId, error}]`) holds every connection still stored that could not be refreshed: an error other than a refusal, or a refusal whose `onRefusal` threw (`refusalOf(error)` is set); the next run retries them. A connection removed before its turn is skipped. The SDK does not start a timer. A store without `listStale(before: Date): Promise<Connection[]>` gets a `CrouterError` naming that missing method; a nonpositive or nonfinite `olderThanMs` also gets a `CrouterError`. `listStale` should reflect the most recent successful save/rotation, not the last read of a connection. `MemoryConnectionStore` and `PostgresConnectionStore` implement it. Store credentials securely.
+
+### Learn when a background run ends
+
+A run the app starts and does not wait on (a draft, a scheduled job) ends while nobody is holding a request. `oauth.watchRuns(...)` returns a `RunWatcher` that follows those runs and hands each ending to `onEnded`, so the app writes no poll loop of its own:
+
+```ts
+const watcher = oauth.watchRuns({
+  pending: () => db.drafts.findMany({where: {status: 'drafting'}, select: {userId: true, runId: true}}),
+  onEnded: async ({userId, runId, ended, run}) => {
+    // Idempotent: only a row still waiting on this run moves.
+    if (ended === 'gone') await db.drafts.updateMany({where: {runId, status: 'drafting'}, data: {status: 'failed'}});
+    else await db.drafts.updateMany({where: {runId, status: 'drafting'}, data: {status: 'ready', result: run.result}});
+  },
+  onError: (error, run) => log.warn({error, run}, 'run watcher'),
+});
+await watcher.start();
+// After starting a run the app will watch:
+watcher.nudge();
+// On shutdown:
+await watcher.stop();
+```
+
+- **`pending()`** returns `{userId, runId}` for every run the app still waits on, read from its own rows. The rows are the durable record: a restarted watcher re-derives everything from them. The watcher calls it at `start()`, every `sweepMs` (default 30 000), after each delivery, and on `nudge()`. Stop returning a run once `onEnded` has landed it.
+- **Each run** is followed with `runs.get(runId, {wait})` on `oauth.client(userId)` until its status is `settled`, `idle` or `waiting_on_user`; then `onEnded({userId, runId, ended, run})` receives that status as `ended` and the `RunObject`. At most `concurrency` (default 50) long-polls are open at once; the rest wait their turn.
+- **Delivery is at least once per `(runId, status, latest_sequence)`.** A run still in `pending()` after delivery is re-read once per sweep without `wait`, and delivered again only when that key changes: it worked again and came to rest at a new sequence, or an `idle` run was later canceled to `settled`. A sweep that reads `running` goes back to the long-poll. The key is held in memory, so a restart may deliver an ending again: guard the write on the row still waiting on that run.
+- **`gone`** (`run: null`) is delivered once when the runtime answers 404 `not_found` with `origin: 'runtime'` (the run was deleted). A 404 from the hosting router (`origin: 'router'`) is a transient failure, not `gone`.
+- **If `onEnded` throws**, the same ending is retried after 5 s, doubling to 5 min, and the error goes to `onError`. A transient runtime error backs off the same way. A missing connection (`not_connected`) or a refused one (which `onRefusal` already handled) drops that run's loop and reports to `onError`; the next sweep decides again from `pending()`.
+- **`stop()`** stops sweeping, aborts every open long-poll, and resolves once every loop has ended; no handler starts afterwards.
+- **Live progress (`onActivity`, optional).** To show what a run is doing (a "reading your memories" / "writing the page" badge) without a second `runs.get` per page read, pass `onActivity: async ({userId, runId, activity, run}) => …`. It is called with each read of a run that is still `running` whose `activity` (see `RunObject.activity`: `starting`, `thinking`, `tool`, `writing`, `submitting_result`, `between_turns`) differs from the last one handed over for that run, compared as JSON, so a new `tool.name` or `tool.summary` counts as a change and a new `latest_sequence` alone does not. It is never called for a run at rest. While `onActivity` is set, running runs are read with `wait: activityWait` (integer 1–25 s, default 2) instead of 25 s, because the runtime's long-poll answers early only when the run comes to rest; a followed run is read at least that often, at one read per run per `activityWait` seconds. A run waiting for a `concurrency` slot or backing off after a failure is not read, and a phase that starts and ends between two reads is not seen. The hook is best effort and never awaited by the watcher: at most one call per run runs at a time, a newer reading taken meanwhile replaces any still waiting, a throw goes to `onError` and is not retried, and it never delays, repeats or changes `onEnded`. A call can finish after that run's `onEnded`, or arrive for a run the app just dropped from `pending()`, so guard the write on the row still waiting on that run and show the stored phase only while the row is waiting; `stop()` does not wait for a call already running.
+
+### Learn when a person's grant changes
+
+What an app reads from `grant.get()` changes while nobody is holding a request: a required provider's setup turns `ready` (`dependencies`), the person changes the app's scopes or spend cap, or the grant is revoked. `oauth.watchGrants(...)` returns a `GrantWatcher` that follows the grants of the people the app names and hands each change to `onChanged`, so the app writes no poll loop and needs no browser tab open:
+
+```ts
+const watcher = oauth.watchGrants({
+  // Only people whose change the app will act on: here, owners still waiting on Context.
+  users: () => db.owners.findMany({where: {connected: true, drafted: false}}).then((rows) => rows.map((row) => row.userId)),
+  onChanged: async ({userId, grant}) => {
+    // Level-triggered: decide from the grant as it is now, never from "did it just change".
+    if (grant.dependencies['context']?.state !== 'ready') return;
+    // Idempotent: only a row still waiting moves, so a redelivery or a second instance starts nothing.
+    const claimed = await db.owners.updateMany({where: {userId, drafted: false}, data: {drafted: true}});
+    if (claimed.count === 1) await startDraft(userId);
+  },
+  onError: (error, userId) => log.warn({error, userId}, 'grant watcher'),
+});
+await watcher.start();
+// After the app starts waiting on someone:
+watcher.nudge();
+// On shutdown:
+await watcher.stop();
+```
+
+- **`users()`** returns the crouter cloud user ids whose grant the app follows, read from its own rows. The watcher calls it at `start()`, every `sweepMs` (default 30 000), after each delivery, and on `nudge()`. A user it no longer returns is forgotten: no further reads, and a user who comes back is delivered their current grant again. Each followed person holds one request on their runtime per turn, so return only people whose change the app will act on.
+- **Each turn** is one `grant.get` on `oauth.client(userId)`; then the user goes to the back of the queue, so with more followed users than `concurrency` (default 50) every user still gets a turn in round-robin order. A user whose last reading was delivered reads `grant.get({wait, since: version})` (`wait` integer 1–25, default 25): the runtime holds the read until the grant's `version` changes or `wait` seconds pass. A user with nothing delivered yet (their first turn, or after `onChanged` threw) reads at once.
+- **`onChanged({userId, grant, previous})`** is level-triggered. The first event for a user in a process carries the current grant and `previous: null`, so a restart delivers current state again; later events carry the grant last delivered as `previous`. Delivery is at least once per `(userId, version)` and never repeated for an unchanged `version`; make the handler idempotent (guard the write on the row still waiting).
+- **If `onChanged` throws**, the same version is delivered again after 5 s, doubling to 5 min, and the error goes to `onError`. A transient runtime error (5xx, `runtime_starting`, a router 504, a network failure), or a runtime 401 `grant_revoked` the client's one forced refresh did not clear, backs off the same way. An answer without `version` (a runtime older than 0.3.400) is reported and backs off. A missing connection (`not_connected`) or a refused one (which `onRefusal` already handled, once) drops that user and reports to `onError`; the next sweep decides again from `users()`.
+- **`stop()`** stops sweeping, aborts every open read, and resolves once every turn has ended; no handler starts afterwards.
+- **One person, one request.** Without the watcher, `runtime.grant.get({wait: 25, since: grant.version})` holds a single read the same way; the request timeout is extended by `wait`. `wait` outside integer 1–25 throws `RangeError` before sending.
+
+### Link to the app's settings on crouter cloud
+
+Each person who uses your app has a page on their crouter cloud account where they change or remove what the app may do. Link to it with the URL the directory advertises; never compose the path yourself:
+
+```ts
+const href = await oauth.accountAppUrl(); // e.g. https://<directory>/account/apps/<your client id>
+```
+
+- **What it is.** The discovery document's `account_app_uri_template` with its one `{client_id}` replaced by your encoded client id. It is the same URL for every person: the directory shows whoever is signed in to it their own page for your app (and sends someone without a directory session through sign-in first). Someone without an active grant, a sign-in-only visitor for one, sees that the app is not connected to their account.
+- **What it needs.** No user and no connection, so it serves owners and visitors alike. Its only request is the discovery read that `authorizeUrl`, `verifyIdToken` and `revoke` share.
+- **Errors.** Each is a `CrouterError` (code `crouter_error`) whose message names the fault: the directory advertises no `account_app_uri_template`, the template does not contain `{client_id}` exactly once, or the expansion is not a URL on the issuer's origin. A discovery read that fails throws `Directory discovery failed: <status>` or the fetch error; one that takes longer than 10 seconds throws the timeout. A failed or timed-out read is not kept, so the next call reads again; a successful one is kept for the client's life, so a template the directory changes reaches your app at its next start.
+- **Warm it at startup and bound it on page loads.** Call `void oauth.accountAppUrl().catch(log)` when the process starts, so the discovery read is usually done before the first page needs it. A page that must not wait on the directory races it against a short timer (a couple of seconds, under the SDK's 10 s) and hides the link when the race is lost; the read keeps running and a later page load reuses its result.
+
+### Testing your app
+
+To test code built on `OAuth2Client` or `Crouter` without a real cloud, pass `fetch` and `issuer` from a `FakeCloud` (`@north-light/sdk/testing`): the fake directory and runtime answer your real client, refusals and refreshes included. See [[crouter-sdk/testing]].
+
+## Options
+
+| Option | Type | Default | Meaning |
+|---|---|---|---|
+| `baseURL` | `string` | `CRTR_BASE_URL`, else unset | `http(s)://host:port` of a daemon TCP listener. |
+| `socketPath` | `string` | `CRTR_SOCKET`, else `${CRTR_HOME}/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock` | Unix socket. Node only; throws in a browser. |
+| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. The owner token or a scoped token from `crtr sys connect`; a scoped token's ceiling is enforced per request (see [[crouter-sdk/getting-started]]). Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
+| `timeout` | `number` (ms) | `30_000` | Per-request wall clock. Does not apply to a stream. |
+| `maxRetries` | `number` | `2` | Transient-failure retries. Never applied to `POST` or `PATCH` — see [[crouter-sdk/errors]]. |
+| `defaultHeaders` | `Record<string, string>` | `{}` | Merged into every request. |
+| `headers` | `Record<string, string>` | unset | Merged after `defaultHeaders`; a matching name wins unless `token` is set, in which case the generated `Authorization` header wins at construction. |
+| `fetch` | `typeof fetch` | global `fetch`, or the socket implementation when `socketPath` is used | Transport override, for proxies and instrumentation. |
+| `autostart` | `boolean` | `true` for a socket, `false` for `baseURL` | On a cold socket, run `crtr sys daemon start` and retry once. Node only. |
+
+### Environment-variable fallbacks
+
+Every fallback above is read at construction, not at request time.
+
+| Variable | Fills |
+|---|---|
+| `CRTR_BASE_URL` | `baseURL` |
+| `CRTR_SOCKET` | `socketPath` |
+| `CRTR_HOME` | the directory the default socket path is resolved under (`$CRTR_HOME/crtrd.sock`) |
+| `CRTRD_TOKEN` | `token` |
+
+An explicit option always beats its environment variable.
+
+## Transport selection
+
+`baseURL` wins if it is set; otherwise `socketPath`; otherwise the default socket path. **Passing both `baseURL` and `socketPath` throws `TypeError` at construction** — exactly one transport per client. In a browser, `new Crouter({})` has no daemon transport; give it the saved `baseURL` and token before making requests.
+
+There is one request path. The client issues every request through the Web `fetch` API, which a browser and Node both supply globally. The unix socket is not a second transport — it is a `fetch` implementation the SDK installs when `socketPath` is set, built on `node:http` with `{ socketPath }`, returning a standard `Response` whose `body` is a `ReadableStream`. Streaming, abort, headers, and error parsing therefore have exactly one implementation, and the browser build never sees Node code.
+
+## Autostart
+
+With `autostart` on (the default for a socket), a request that finds a cold socket runs `crtr sys daemon start`, waits for the daemon to serve, and retries the request once. This is what makes `npm i -g crouter` followed by `new Crouter()` work on a machine that has never run the daemon.
+
+Autostart is Node-only and applies only to the socket transport. A `baseURL` client cannot start a daemon it may not even share a machine with, so `autostart` defaults to `false` there; setting it to `true` on a `baseURL` client throws `CrouterError` (`autostart is only valid for the local socket transport`).
+
+## Per-request options
+
+Every request-capable method accepts an options object as its last argument, after any path, body, or query arguments. Each field overrides the client-level default for that one request.
+
+```ts
+const id = 'example-node';
+const signal = new AbortController().signal;
+
+await client.nodes.retrieve(id, {
+  signal,                       // AbortSignal — real cancellation, passed straight to fetch
+  timeout: 5_000,               // ms, this request only
+  maxRetries: 0,                // this request only
+  headers: { 'x-trace': 't-9' } // merged over defaultHeaders
+});
+```
+
+| Field | Type | Effect |
+|---|---|---|
+| `signal` | `AbortSignal` | Aborts the underlying `fetch`. Raises `APIUserAbortError`. |
+| `timeout` | `number` (ms) | Overrides the client `timeout`. |
+| `maxRetries` | `number` | Overrides the client `maxRetries`. |
+| `headers` | `Record<string, string>` | Merged over `defaultHeaders`, client `headers`, and the token-generated header; a matching name, including `Authorization`, wins. |
+
+`signal` is real cancellation. The long-polling helpers (`waitForOutcome`, `createAndWait`, `parse`) honour it between polls and during the in-flight request, and aborting them stops the client — it does not cancel the node. To stop the run itself, call `client.nodes.cancel(id)` or `client.nodes.interrupt(id)`. Streams use `NodeEventsOptions`: the same fields except `timeout`, plus `after` for `nodes.events`; see [[crouter-sdk/streaming]].
+
+## What is not on the client
+
+| Convention | Why it is absent |
+|---|---|
+| `.withResponse()` / `.asResponse()` | They exist to hand back the raw `Response` and an `x-request-id`. The daemon emits no request id, and a caller who needs raw bytes uses `client.request()`. |
+| `apiKey` | The daemon's credential is a token (`CRTRD_TOKEN`) everywhere in the product. `apiKey` would be a second name for one thing. |
+| Resource-prefixed ids | Node ids have their own format. The SDK validates unsafe path identifiers locally with `TypeError`, and the daemon validates the request too; nothing is re-prefixed. |
+
+## Wire naming
+
+Wire fields are `snake_case` — `output_schema`, `root_lifecycle`, `pin_cwd`, `final_report_path`. The SDK does not camelize them. Namespaces and method names are camelCase (`client.nodes.waitForOutcome`, `client.nodes.worktree`).
+
+Timestamps are ISO-8601 strings (`created`, `settled_at`, `finalized_at`, `deadline_at`), not Unix seconds.
+
+For a sign-in that requested runtime scopes plus `profile`, read the name and `picture` from the verified ID token: `if (connection.idToken) profileFromClaims(await oauth.verifyIdToken(connection.idToken, {nonce}))` (`idToken` is optional on `Connection`).

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

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

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

@@ -0,0 +1,38 @@
+---
+kind: knowledge
+when-and-why-to-read: When you need App-facing error envelope, this knowledge
+  should be read because Contract 2 codes and the HTTP refusal body for crouter
+  cloud apps.
+---
+
+# App-facing error envelope
+
+crouter cloud's app-facing HTTP endpoints use contract 2's error body. An app's **own** endpoints can use the same shape with `origin: 'app'`. The SDK publishes the fixed code tuples:
+
+```ts
+import { errorCodes, type ErrorEnvelope } from '@north-light/sdk/errors';
+
+const row = errorCodes.invalid_request;
+// { type: 'invalid_request_error', status: 400, retryable: false }
+
+const body: ErrorEnvelope = {
+  error: {
+    code: 'invalid_request',
+    message: 'Missing prompt',
+    type: row.type,
+    origin: 'app',
+    retryable: row.retryable,
+    request_id: 'req-123',
+    param: 'prompt',
+  },
+};
+// Send body with HTTP status row.status.
+```
+
+The body is `{ error: { code, message, details?, type, param?, origin, retryable, retry_after_s?, reset_at?, request_id, run_id?, question_id?, user_action?, scope? } }`. `origin` is `directory`, `router`, `runtime`, `provider`, or `app`. `type` uses OpenAI's `invalid_request_error`, `authentication_error`, `permission_error`, `rate_limit_error`, or `server_error`. **Status belongs only in the HTTP status line**, not in the body. Send `Retry-After` when `retry_after_s` is set. Keep `request_id` in the body and echo it as a request-id response header. Do not expose stack traces in a 5xx message.
+
+`errorCodes` is keyed by code. Each row gives that code's fixed contract-2 `{ type, status, retryable }` tuple; the daemon renderer uses this module for `type` via `@north-light/api`. An unsatisfiable byte range is `range_not_satisfiable` (416), an upstream model failure is `upstream_model_unavailable` (503, retryable), and an upstream vendor sign-in refusal is `upstream_refused` (502). The renderer preserves the thrown HTTP status and retry decision; throw sites must choose a code whose tuple matches those values. If no existing code fits an app-specific failure, declare an app code with a consistent type/status and document it in the app's OpenAPI spec.
+
+Not every error has a fixed tuple. `provider_error` carries the provider's varying 4xx status and is not in `errorCodes`; `usage` is a legacy socket/loopback code that becomes `invalid_request` on the app-facing listener. `stream_gap`, `stream_dropped`, and `stream_error` are stream protocol codes with beta-defined behavior, not ordinary static HTTP refusal rows. SDK-generated connection failures (`daemon_unavailable`, `transport_error`, `daemon_request_interrupted`, `request_timeout`, `daemon_health_unavailable`) are not daemon refusals. `runtime_unreachable` applies to a hosted router, `runtime_provisioning`, `grant_removed`, `grant_suspended`, `refresh_token_expired`, and `refresh_token_reused` are raised by the SDK for directory token responses (see [[crouter-sdk/client]]), and `wake_timeout` is reserved for the later hosted sleep/wake stage; their presence in the table does not mean the local daemon emits them today.
+
+`ErrorEnvelope` models the **full app-facing response**, not the SDK's permissive `ErrorBody` used to parse older and socket responses. A socket or v0 loopback response can have only `code`, `message`, and optional `details` (with run-layer fields in some cases); never assume `type` or `request_id` exists on those transports. `APIError.status` is separate from the parsed JSON body. See [[crouter-sdk/errors]] for error classes, transport failures, and retry rules.