@north-light/cli 0.3.472 → 0.3.474

package/docs/apps/coding-agents.md

@@ -0,0 +1,72 @@
+---
+title: Use your coding agent
+description: What npx @north-light/sdk init and skill install for Claude Code, Codex, Cursor and Copilot, where the skill lives, and how it stays in step with your SDK version.
+---
+
+# Use your coding agent
+
+The `northlight` skill teaches a coding agent the whole path in the [quick setup](/docs/quickstart): the commands, the console fields, the code patterns and the rules. `npx @north-light/sdk init` installs it into your project. The skill needs no account and no crtr.
+
+## Install it
+
+For a new app, `init` installs it with everything else:
+
+```bash
+npx @north-light/sdk@latest init my-app
+```
+
+For a project that already has a `package.json`, run `npx @north-light/sdk init` in it. It adds `@north-light/sdk` at an exact version, makes a key if `local/app-key.json` does not exist, installs the skill, and writes no app code. It never overwrites a file: if one is in the way, it names the file and exits non-zero.
+
+To install only the skill, or to replace an older copy:
+
+```bash
+npx @north-light/sdk skill
+```
+
+`skill` always replaces the `northlight` skill it finds. `--print` writes the skill to stdout instead of to files.
+
+## Where it goes
+
+| Agent | In the project (default) | With `--global` |
+|---|---|---|
+| Codex, Cursor, GitHub Copilot, VS Code | `.agents/skills/northlight/SKILL.md` | `~/.agents/skills/northlight/SKILL.md` |
+| Claude Code | `.claude/skills/northlight/SKILL.md` | `~/.claude/skills/northlight/SKILL.md` |
+
+`--agent claude`, `--agent agents` or `--agent all` (the default) picks which. `all` writes both places. Cursor and Copilot also read `.claude/skills`, so they may list the skill twice. Use `--agent agents` or `--agent claude` to write one place. `init` takes `--global-skill` where `skill` takes `--global`.
+
+The project copy is the default so it is committed with the project, and teammates get it from git. It matches the SDK version your project pins.
+
+Checked: the files `init` writes, and that `skill` rewrites both, from the SDK source built on this branch. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
+
+## Without a project: the hosted skill
+
+An agent that has no project yet can read the hosted copy:
+
+> Read https://sdk.docs.northlight.ai/SKILL.md and follow it.
+
+The agent runs `npx @north-light/sdk@latest init` and then follows the quick setup. It asks you to do the browser steps: sign up, register the app at `https://account.northlight.ai/console/new`, and add permissions. The hosted copy matches the SDK version the docs site was last built from.
+
+## How it stays current
+
+The skill's frontmatter carries `metadata.sdk-version`. Its first instruction tells the agent to compare that number with `node_modules/@north-light/sdk/package.json`. If they differ, the agent runs `npx @north-light/sdk skill`, which rewrites the skill from the installed package. A skill therefore always documents the SDK your project pins, and a newer SDK never gets documented against an older one.
+
+## Example prompts
+
+After `init`:
+
+> Add a "Summarize my day" button to the app. It starts a run on the signed-in person's runtime with `runs.start`, waits with `runs.wait`, and shows the report. Use the northlight skill.
+
+Starting from nothing:
+
+> Read https://sdk.docs.northlight.ai/SKILL.md and build me an app where people sign in with Northlight and the app texts them a daily summary. Tell me which console steps I need to do.
+
+## Rules the skill gives your agent
+
+Your agent reads them from the skill. They are worth knowing as the person reviewing its work:
+
+- Pin the exact SDK version.
+- Take scope strings from the console's Add permissions list, never from memory.
+- Never print, paste or commit `local/app-key.json`.
+- Reach a person's runtime with `oauth.client(userId)`, not `new Crouter()`.
+- Use a persistent `ConnectionStore` in production.
+- Get data back with `runs.parse`, not by reading `runs.trace`.

package/docs/apps/concepts/apps-and-sign-in.md

