@north-light/cli 0.3.472 → 0.3.473

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.

package/docs/apps/guides/background-runs.md

@@ -0,0 +1,78 @@
+---
+title: Background runs
+description: Learn when a run your app started and did not wait on has ended, with RunWatcher or run notices.
+---
+
+# Background runs
+
+A run your app starts and does not wait on (a draft, a scheduled job) ends while nobody is holding a request. Two tools tell your app. Use `RunWatcher` while your server is running. Add run notices when the person's runtime sleeps and your app must wake on output.
+
+## Follow runs with `RunWatcher`
+
+`oauth.watchRuns(...)` returns a `RunWatcher` that follows those runs and hands each ending to `onEnded`, so you write no poll loop:
+
+```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 your own rows. The rows are the durable record: a restarted watcher re-derives everything from them. It is called 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.
+- **Delivery is at least once** per `(runId, status, latest_sequence)`. 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 with `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 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()`** aborts every open long-poll and resolves once every loop has ended.
+
+### Live progress
+
+To show what a run is doing without a second `runs.get` per page, pass `onActivity: async ({userId, runId, activity, run}) => …`. It is called with each read of a still-`running` run whose `activity` differs from the last one handed over, and never for a run at rest. While it is set, running runs are read with `wait: activityWait` (integer 1–25 s, default 2) instead of 25 s. The hook is best effort and never awaited: a throw goes to `onError` and is not retried, and it never delays or changes `onEnded`. A call can finish after that run's `onEnded`, so guard the write on the row still waiting. The phases are listed in [Typed results](/docs/guides/typed-results#showing-progress).
+
+## Run notices
+
+A hosted runtime that sleeps cannot be polled, so it can tell your app when a run has output nobody is reading. If your app has a run notice URL, the runtime sends `POST <run notice URL>` with `Authorization: Bearer <directory token>` and body `{run_id, latest_sequence}`. It sends one when events are appended to one of your runs and no event stream is open, or a stream ended with events unread. A notice carries no content and never keeps the runtime awake. If it cannot be delivered after three quick attempts the runtime drops it; a lost notice delays output until your app next reads from its cursor, and never loses output.
+
+Check each notice with `verifyRunNotice`:
+
+```ts
+import {RunNoticeError, verifyRunNotice} from '@north-light/sdk';
+
+app.post('/run-notices', async (req, res) => {
+  try {
+    const notice = await verifyRunNotice(toFetchRequest(req), {
+      runNoticeUrl: 'https://app.example.com/run-notices', // exactly as registered
+      issuer: 'https://account.northlight.ai',
+      grantee: 'app:<your client id>',
+    });
+    await storeAndReadFrom(notice.userId, notice.runId, notice.latestSequence); // then read events from your cursor
+    res.sendStatus(204);
+  } catch (error) {
+    if (error instanceof RunNoticeError) return res.sendStatus(401); // store nothing
+    throw error;
+  }
+});
+```
+
+`verifyRunNotice` checks the token's signature, issuer, audience (your run notice URL), expiry, scope `crtr:run_notice` and grantee, and returns `{userId, runtime, runId, latestSequence}`. `runtime` comes from the token, never the body. Answer 2xx once the notice is stored. The same or a lower `latest_sequence` is a no-op. In tests, pass `fetch: cloud.fetch` from `FakeCloud` ([Test your app](/docs/guides/test-your-app)).
+
+### Set the run notice URL
+
+The console has no field for this yet. Until it does, set it with crtr on a machine joined to your Northlight account (`crtr sys join`; see [joining a machine](https://crouter.docs.northlight.ai/docs/sdk/guides/apps-on-northlight#1-account-and-join) in the crouter docs):
+
+```bash
+crtr cloud apps set-run-notice-url --app-id <client id> --url https://app.example.com/run-notices
+crtr cloud apps set-run-notice-url --app-id <client id> --clear   # stop notices
+```
+
+The URL must be https (plain http only on localhost in development) and at most 512 characters. `crtr cloud apps get --app-id <client id>` shows it as `run_notice_url`.

package/docs/apps/guides/files-and-documents.md

@@ -0,0 +1,59 @@
+---
+title: Files and documents
+description: Download a file from a person's runtime with files.download, and read the person's public documents with memory.list and memory.get.
+---
+
+# Files and documents
+
+## Download a file
+
+`runtime.files.download(path, options?)` returns the file's raw bytes as a Fetch `Response` (200, or 206 for a `range`) with `Content-Type`, `Content-Length` and `Content-Range`, so you can pipe its body on. `path` is an absolute path on the person's runtime that your app's grant lets it read. Options: `range` (one `Range` header value such as `bytes=0-0` or `bytes=-500`) and `signal`.
+
+```ts
+const response = await runtime.files.download('/apps/<your client id>/files/report.pdf');
+res.setHeader('content-type', response.headers.get('content-type') ?? 'application/octet-stream');
+await pipeline(Readable.fromWeb(response.body!), res);
+```
+
+A non-2xx answer is thrown as an `APIError`, never returned as bytes. A bad `range` is `416`, `invalid_request` with `param: 'range'`. A body cut short mid-stream means the file could not be read to the end. What a path may reach depends on the grant: see [Scopes and grants](/docs/concepts/scopes-and-grants). The client your app gets from `oauth.client(userId)` exposes only `download` from `files`; reading, writing and listing are not available to apps.
+
+## Read the person's public documents
+
+`runtime.memory` is a read-only view of the `knowledge` and `preference` documents the person owns (`memory` and the `/v1/memory` routes are the API's names for this). An app reads the person's `public` documents with `memory.list` and `memory.get`, and needs no scope to do it. It never sees a `friends` or `private` document and cannot tell one from a document that does not exist: both answer `404 not_found`. The list is what the app's agents can read about the person, so an app can show the person exactly which of their documents it draws on.
+
+```ts
+const page = await runtime.memory.list({store: 'user'});
+for (const item of page.items) console.log(item.name, item.preview);
+
+const doc = await runtime.memory.get({store: 'user', name: page.items[0].name});
+console.log(doc.body);
+```
+
+`store` is `'user'` in this release; any other value answers `400 invalid_request` with `param: "store"`. An app whose grant holds `crtr:memory:manage:user` (a first-party app) sees every privacy level. Reading records nothing: no watch, no `read` event, no audit row. Both methods are `GET` requests and follow the SDK's retry rule for safe requests.
+
+### List
+
+`list({store, path?, kind?, limit?, cursor?}, options?)` sends `GET /v1/memory` and returns `{items, next_cursor}`.
+
+| Field | Meaning |
+|---|---|
+| `path` | A folder: lists documents whose name starts with `<path>/`, at any depth |
+| `kind` | `knowledge` or `preference`; both when omitted |
+| `limit` | 1 to 100; default 50 |
+| `cursor` | The previous page's `next_cursor`, with the same `store`, `path` and `kind` |
+
+Items are ordered by `name`. Each item is `{name, folder, kind, preview, summary, privacy, revision, created_at, updated_at}`: `name` has no `user/` prefix, `folder` is the name up to its last `/` (`""` at the top level), and `updated_at` is the current revision's time. Folders are not items, and deleted and unlisted documents are left out. `next_cursor` is `null` on the last page.
+
+`listAll(params, options?)` takes the same fields without `cursor` and yields every item across pages, fetching the next page only as you iterate:
+
+```ts
+for await (const item of runtime.memory.listAll({store: 'user', path: 'work'})) render(item);
+```
+
+### Get
+
+`get({store, name}, options?)` sends `GET /v1/memory/document` and returns a list item's fields plus `body`, `size`, `truncated` and `grantee`.
+
+- `body` is the current markdown as stored; `[[links]]` are not resolved. A body over 1 MiB is cut to its longest whole-character prefix of at most 1 MiB, with `truncated: true`; `size` is always the full length in UTF-8 bytes.
+- `grantee` is `app:<id>` of the app whose agent wrote the first revision, or `null` when the person wrote it.
+- An absent, deleted, `friends` or `private` name rejects with `NotFoundError` (`code: 'not_found'`); a malformed field rejects with `BadRequestError`.