@@ -0,0 +1,82 @@
+---
+title: Apps and sign-in
+description: What registering an app creates, how an app proves who it is with a key pair, and the authorization-code flow with PKCE that OAuth2Client runs.
+---
+
+# Apps and sign-in
+
+An app is a registration in the Northlight directory: a client ID, a public signing key, the redirect URIs people return to after sign-in, and the list of scopes the app may ask for. You create it in the console at `https://account.northlight.ai/console/new`. Your server proves it is that app by signing its requests with the matching private key.
+
+## What registration holds
+
+| Part | What it is |
+|---|---|
+| **Client ID** | The app's id. The console shows it after you register. Your code passes it as `clientId`. |
+| **Origin URL** | Where your app runs. People see its domain as your app's maker. `http://localhost:<port>` is accepted for development. |
+| **Redirect URIs** | The only places sign-in may return to. A URI must match exactly: `localhost` and `127.0.0.1` are different, and the port counts. `http://localhost`, `http://127.0.0.1` and `http://[::1]` are accepted over plain http; every other URI is `https`. |
+| **Public key** | The half of your key pair the directory keeps. |
+| **Scopes** | What the app may ask for. See [Scopes and grants](/docs/concepts/scopes-and-grants). |
+
+Name, logo and "Why your app needs access" appear on the consent page.
+
+## A key pair, not a client secret
+
+An app has no client secret. It signs a short assertion with its private key (`private_key_jwt`, the only token authentication method the directory supports) each time it exchanges a code or refreshes a token. The directory checks the signature against the public keys it holds.
+
+- `npx @north-light/sdk keygen` writes the private key to `local/app-key.json` (mode `0600`) and prints the public key as JSON. `init` runs it for you. Paste the public key into **Public key** when you register, or under **Add key** on the app's **Sign-in** tab.
+- The private key stays on your server. Never paste it, log it or commit it. The console refuses a pasted private key.
+- An app holds at most 2 active keys, so you can add a new one beside the old one, switch, and retire the old one without downtime.
+- Instead of pasting keys you can give the directory a **JWKS URL** (**Use a JWKS URL instead** on the **Sign-in** tab).
+- Until a key is added, `exchangeCode` throws an `AuthenticationError`.
+
+## The sign-in flow
+
+`OAuth2Client` runs the OAuth 2.0 authorization-code flow with PKCE (`S256`) and an OpenID Connect nonce. Your two routes are short:
+
+<include lang="ts">../../../examples/apps/quickstart-server.ts#login</include>
+
+`authorizeUrl` returns the URL to redirect to, plus three values to keep for this sign-in: `codeVerifier`, `state` and `nonce`. The example keeps them in a `Map` keyed by `state`. Use your own session store.
+
+<include lang="ts">../../../examples/apps/quickstart-server.ts#callback</include>
+
+On the callback:
+
+1. Read `state` and `code` from the query. Find what you saved for that `state`. If nothing is there, send the person back to the login route.
+2. Call `exchangeCode` with the code, the saved `codeVerifier` and `nonce`, the `state` from the query as `state`, and the value you saved as `expectedState`. Never pass the callback's `state` for both. A missing or different `expectedState` throws `CrouterError` with code `oauth_state_mismatch` before the code is sent anywhere.
+3. `exchangeCode` verifies the ID token (ES256 signature, issuer, audience and nonce) when it has one, and returns a `Connection`. Save it in your [`ConnectionStore`](/docs/concepts/connections).
+
+Then set your own session for the person. The SDK does not manage your sessions.
+
+### Scopes decide what comes back
+
+A sign-in that asks only for `openid`, optionally with `email` and `profile`, creates no connection. Finish it with `oauth.exchangeIdentity(...)`, which returns the verified `Identity` (`sub`, and `email`, `name` and `picture` when approved and present). A sign-in that asks for runtime scopes such as `crtr:llm` finishes with `exchangeCode`. Each method refuses the other's answer with `oauth_exchange_mismatch`.
+
+### When the directory refuses to sign someone in
+
+If the app is in testing and the person is not a tester, the directory redirects to your callback with `error=access_denied` and `error_description=app_in_testing` instead of a `code`. `authorizationRefusalOf(url)` reads it. See [Testing mode](/docs/concepts/testing-mode).
+
+## Keep sign-in secrets out of HTTP logs
+
+The callback URL carries a one-use `code` and your `state`, and the response that follows carries a session cookie. Request loggers such as `pino-http` log full URLs and response headers by default. Log the method, the path without the query string, an id and the response status, for every route, not only the callback. Redacting only the `authorization` and `cookie` request headers does not cover these values.
+
+```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'],
+  },
+});
+```
+
+Test it: send a callback with a recognizable fake code and assert that the code, the state and the cookie never appear in the log output.
+
+## Checked and not checked
+
+Checked on production: the discovery document lists `S256` and `private_key_jwt`, and the login route of the quickstart server redirects to `https://account.northlight.ai/authorize` with the PKCE challenge and nonce. The rest is from the SDK and directory source. A full sign-in with a real account is not yet checked on production.

package/docs/apps/concepts/connections.md

@@ -0,0 +1,106 @@
+---
+title: Connections
+description: A connection is the stored token set for one person. How ConnectionStore keeps it, how it refreshes, and what to do when the directory refuses a refresh.
+---
+
+# Connections
+
+A connection is what your server stores for one person after they sign in: their user id, the URL of their runtime, a refresh token, and a short-lived access token. `oauth.client(userId)` loads it and gives you a client on that person's runtime. You keep connections in a `ConnectionStore`.
+
+```ts
+const connection = await oauth.exchangeCode({code, codeVerifier, state, expectedState, nonce});
+await store.save(connection);
+
+// Later, in any process that shares the store:
+const runtime = await oauth.client(connection.userId);
+```
+
+Access tokens last 10 minutes. Refresh tokens rotate on every use and expire after 90 days without one. `oauth.client(userId)` refreshes the access token when it needs to. When nothing is stored for the id it throws `CrouterError` with code `not_connected`: send the person through sign-in again.
+
+## The store
+
+`ConnectionStore` has `load(userId)`, `save(connection)`, `lock(userId, fn)` and `remove(userId, refreshToken)`, and may have `listStale(before)`.
+
+- `MemoryConnectionStore` keeps connections in one process. Use it for development and tests. Every sign-in is lost when the process restarts, and its lock does not reach other processes.
+- `PostgresConnectionStore` from `@north-light/sdk/stores/postgres` is the production store. Install `pg` in your app. It locks across every process that shares the database.
+
+```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 first:
+
+```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 table holds credentials. Restrict database access and encrypt backups. All workers must use the same database. The store holds an advisory lock for the whole refresh, so size the pool for concurrent refreshes and do not set a transaction timeout shorter than a token request.
+
+### Why the lock matters
+
+Two processes refreshing one person at once would spend the same refresh token twice, and the directory ends the grant's refresh tokens when it sees that (`refresh_token_reused`). `lock` makes the SDK reload the connection, refresh only if no other process already did, and save the result while it holds the lock. If you write your own store, `lock` must hold across every process that shares it and commit what `fn` wrote when `fn` resolves.
+
+## When a refresh is refused
+
+When the directory refuses to refresh a stored connection, the SDK runs your `onRefusal(refusal)` once the lock is released, then removes the stored connection, then rejects the call that needed the refresh with an `AuthenticationError` (status 401, `userAction: 'reconnect'`). Handle every dead connection in that one place:
+
+```ts
+const oauth = new OAuth2Client({
+  clientId, privateKey, 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:
+try { await (await oauth.client(userId)).runs.start({prompt}); }
+catch (error) { if (refusalOf(error)) return showSignInAgain(); throw error; }
+```
+
+A `Refusal` is `{kind, code, userId, grantId, error}`. **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 or deleted their account. 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 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. | Keep everything, stop calling for them, show the app as paused. If they connect again, the same grant comes back. |
+| `app_in_testing` | `paused` | Your app is in testing and this person is not a tester (they were removed, or their email or phone stopped matching). The grant is revoked, not removed. | Keep everything, stop calling for them, and tell them the developer must add them. If you add them back and they sign in again, the same space returns. |
+| `refresh_token_expired` | `reconnect` | The refresh token went 90 days unused. The grant is still active. | Keep everything. Run sign-in again; the consent page is skipped. Prevent it with `refreshIdleConnections`. |
+| `refresh_token_reused` | `reconnect` | Two processes raced on one refresh token. | Keep everything. Fix the store's `lock`, then reconnect. |
+| `grant_revoked` | `reconnect` | The directory refused without naming a reason. | Keep everything and reconnect. Never delete data on this code. |
+
+`onRefusal` runs at least once per dead connection, so make it idempotent. If it throws, the connection stays stored, the caller still receives the directory's refusal, and the next use calls the handler again. It must not call the runtime for `refusal.userId`: `oauth.client(userId)` for that user inside the handler throws `CrouterError` code `refusal_handler_reentry`.
+
+`refusalOf(error)` returns a `Refusal` only for an error raised while refreshing a stored connection. A 429, `cap_exhausted`, `scope_missing`, or an `invalid_client` refusal of your app's key is not a refused connection, and `refusalOf` returns `null` for it.
+
+## Keep offline people connected
+
+A refresh token expires after 90 days without use. Run a worker, for example daily, that calls:
+
+```ts
+await oauth.refreshIdleConnections({olderThanMs: 30 * 24 * 60 * 60 * 1000});
+```
+
+It refreshes every connection last saved before the cutoff, through the store's lock, and returns `{refreshed, refused, failures}`. A refused connection goes through `onRefusal` and is removed. `failures` holds connections that could not be refreshed and are still stored; the next run retries them. The SDK starts no timer. The store needs `listStale(before)`, which both `MemoryConnectionStore` and `PostgresConnectionStore` have.
+
+## Signing in a visitor
+
+A person who only needs to be recognized, not connected, signs in with identity only: request `openid`, optionally with `email` and `profile`, and no runtime scope. Finish with `exchangeIdentity`, not `exchangeCode`. An `Identity` is not a connection: no runtime URL, grant or refresh token, nothing goes in the store, and you keep your own session. To act for that person later, send them through `authorizeUrl` again with the runtime scopes you need.
+
+## Checked and not checked
+
+From the SDK source and tests. The refresh and refusal paths against `account.northlight.ai` are not yet checked on production.

package/docs/apps/concepts/providers.md

@@ -0,0 +1,59 @@
+---
+title: Providers
+description: A provider is a service the person's runtime calls for your app. Provider scopes, providers.tools, providers.call, and apps that require a provider.
+---
+
+# Providers
+
+A provider is a service that a person's runtime calls on your app's behalf: sending a text, searching the web, reading their connected accounts, or using their device. Northlight runs the first-party providers (sms, search, integrations, context and device). Your server asks the person's runtime to call one with `providers.call`.
+
+## Scopes
+
+Each provider's tools are grouped, and each group is a scope named `<provider>:<group>`. The `sms` provider has one: `sms:send`. Your app can call a provider only if all three of these hold:
+
+1. The scope is on the app's **What it asks for** list (console → **Add permissions**).
+2. Your sign-in requested it (`authorizeUrl({scopes: […]})`).
+3. The person approved it on the consent page.
+
+Take scope strings from the **Add permissions** list. Do not guess them. [Providers](/docs/providers) lists the first-party providers.
+
+## Find the tools, then call one
+
+`providers.tools('<provider>')` lists the tools the person has granted your app, with their descriptions and parameters. Tool names and arguments come from there, never from memory:
+
+<include lang="ts">../../../examples/apps/provider-tools.ts</include>
+
+`providers.call({provider, tool, arguments})` makes the call and returns the tool's output. The quickstart sends a text this way:
+
+<include lang="ts">../../../examples/apps/quickstart-server.ts#provider-call</include>
+
+`send` takes a required `body` and an optional `file`. It has no recipient argument: it texts the verified phone of the person who signed in to your app, from Northlight's number, at most 50 texts per person per UTC day. Calling `providers.tools()` with no provider lists every provider the person's runtime can reach.
+
+A call is refused when the scope is missing from the grant. The refusal is an `APIError` whose code says why (`scope_missing` for a scope the run or grant lacks).
+
+## Providers your app requires
+
+Some apps do not work until a provider is set up for the person. Name it under **What your app requires** on the **What it asks for** tab. The person is then taken through that provider's setup the first time they sign in. Context, for example, asks for a profile URL, and its state stays `pending` for a few minutes afterwards.
+
+Read the state on each request that depends on it. `runtime.grant.get()` returns `dependencies`, one entry per required provider, keyed by provider id (or `{}` when the app requires none):
+
+```ts
+const {dependencies} = await runtime.grant.get();
+const context = dependencies['context']; // {state, message?, next} or undefined
+if (context?.state !== 'ready') {
+  // Show context.message and link context.next; never hard-code either.
+}
+```
+
+| `state` | Meaning |
+|---|---|
+| `not_started` | The person has not done their part. |
+| `pending` | The provider is working. |
+| `ready` | Calls that depend on it work. |
+| `failed` | Setup failed. `message` says why. |
+
+`message` is the provider's own sentence, present for `pending` and `failed`. `next` is the absolute URL of the setup page for this provider and your app; add a `return_to` query parameter with your app's registered origin so the person returns to you. An entry is missing when the runtime has not synced the grant since the app began requiring the provider: treat that as `not_started`. The runtime does not block your calls for you, so refuse the dependent operation yourself. To act the moment a state turns `ready`, follow it with `oauth.watchGrants`; see [Grant changes](/docs/guides/grant-changes).
+
+## Checked and not checked
+
+From the SDK source (`providers.tools`, `providers.call`, `grant.get`) and the directory source. The sms limits come from the existing SDK guide. A real `providers.call` for `sms` on production is not yet checked.

package/docs/apps/concepts/runs.md

@@ -0,0 +1,94 @@
+---
+title: Runs
+description: A run is an agent working on the person's runtime, with their AI subscription, under the grant's scopes. Status, outcome, result, activity, and how to bound one.
+---
+
+# Runs
+
+A run is an agent that works on a person's Northlight runtime, on your behalf and with their AI subscription, under the scopes of their grant. Your server starts it with `runs.start`, and the run keeps going on the runtime whether or not your server is waiting.
+
+<include lang="ts">../../../examples/apps/quickstart-server.ts#run</include>
+
+`runs.start` returns at once with a `run_id`. `runs.wait(runId)` long-polls until the run is no longer `running`.
+
+## Status
+
+`RunObject.status` is one of:
+
+| `status` | Meaning |
+|---|---|
+| `running` | The run's root agent is working. |
+| `waiting_on_user` | The agent asked the person a question (`pending_question_ids` lists them). |
+| `idle` | The agent finished a turn and is waiting. A reply to your prompt leaves the run `idle`. Send `runs.message` for another turn, or `runs.cancel` to end it. |
+| `settled` | The run has ended. `outcome` says how. |
+
+`runs.wait` returns on `waiting_on_user`, `idle` and `settled`, so check the status before you read a result.
+
+## Outcome and result
+
+A `settled` run has an `outcome`:
+
+| `outcome.kind` / `reason` | Meaning |
+|---|---|
+| `result` | The run finished. If you passed an `output_schema`, `result` holds the validated value. |
+| `declined` | The agent could not honestly satisfy the schema. `details` has `reason`, `code` and `retryable`. |
+| `canceled` | You or the person ended it. |
+| `deadline_exceeded` | A deadline ended it. |
+| `runtime_error` | The runtime failed. `details.crouter_reason` says why. |
+
+`last_report` is the agent's last report text. To get data back, give the run an `output_schema` and read it with `runs.parse`: see [Typed results](/docs/guides/typed-results). Do not parse the assistant's text out of `runs.trace`. The trace is what the model said, not a value anything checked.
+
+## Scopes
+
+`runs.start({prompt, scopes})` starts the run with only those scopes. `crtr:llm` goes in every run. See [Scopes and grants](/docs/concepts/scopes-and-grants).
+
+## Showing progress
+
+While a run is `running`, `runs.get(runId).activity` says what the root agent is doing now. It is `null` in any other status.
+
+| `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) |
+| `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 result |
+
+```ts
+const run = await runtime.runs.get(runId);
+const badge = run.activity?.phase === 'tool' ? `Running ${run.activity.tool.name}` : run.activity?.phase ?? run.status;
+```
+
+`activity` covers the root agent only and is read each time you call `runs.get`, so a phase shorter than your poll interval can be missed. To show text as it streams, follow `runs.events` or `runs.reply` instead of polling. Do not read `runs.trace` for progress.
+
+## Bounding a run
+
+`runs.wait` and `runs.parse` take a `signal`. 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('took too long')), 10 * 60_000);
+let runId: string | undefined;
+try {
+  const started = await runtime.runs.start({prompt, scopes: ['crtr:llm']});
+  runId = started.run_id;
+  const run = await runtime.runs.wait(runId, {signal: controller.signal});
+  // read run.status, run.outcome, run.result
+} catch (error) {
+  if (controller.signal.aborted && runId) await runtime.runs.cancel(runId);
+  throw error;
+} finally {
+  clearTimeout(timer);
+}
+```
+
+`runs.parse` rejects with `APIError` code `run_idle` when the agent stopped without submitting a result. The runtime reminds the agent of the schema up to three times, then leaves the run `idle` with the schema still armed. Send `runs.message` to nudge it, or `runs.cancel` to end it. A question from the run rejects with `waiting_on_user` unless you pass `onQuestion`.
+
+## Learn when a background run ends
+
+A run you start and do not wait on ends while nobody holds a request. `oauth.watchRuns(...)` follows those runs for you and calls `onEnded` for each one that comes to rest. See [Background runs](/docs/guides/background-runs).
+
+## Checked and not checked
+
+From the SDK source and its tests. The `runs.start`, `runs.wait` and `activity` behavior against a real runtime on production is not yet checked.

package/docs/apps/concepts/scopes-and-grants.md

@@ -0,0 +1,62 @@
+---
+title: Scopes and grants
+description: A scope is what your app may ask for, a grant is what one person allowed, and a run's scopes narrow it further.
+---
+
+# Scopes and grants
+
+Three things limit what your app can do for a person: the scopes your app **may ask for**, the **grant** that person approved, and the `scopes` list of each run you start. Each can only narrow the one before.
+
+| Layer | Set by | Where |
+|---|---|---|
+| What the app may ask for | You | The console, app page, **What it asks for** tab → **Add permissions** |
+| The grant | One person | The consent page, when they connect your app |
+| A run's `scopes` | Your code | `runs.start({scopes: […]})` |
+
+## What your app may ask for
+
+An app can only ask for scopes it has been given. A new app starts with `crtr:llm` and `crtr:act`. On the **What it asks for** tab, **Add permissions** searches the full list: agent access, parts of the person's space, and the tools of each provider. Take scope strings from that list or from `providers.tools`. Do not invent them. Without `sms:send` on the list, the consent page does not offer it and `providers.call` for `sms` is refused.
+
+The same tab holds **What your app requires** (providers the app does not work without: see [Providers](/docs/concepts/providers)) and **Monthly spend cap**, the most your app can spend on each person's AI subscription in a month. People see the cap on the consent page.
+
+## The protocol scopes
+
+`openid`, `email` and `profile` are available to every app and are not saved in the list. You request them in `authorizeUrl` for sign-in: `openid` for the person's id, `email` for their email, `profile` for their name and photo. A request with only these scopes signs the person in without creating a grant or a connection.
+
+## The grant
+
+When a person connects your app, the consent page shows each scope you asked for and the spend cap. What they approve is the **grant**. Your `authorizeUrl` should request only the scopes your app uses, because the grant holds what was requested and approved. A person can change or remove the grant from their Northlight account. Link to that page with `await oauth.accountAppUrl()`; never build the path yourself.
+
+If you change what the app asks for, people already connected approve the new list the next time they sign in. Lowering the spend cap applies to everyone at once; raising it reaches each person only after they approve again.
+
+## What each scope gates
+
+A run can only do what the grant holds and the run's own `scopes` allow. Narrowing a run's `scopes` removes abilities, so pass the smallest list that works.
+
+| Scope | A run (or your server) with it can | Without it |
+|---|---|---|
+| `crtr:llm` | Use the person's AI subscription for the run's model calls. List it in every run's `scopes`. | The run has no model access. |
+| `crtr:act` | Start runs (`runs.start`) and use a shell. Every bash call on the hosted (Linux) runtime needs it. | `runs.start` is refused with `403 scope_missing`. Add it on the **What it asks for** tab and list it in the run's `scopes`. |
+| `crtr:schedule` | Create, pause, resume and run schedules. | Schedule calls are refused. |
+| `crtr:memory:read:user`, `crtr:files:read:user:.`, `crtr:files:rw:user:.` | Read the person's documents beyond their public ones; read or write the person's files. | The run sees only the person's `public` documents and its own app space. |
+| `sms:send` (a provider scope) | Call the `sms` provider's `send` tool, which texts the person's own verified phone. | `providers.call` is refused. |
+
+`crtr:act` requires `crtr:llm`, so drop both together. A run that only reasons and submits a typed result needs only `crtr:llm`.
+
+Other scopes follow the same shape. A provider scope is `<provider>:<tool group>`; see [Providers](/docs/concepts/providers). Scopes for the person's files and documents are named `crtr:files:…` and `crtr:memory:…`; copy them from **Add permissions**.
+
+## A run's `scopes`
+
+```ts
+await runtime.runs.start({prompt, scopes: ['crtr:llm']});
+```
+
+A run's list must stay inside the grant, and a child agent never regains a scope its parent's list dropped. Leaving `scopes` out gives the run everything the grant holds. Prefer a list.
+
+## Your app's own space
+
+Your app has its own space on each person's runtime: documents and files owned by your app. Your server and runs started without a `scopes` list read and write it freely. A run started with a `scopes` list needs `crtr:memory:read:app:<your client id>` or `crtr:memory:rw:app:<your client id>` to touch it. Another app's space is reachable only where that app allows it.
+
+## Checked and not checked
+
+From the SDK source, the directory console source and the existing SDK guide. `403 scope_missing` for a missing `crtr:act` and the consent page's behavior are not yet checked on production.

package/docs/apps/concepts/testing-mode.md

@@ -0,0 +1,36 @@
+---
+title: Testing mode
+description: A new app is in testing. You and up to 100 testers can sign in. How to add testers, what everyone else sees, and how to get an app verified.
+---
+
+# Testing mode
+
+A new app is in testing. Only you and up to 100 testers can sign in to it, and it is not shown in the marketplace. You can sign in as yourself with no setup. Verification, which opens the app to everyone, is by email to support@northlight.ai.
+
+## Add testers
+
+On the app's page in the console at `https://account.northlight.ai/console`, open the **Testers** tab, enter the **Email or phone number** on the person's Northlight account, and choose **Add tester**. An email matches only while it is verified on that account. The person can sign in right away. Nobody gets a message, so tell them. The tab lists everyone on the list and lets you remove them.
+
+Removing a tester stops their access at once, including their refresh tokens, and keeps their data. Adding them back and having them sign in again restores it.
+
+## What a person who is not a tester sees
+
+The directory shows "*app name* is still in testing" and redirects to your `redirectUri` with `error=access_denied`, `error_description=app_in_testing` and your `state` instead of a `code`. `authorizationRefusalOf` reads it from the callback's query and returns `{code: 'app_in_testing', error: 'access_denied', state}`. A person who pressed Cancel (`access_denied` with no description) returns `null`.
+
+<include lang="ts">../../../examples/apps/quickstart-server.ts#callback</include>
+
+The quickstart server shows "This app is still in testing" and asks the person to contact the owner. Check `refused.state` against the saved state before showing anything.
+
+A person already connected who is later removed as a tester has their grant revoked, not removed. Their next refresh is refused with `app_in_testing` (`kind: 'paused'`). Keep their data and show the app as paused. See [Connections](/docs/concepts/connections).
+
+## Go public
+
+Email support@northlight.ai to have the app verified. Only Northlight staff can verify an app, and registering never sets it. Include the app name and what it does. A testing app also stays out of the marketplace listing, even once you turn on **Listed** on the **Profile** tab. Apps that existed before testing mode are already verified.
+
+## Test the refusal in code
+
+`@north-light/sdk/testing` has a fake directory that can refuse a sign-in as an app in testing, so you can test this path without a second account. See [Test your app](/docs/guides/test-your-app).
+
+## Checked and not checked
+
+From the SDK source, the console source and the testing-mode specification. Adding a tester, a second person signing in, the `app_in_testing` redirect and removing a tester have not been run on production (not yet checked on production). Those steps need a second account.

package/docs/apps/errors.md

@@ -0,0 +1,117 @@
+---
+title: Errors
+description: What throws and what settles as an outcome, the error classes, refusals, the error envelope, and which calls the SDK retries.
+---
+
+# Errors
+
+## What throws and what does not
+
+**A run's own outcome is returned, never thrown.** A run that declined the schema, hit its deadline or failed comes back as an outcome from `runs.wait` or `runs.parse`. Narrow on it: see [Typed results](/docs/guides/typed-results). Only transport faults, runtime or directory refusals, bad local configuration, and your own abort throw.
+
+An error without `origin` was produced by the SDK because the request reached no server (runtime, router or directory). Show it as a connection failure, never as a refusal.
+
+Codes the SDK raises itself are listed in `sdkErrorCodes`, and `CrouterError.code` is typed `SdkErrorCode`. Both are exported from `@north-light/sdk/errors` alongside `errorCodes` and `ErrorCode`. That subpath also exports `mapError(error)`, which turns a plain `APIError` into its status class below, for test doubles that build errors by hand.
+
+| Code | Means | What to do |
+|---|---|---|
+| `id_token_invalid` | An ID token failed verification (signature, issuer, audience, expiry, missing or mismatched nonce), or a sign-in-only answer had no ID token. A JWKS that can't be fetched or is malformed is not this code: that error is thrown as is. | Restart the sign-in. |
+| `oauth_exchange_mismatch` | The wrong exchange call: `exchangeCode` on a sign-in-only answer, or `exchangeIdentity` on an answer that carries a connection. | Use the call that matches the scopes you requested ([Many users](/docs/guides/many-users#signing-in-a-visitor)). |
+| `oauth_nonce_missing` | `exchangeIdentity` was called without the `nonce` from `authorizeUrl`. | Save the nonce in the visitor's session and pass it back. |
+| `oauth_state_mismatch` | The callback's `state` was missing or differed from the saved one. | Refuse the callback. |
+| `not_connected` | `oauth.client(userId)` or a refresh found no stored connection for that person. | Show "sign in again". |
+| `refusal_handler_reentry` | An `onRefusal` handler called `oauth.client` (or a refresh) for the person whose connection it is handling. | Don't call the runtime for `refusal.userId` inside the handler. |
+| `unauthorized` (401, `AuthenticationError`) | The directory refused your app's client assertion (`invalid_client`) on `exchangeCode`, a refresh or `revoke`, including a refresh inside a client from `oauth.client(userId)`. The message names the key id (`kid`) you signed with and asks whether that key's public JWK is registered. `details` is `{oauth_error: 'invalid_client', kid}`, or `key_thumbprint` instead of `kid` for a key with no `kid`. | Check that the key's public JWK is on the app's **Sign-in** tab ([Manage your app](/docs/guides/manage-your-app)). |
+| `run_idle`, `waiting_on_user` | `runs.parse`: the run stopped without submitting, or waits on a question and you passed no `onQuestion`. | See [Typed results](/docs/guides/typed-results#stopping-without-a-result-run_idle). |
+| `request_timeout`, `deadline_exceeded` | A timeout, or the call's overall deadline passed. | Retry later, or raise the budget. |
+
+A refused stored connection raises the directory's `AuthenticationError`, and `refusalOf(error)` returns the `Refusal`. See [Connections](/docs/concepts/connections).
+
+## Classes and mappings
+
+Every class extends `APIError`, which carries `status`, `code`, `message`, `details` and `headers`.
+
+| Condition | Class |
+|---|---|
+| SDK configuration error | `CrouterError` with `status: 0`, `code: 'crouter_error'` |
+| The runtime does not serve the contract level the SDK requires, or names none | `RuntimeVersionError`, `status: 426`, `code: 'runtime_version_unsupported'`. See below. |
+| HTTP 400 | `BadRequestError` |
+| HTTP 401 | `AuthenticationError` |
+| HTTP 403 | `PermissionDeniedError` |
+| HTTP 404 | `NotFoundError` |
+| HTTP 409 | `ConflictError` |
+| HTTP 413, 422 | `UnprocessableEntityError` |
+| HTTP 429 | `RateLimitError` |
+| Code `deadline_exceeded` | `DeadlineExceededError` (extends `APIConnectionTimeoutError`; status 504; `reason` `elapsed` or `retry_after`, `deadlineAt`, `cause`) |
+| HTTP 504 or code `request_timeout` | `APIConnectionTimeoutError` (extends `APIConnectionError`) |
+| Other HTTP ≥ 500 | `InternalServerError` |
+| A transport failure, or code `transport_error` | `APIConnectionError` |
+| Code `request_aborted` | `APIUserAbortError` |
+| Any other response | `APIError` |
+
+The subclasses add no fields. `status` and `code` on the base class decide everything there is to branch on. They exist so that `catch (error) { if (error instanceof NotFoundError) … }` works.
+
+```ts
+import {ConflictError, NotFoundError, APIConnectionError} from '@north-light/sdk';
+
+try {
+  await runtime.runs.get(runId);
+} catch (error) {
+  if (error instanceof NotFoundError) return showRunGone();
+  if (error instanceof APIConnectionError) return showTryAgain();
+  throw error;
+}
+```
+
+### `426 runtime_version_unsupported`
+
+The SDK sends `Crouter-Required-Contract` and a frozen `Crouter-Minimum-Runtime-Version` with each call. If the runtime does not serve the contract level the SDK requires, the hosting router or the runtime refuses it before handling: nothing was accepted and no idempotency key was recorded. The error is a `RuntimeVersionError`: `requiredContract` and `runtimeContract` (or `null`) name both levels, `sdkVersion` and `runtimeVersion` stay for logging, and it is never retryable. A level is `MAJOR.MINOR`; the runtime satisfies it when it serves the same major and a minor at or above. A runtime that predates the contract level handles the request first, and the SDK then raises after.
+
+In practice it means your SDK is newer than the runtimes, which can happen briefly after an SDK release. Install the previous version or wait, and tell support@northlight.ai. See the [release notes](/docs/release-notes).
+
+## The error envelope
+
+Northlight's app-facing HTTP endpoints answer errors with one body shape. Your 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` is `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, and each row gives that code's fixed `{ type, status, retryable }`. 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). If no existing code fits an app-specific failure, declare an app code with a consistent type and status and document it in your app's API description.
+
+Not every error has a fixed row. `provider_error` carries the provider's varying 4xx status and is not in `errorCodes`. `stream_gap`, `stream_dropped` and `stream_error` are stream protocol codes, not ordinary refusals. `runtime_provisioning`, `grant_removed`, `grant_suspended`, `refresh_token_expired` and `refresh_token_reused` are raised by the SDK for directory token responses ([Connections](/docs/concepts/connections)).
+
+`output_parsed` from `runs.parse` is non-null on a result. A Zod schema supplies its inferred output type; a JSON Schema literal makes it `unknown`.
+
+## Retries
+
+`maxRetries` defaults to `2`, with exponential backoff. It applies to connection errors, and to HTTP 429 and 5xx responses **on `GET`, `HEAD` and `DELETE` only**. Override it per request with `{maxRetries: 0}` or `{maxRetries: 5}`.
+
+**`POST` and `PATCH` are not retried automatically, with two exceptions: `runs.start` and `runs.message`.** A mutation whose response was interrupted may already have been applied, and replaying it would start a second run or deliver a second message. Those two carry an `Idempotency-Key` header: the SDK generates one key per call (or uses the `idempotencyKey` option) and reuses it on every retry of that call. The runtime records the key in the same transaction that accepts the request and holds it for 24 hours, so a retry after a lost response returns the original result and delivers once. Reusing a key with a different body is refused with `409 idempotency_conflict`. Both calls retry transport failures and retryable refusals. A key the SDK generates does not survive a restart of your process: to dedupe across restarts, derive `idempotencyKey` from your own id.
+
+A call with `budgetMs` (or `deadlineAt`) has one deadline over all attempts and waits, a server's `Retry-After` included. A wait longer than the time left rejects at once with `DeadlineExceededError` instead of sleeping. Without a deadline, a keyed send waits out any `retry_after_s`.
+
+A `503 service_unavailable` (`retryable: true`, `origin: 'runtime'`) means the runtime could not confirm the grant the access token names. 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.