@north-light/sdk 0.3.470 → 0.3.472

package/README.md

@@ -10,7 +10,15 @@
 
 It is a client, not a runtime. It never runs an agent itself, and it does not bundle a model: the daemon it talks to does, using the provider that daemon is signed in to. In Node, `new Crouter()` connects to the local daemon over its unix socket and starts it on the first request if it is not running. In a browser or from another machine it needs the daemon's TCP URL and a bearer token. The lower-level contract it is built on is [`@north-light/api`](https://www.npmjs.com/package/@north-light/api); most applications should install this package instead.
 
-[Docs](https://docs.northlight.ai/docs/sdk) · [Client construction](https://docs.northlight.ai/docs/sdk/client) · [Resource map](https://docs.northlight.ai/docs/sdk/resources) · [Recipes](https://docs.northlight.ai/docs/sdk/guides) · [crouter repository](https://github.com/Northlight-Systems/crouter)
+[Docs](https://crouter.docs.northlight.ai/docs/sdk) · [Client construction](https://crouter.docs.northlight.ai/docs/sdk/client) · [Resource map](https://crouter.docs.northlight.ai/docs/sdk/resources) · [Recipes](https://crouter.docs.northlight.ai/docs/sdk/guides) · [crouter repository](https://github.com/Northlight-Systems/crouter)
+
+## Start an app with the CLI
+
+```bash
+npx @north-light/sdk@latest init my-app
+```
+
+`init` writes a runnable app, a signing key and the `northlight` Agent Skill for Claude Code, Codex, Cursor and Copilot, and prints the console steps. `npx @north-light/sdk skill` refreshes the skill after you change the pinned SDK version, and `npx @north-light/sdk env --client-id <client id>` writes the app's env file. None of them needs crtr.
 
 ## Install
 
@@ -174,7 +182,7 @@ See the complete [localhost SDK demo](https://github.com/Northlight-Systems/crou
 
 ## Reference
 
-The [SDK guide](https://docs.northlight.ai/docs/sdk) covers [client construction](https://docs.northlight.ai/docs/sdk/client), [nodes and scopes](https://docs.northlight.ai/docs/sdk/nodes), [streaming](https://docs.northlight.ai/docs/sdk/streaming), [files](https://docs.northlight.ai/docs/sdk/files), [bash](https://docs.northlight.ai/docs/sdk/bash), [Docker](https://docs.northlight.ai/docs/sdk/docker), [errors](https://docs.northlight.ai/docs/sdk/errors), and the complete [resource map](https://docs.northlight.ai/docs/sdk/resources).
+The [SDK guide](https://crouter.docs.northlight.ai/docs/sdk) covers [client construction](https://crouter.docs.northlight.ai/docs/sdk/client), [nodes and scopes](https://crouter.docs.northlight.ai/docs/sdk/nodes), [streaming](https://crouter.docs.northlight.ai/docs/sdk/streaming), [files](https://crouter.docs.northlight.ai/docs/sdk/files), [bash](https://crouter.docs.northlight.ai/docs/sdk/bash), [Docker](https://crouter.docs.northlight.ai/docs/sdk/docker), [errors](https://crouter.docs.northlight.ai/docs/sdk/errors), and the complete [resource map](https://crouter.docs.northlight.ai/docs/sdk/resources).
 
 `@north-light/sdk/errors` exports `errorCodes`/`ErrorCode` (the daemon's codes), `sdkErrorCodes`/`SdkErrorCode` (the codes the SDK raises itself, such as `oauth_state_mismatch`; `CrouterError.code` is typed with them), and `mapError`, which turns a plain `APIError` into its status class (`NotFoundError`, …) for app tests.
 

package/dist/assets.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The absolute path of a file the build put under the package's `dist/` (for example `skill/northlight/SKILL.md`).
+ * Compiled code finds it beside itself; code running from `src/` under tsx finds it in the package's `dist/`.
+ */
+export declare function assetPath(relative: string): string;

package/dist/assets.js

@@ -0,0 +1,13 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+/**
+ * The absolute path of a file the build put under the package's `dist/` (for example `skill/northlight/SKILL.md`).
+ * Compiled code finds it beside itself; code running from `src/` under tsx finds it in the package's `dist/`.
+ */
+export function assetPath(relative) {
+    const candidates = [new URL(`./${relative}`, import.meta.url), new URL(`../dist/${relative}`, import.meta.url)].map((url) => fileURLToPath(url));
+    const found = candidates.find((path) => existsSync(path));
+    if (!found)
+        throw new Error(`The package is missing ${relative}. Reinstall @north-light/sdk, or run \`npm run build\` in a checkout.`);
+    return found;
+}

package/dist/cli-usage.d.ts

@@ -0,0 +1,13 @@
+export interface CommandUsage {
+    name: string;
+    /** The command's forms after `crouter-sdk` (the bin name); the skill table writes them after `npx @north-light/sdk`. */
+    forms: string[];
+    summary: string;
+    /** What, if anything, needs a joined `crtr`. */
+    crtr: string;
+}
+export declare const COMMANDS: CommandUsage[];
+/** The usage text a command prints on a usage error. */
+export declare function usageOf(name: string): string;
+/** The text `crouter-sdk` prints with no command, an unknown one, or `--help`. */
+export declare function overviewUsage(): string;

package/dist/cli-usage.js

@@ -0,0 +1,49 @@
+// The developer CLI's command table. One source for the usage lines the commands print and for the
+// command table in the generated Agent Skill (scripts/build-skill.mjs reads it), so the two cannot drift.
+// Keep this file free of imports and of TypeScript-only syntax beyond type annotations: the skill generator loads it directly.
+export const COMMANDS = [
+    {
+        name: 'init',
+        forms: ['init [dir] [--agent claude|agents|all] [--global-skill]'],
+        summary: 'Scaffold a Northlight app in an empty or new directory (server.ts, key, env file, skill), or add the SDK, a key and the skill to an existing project. Never overwrites a file.',
+        crtr: 'No',
+    },
+    {
+        name: 'skill',
+        forms: ['skill [--agent claude|agents|all] [--global] [--print]'],
+        summary: 'Write the packaged `northlight` skill into `.agents/skills` and `.claude/skills` (or `~/` with `--global`), replacing an older copy. `--print` writes it to stdout.',
+        crtr: 'No',
+    },
+    {
+        name: 'keygen',
+        forms: ['keygen [--out <path>] [--app <client id>] [--yes]'],
+        summary: 'Write a private signing key to `local/app-key.json` (mode 0600) and print the public JWK to register.',
+        crtr: 'Only with `--app`',
+    },
+    {
+        name: 'env',
+        forms: [
+            'env --client-id <client id> [--origin <url>] [--issuer <url>] [--out <path>]',
+            'env --app <client id> [--out <path>]',
+        ],
+        summary: 'Write `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env`, keeping every other line. `--client-id` makes no network call; `--app` reads them through crtr.',
+        crtr: 'Only with `--app`',
+    },
+];
+const BIN = 'crouter-sdk';
+/** The usage text a command prints on a usage error. */
+export function usageOf(name) {
+    const command = COMMANDS.find((entry) => entry.name === name);
+    if (!command)
+        throw new Error(`unknown command ${name}`);
+    const [first, ...rest] = command.forms;
+    return [`Usage: ${BIN} ${first}`, ...rest.map((form) => `   or: ${BIN} ${form}`)].join('\n');
+}
+/** The text `crouter-sdk` prints with no command, an unknown one, or `--help`. */
+export function overviewUsage() {
+    return [
+        `Usage: ${BIN} <command>`,
+        '',
+        ...COMMANDS.flatMap((command) => command.forms.map((form) => `  ${form}`)),
+    ].join('\n');
+}

package/dist/env-command.d.ts

@@ -1,4 +1,7 @@
-export declare const ENV_USAGE = "Usage: crouter-sdk env --app <client id> [--out <path>]";
+export declare const ENV_USAGE: string;
+/** The directory every Northlight app signs in against, and the origin `init` registers for local development. */
+export declare const DEFAULT_ISSUER = "https://account.northlight.ai";
+export declare const DEFAULT_ORIGIN = "http://localhost:3000";
 /** The variables `env` owns, in the order it writes them. `CROUTER_KEY_FILE` is never one. */
 declare const NAMES: readonly ["CROUTER_ISSUER", "CROUTER_CLIENT_ID", "APP_ORIGIN"];
 type Name = typeof NAMES[number];
@@ -8,8 +11,10 @@ export interface EnvOptions {
 }
 /** Rewrites each assignment to a name in `values`, appends the names it had none for, and keeps every other line. */
 export declare function updateEnvText(text: string, values: Record<Name, string>): string;
+/** The last non-empty value the file assigns to `name`, or undefined. */
+export declare function envValueOf(text: string, name: string): string | undefined;
 /** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
-export declare function keyFileOf(text: string): string | undefined;
+export declare const keyFileOf: (text: string) => string | undefined;
 /** The `crouter-sdk env` command. Returns the process exit code. */
 export declare function runEnv(argv: string[], options?: EnvOptions): Promise<number>;
 export {};

package/dist/env-command.js

@@ -1,30 +1,35 @@
 import { mkdir, open, readFile, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { CRTR_TIMEOUT_MS, notJoinedLines, parseJson, runCrtr, say } from './crtr.js';
-export const ENV_USAGE = 'Usage: crouter-sdk env --app <client id> [--out <path>]';
+import { usageOf } from './cli-usage.js';
+export const ENV_USAGE = usageOf('env');
+/** The directory every Northlight app signs in against, and the origin `init` registers for local development. */
+export const DEFAULT_ISSUER = 'https://account.northlight.ai';
+export const DEFAULT_ORIGIN = 'http://localhost:3000';
 const DEFAULT_KEY_FILE = 'local/app-key.json';
 /** The variables `env` owns, in the order it writes them. `CROUTER_KEY_FILE` is never one. */
 const NAMES = ['CROUTER_ISSUER', 'CROUTER_CLIENT_ID', 'APP_ORIGIN'];
+const FLAGS = { '--out': 'path', '--app': 'app', '--client-id': 'clientId', '--origin': 'origin', '--issuer': 'issuer' };
 function parseArgs(args) {
     if (args[0] !== 'env')
         throw new Error(ENV_USAGE);
-    let path = 'local/app.env';
-    let app;
+    const parsed = { path: 'local/app.env' };
     const seen = new Set();
     for (let i = 1; i < args.length; i++) {
         const flag = args[i];
         const value = args[++i];
-        if (seen.has(flag) || (flag !== '--out' && flag !== '--app') || !value || value.startsWith('--'))
+        const key = FLAGS[flag];
+        if (seen.has(flag) || !key || !value || value.startsWith('--'))
             throw new Error(ENV_USAGE);
         seen.add(flag);
-        if (flag === '--out')
-            path = value;
-        else
-            app = value;
+        parsed[key] = value;
     }
-    if (!app)
+    // Exactly one source for the client id; --origin and --issuer only mean something when env writes them itself.
+    if (!parsed.app === !parsed.clientId)
         throw new Error(ENV_USAGE);
-    return { path, app };
+    if (parsed.app && (parsed.origin || parsed.issuer))
+        throw new Error(ENV_USAGE);
+    return parsed;
 }
 /** One `NAME=value` assignment line, with an optional `export ` prefix. */
 const ASSIGNMENT = /^(\s*(?:export\s+)?)([A-Za-z_][A-Za-z0-9_]*)(\s*=)(.*)$/;
@@ -64,16 +69,18 @@ export function updateEnvText(text, values) {
             out.push(`${name}=${formatValue(values[name])}`);
     return `${out.join('\n')}\n`;
 }
-/** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
-export function keyFileOf(text) {
+/** The last non-empty value the file assigns to `name`, or undefined. */
+export function envValueOf(text, name) {
     let found;
     for (const line of text.split('\n')) {
         const match = ASSIGNMENT.exec(line);
-        if (match?.[2] === 'CROUTER_KEY_FILE')
+        if (match?.[2] === name)
             found = readValue(match[4] ?? '');
     }
     return found || undefined;
 }
+/** The last `CROUTER_KEY_FILE` the file assigns, or undefined. */
+export const keyFileOf = (text) => envValueOf(text, 'CROUTER_KEY_FILE');
 function envOf(answer) {
     const env = answer?.env;
     if (!env || typeof env !== 'object')
@@ -88,9 +95,45 @@ function envOf(answer) {
     return values;
 }
 const byHand = (path) => `Set ${NAMES.join(', ')} in ${path} by hand: \`crtr cloud apps get --app-id <client id>\` shows them under env.`;
+async function writeEnv(path, existing, values) {
+    const next = updateEnvText(existing ?? '', values);
+    if (existing === undefined) {
+        await mkdir(dirname(path), { recursive: true });
+        const file = await open(path, 'wx', 0o600);
+        try {
+            await file.writeFile(next);
+        }
+        finally {
+            await file.close();
+        }
+    }
+    else if (next !== existing) {
+        await writeFile(path, next);
+    }
+    say([
+        `Set in ${path}:`,
+        ...NAMES.map((name) => `  ${name}=${values[name]}`),
+        `Key file: ${keyFileOf(next) ?? DEFAULT_KEY_FILE} (set CROUTER_KEY_FILE to change it).`,
+    ]);
+    return 0;
+}
 /** The `crouter-sdk env` command. Returns the process exit code. */
 export async function runEnv(argv, options = {}) {
-    const { path, app } = parseArgs(argv);
+    const { path, app, clientId, origin, issuer } = parseArgs(argv);
+    const existing = await readFile(path, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (clientId) {
+        // No crtr and no network: the issuer is fixed, the client id is what the console showed, and the origin is
+        // what the developer registered, which is already in the file when `init` wrote it.
+        return writeEnv(path, existing, {
+            CROUTER_ISSUER: issuer ?? DEFAULT_ISSUER,
+            CROUTER_CLIENT_ID: clientId,
+            APP_ORIGIN: origin ?? envValueOf(existing ?? '', 'APP_ORIGIN') ?? DEFAULT_ORIGIN,
+        });
+    }
     const outcome = await runCrtr(['cloud', 'apps', 'get', '--app-id', app, '--json'], options.crtrTimeoutMs ?? CRTR_TIMEOUT_MS);
     if (outcome.kind === 'missing') {
         say(["Couldn't find crtr, so nothing was written.", byHand(path)]);
@@ -110,29 +153,5 @@ export async function runEnv(argv, options = {}) {
         say([`crtr answered without the app's env: ${last ?? '(no output)'}`, 'Nothing was written.']);
         return 2;
     }
-    const existing = await readFile(path, 'utf8').catch((error) => {
-        if (error.code === 'ENOENT')
-            return undefined;
-        throw error;
-    });
-    const next = updateEnvText(existing ?? '', values);
-    if (existing === undefined) {
-        await mkdir(dirname(path), { recursive: true });
-        const file = await open(path, 'wx', 0o600);
-        try {
-            await file.writeFile(next);
-        }
-        finally {
-            await file.close();
-        }
-    }
-    else if (next !== existing) {
-        await writeFile(path, next);
-    }
-    say([
-        `Set in ${path}:`,
-        ...NAMES.map((name) => `  ${name}=${values[name]}`),
-        `Key file: ${keyFileOf(next) ?? DEFAULT_KEY_FILE} (set CROUTER_KEY_FILE to change it).`,
-    ]);
-    return 0;
+    return writeEnv(path, existing, values);
 }

package/dist/init-command.d.ts

@@ -0,0 +1,5 @@
+/** The `crouter-sdk init` command. Returns the process exit code. */
+export declare function runInit(argv: string[], options?: {
+    cwd?: string;
+    home?: string;
+}): Promise<number>;

package/dist/init-command.js

@@ -0,0 +1,159 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, open, readFile, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { assetPath } from './assets.js';
+import { usageOf } from './cli-usage.js';
+import { say } from './crtr.js';
+import { DEFAULT_ISSUER, DEFAULT_ORIGIN } from './env-command.js';
+import { createKeyFile } from './keygen-command.js';
+import { isAgent, packagedSkill, skillTargets, writeSkillFile } from './skill-command.js';
+import { SDK_VERSION } from './version.js';
+const CONSOLE_URL = 'https://account.northlight.ai/console/new';
+const KEY_FILE = 'local/app-key.json';
+const ENV_FILE = 'local/app.env';
+const START = 'node --env-file=local/app.env --import tsx server.ts';
+function parseArgs(args) {
+    if (args[0] !== 'init')
+        throw new Error(usageOf('init'));
+    const parsed = { dir: '.', agent: 'all', globalSkill: false };
+    const seen = new Set();
+    let haveDir = false;
+    for (let i = 1; i < args.length; i++) {
+        const arg = args[i];
+        if (!arg.startsWith('--')) {
+            if (haveDir)
+                throw new Error(usageOf('init'));
+            haveDir = true;
+            parsed.dir = arg;
+            continue;
+        }
+        if (seen.has(arg))
+            throw new Error(usageOf('init'));
+        seen.add(arg);
+        if (arg === '--global-skill')
+            parsed.globalSkill = true;
+        else if (arg === '--agent') {
+            const value = args[++i];
+            if (!isAgent(value))
+                throw new Error(usageOf('init'));
+            parsed.agent = value;
+        }
+        else
+            throw new Error(usageOf('init'));
+    }
+    return parsed;
+}
+const packageJson = () => `${JSON.stringify({
+    name: 'my-northlight-app',
+    private: true,
+    type: 'module',
+    scripts: { start: START },
+    dependencies: { '@north-light/sdk': SDK_VERSION, tsx: '^4.20.0' },
+}, null, 2)}\n`;
+const ENV_TEXT = `CROUTER_ISSUER=${DEFAULT_ISSUER}\nAPP_ORIGIN=${DEFAULT_ORIGIN}\nCROUTER_CLIENT_ID=\nCROUTER_KEY_FILE=${KEY_FILE}\n`;
+const exists = (path) => stat(path).then(() => true, () => false);
+/** Writes `text` to a file that must not exist yet. */
+async function createFile(path, text, mode = 0o644) {
+    await mkdir(dirname(path), { recursive: true });
+    const file = await open(path, 'wx', mode);
+    try {
+        await file.writeFile(text);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Runs `npm i --save-exact @north-light/sdk@<this version>` in `cwd` (no shell). */
+function installSdk(cwd) {
+    const result = spawnSync('npm', ['i', '--save-exact', `@north-light/sdk@${SDK_VERSION}`], { cwd, stdio: ['ignore', 2, 2] });
+    if (result.error) {
+        say([`Couldn't run npm: ${result.error.message}`]);
+        return 1;
+    }
+    return result.status ?? 1;
+}
+/** The `crouter-sdk init` command. Returns the process exit code. */
+export async function runInit(argv, options = {}) {
+    const { dir: given, agent, globalSkill } = parseArgs(argv);
+    const root = join(options.cwd ?? process.cwd(), given);
+    const shown = (path) => relative(options.cwd ?? process.cwd(), path) || '.';
+    const existingProject = existsSync(join(root, 'package.json'));
+    const skillBase = globalSkill ? options.home ?? homedir() : root;
+    const skillPaths = skillTargets(skillBase, agent);
+    const keyPath = join(root, KEY_FILE);
+    // Decide every refusal before writing anything, so a refused init leaves the directory as it found it.
+    const scaffold = {
+        'package.json': packageJson(),
+        'server.ts': await readFile(assetPath('templates/server.ts'), 'utf8'),
+        '.gitignore': 'local/\nnode_modules/\n',
+        [ENV_FILE]: ENV_TEXT,
+    };
+    const refused = [];
+    if (!existingProject) {
+        for (const name of Object.keys(scaffold))
+            if (await exists(join(root, name)))
+                refused.push(join(root, name));
+        if (await exists(keyPath))
+            refused.push(keyPath);
+    }
+    // A project skill is never replaced by init; `skill` replaces it. The global one is the user's own and init refreshes it.
+    if (!globalSkill)
+        for (const path of skillPaths)
+            if (await exists(path))
+                refused.push(path);
+    if (refused.length > 0) {
+        say([
+            ...refused.map((path) => `Refusing to overwrite ${shown(path)}.`),
+            'Nothing was written.',
+            ...(refused.some((path) => path.endsWith('SKILL.md')) ? ['To replace the skill with the one this package ships, run `npx @north-light/sdk skill`.'] : []),
+        ]);
+        return 1;
+    }
+    const skill = await packagedSkill();
+    if (existingProject) {
+        // An existing project keeps its own code: only the SDK, a key and the skill are added.
+        const status = installSdk(root);
+        if (status !== 0) {
+            say([`\`npm i --save-exact @north-light/sdk@${SDK_VERSION}\` failed (exit ${status}), so nothing else was written.`]);
+            return status;
+        }
+    }
+    else {
+        await mkdir(root, { recursive: true });
+        for (const [name, text] of Object.entries(scaffold))
+            await createFile(join(root, name), text, name === ENV_FILE ? 0o600 : 0o644);
+    }
+    let publicJwk;
+    if (!(await exists(keyPath)))
+        publicJwk = JSON.stringify((await createKeyFile(keyPath)).publicJwk);
+    for (const path of skillPaths)
+        await writeSkillFile(path, skill);
+    const cd = given === '.' ? [] : [`cd ${given}`];
+    say([
+        existingProject ? `Added @north-light/sdk@${SDK_VERSION}, a signing key and the \`northlight\` skill to ${shown(root)}.` : `Created a Northlight app in ${shown(root)}:`,
+        ...(existingProject ? [] : ['  package.json  server.ts  .gitignore  local/app.env', '']),
+        `Private key: ${shown(keyPath)} (mode 0600, kept out of git). Never paste or commit it.`,
+        'Skill:',
+        ...skillPaths.map((path) => `  ${globalSkill ? path : shown(path)}`),
+        '',
+        'Next, in this order:',
+        "  1. Sign in at https://account.northlight.ai/signup if you don't have an account.",
+        `  2. Register the app at ${CONSOLE_URL} with these values:`,
+        `       Origin URL:    ${DEFAULT_ORIGIN}`,
+        `       Redirect URI:  ${DEFAULT_ORIGIN}/auth/callback`,
+        ...(publicJwk ? ['       Public key:    the JWK printed on stdout'] : [`       Public key:    the public half of ${KEY_FILE}`]),
+        '     Then open the app\'s "What it asks for" tab, choose Add permissions, and add sms:send.',
+        '  3. Write the client ID the console shows into the env file:',
+        '       npx @north-light/sdk env --client-id <client id>',
+        '  4. Start it:',
+        ...cd.map((line) => `       ${line}`),
+        ...(existingProject ? [] : ['       npm i']),
+        `       ${START}`,
+        `     then open ${DEFAULT_ORIGIN}/auth/login`,
+    ]);
+    if (publicJwk)
+        console.log(publicJwk);
+    return 0;
+}

package/dist/keygen-cli.js

@@ -1,11 +1,28 @@
 #!/usr/bin/env node
-// The `crouter-sdk` bin: `keygen` and `env`. The file keeps its first command's name because the
-// published bin path (`dist/keygen-cli.js`) is part of the package.
+// The `crouter-sdk` bin: `init`, `skill`, `keygen` and `env`. The file keeps its first command's name because the
+// published bin path (`dist/keygen-cli.js`) is part of the package, and the package keeps exactly one bin so that
+// `npx @north-light/sdk <command>` works without naming it.
+import { overviewUsage } from './cli-usage.js';
 import { runEnv } from './env-command.js';
+import { runInit } from './init-command.js';
 import { runKeygen } from './keygen-command.js';
+import { runSkill } from './skill-command.js';
 const args = process.argv.slice(2);
-const run = args[0] === 'env' ? runEnv(args) : runKeygen(args);
-run.then((code) => { process.exitCode = code; }, (error) => {
+const commands = { init: runInit, skill: runSkill, keygen: runKeygen, env: runEnv };
+const command = args[0] ?? '';
+async function main() {
+    if (command === '--help' || command === '-h' || command === 'help') {
+        console.log(overviewUsage());
+        return 0;
+    }
+    const run = Object.hasOwn(commands, command) ? commands[command] : undefined;
+    if (!run) {
+        console.error(overviewUsage());
+        return 1;
+    }
+    return run(args);
+}
+main().then((code) => { process.exitCode = code; }, (error) => {
     console.error(error instanceof Error ? error.message : String(error));
     process.exitCode = 1;
 });

package/dist/keygen-command.d.ts

@@ -1,6 +1,15 @@
+import { generateKeyPair } from './oauth/keygen.js';
 export interface KeygenOptions {
     /** How long `crtr cloud apps keys add` may run before keygen gives up. */
     crtrTimeoutMs?: number;
 }
+/**
+ * Reserves `path` (mode 0600, never truncating an existing file), writes a fresh private JWK into it and returns the
+ * public JWK and key id. Throws, naming the path, when the file already exists.
+ */
+export declare function createKeyFile(path: string): Promise<{
+    publicJwk: Awaited<ReturnType<typeof generateKeyPair>>['publicJwk'];
+    kid: string;
+}>;
 /** The `crouter-sdk keygen` command. Returns the process exit code. */
 export declare function runKeygen(argv: string[], options?: KeygenOptions): Promise<number>;

package/dist/keygen-command.js

@@ -2,8 +2,9 @@ import { mkdir, open, unlink } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
 import { CRTR_TIMEOUT_MS, notJoinedLines, parseJson, runCrtr, say } from './crtr.js';
+import { usageOf } from './cli-usage.js';
 import { generateKeyPair } from './oauth/keygen.js';
-const USAGE = 'Usage: crouter-sdk keygen [--out <path>] [--app <client id>] [--yes]';
+const USAGE = usageOf('keygen');
 function parseArgs(args) {
     if (args[0] !== 'keygen')
         throw new Error(USAGE);
@@ -71,9 +72,11 @@ async function addKey(app, publicJwk, timeoutMs) {
 /** Removes a key file keygen wrote for a key that no app holds, so a rerun is not refused over it. */
 const discardKey = (path) => unlink(path).catch(() => undefined);
 const discarded = (path) => `Removed ${path}, and the public key printed above is not on any app, so don't add it. Fix the above and run keygen again.`;
-/** The `crouter-sdk keygen` command. Returns the process exit code. */
-export async function runKeygen(argv, options = {}) {
-    const { path, app, yes } = parseArgs(argv);
+/**
+ * Reserves `path` (mode 0600, never truncating an existing file), writes a fresh private JWK into it and returns the
+ * public JWK and key id. Throws, naming the path, when the file already exists.
+ */
+export async function createKeyFile(path) {
     await mkdir(dirname(path), { recursive: true });
     // Reserve the destination before generating or printing the public key; never truncate an existing key.
     const file = await open(path, 'wx', 0o600).catch((error) => {
@@ -81,19 +84,22 @@ export async function runKeygen(argv, options = {}) {
             throw new Error(`${path} already exists. Delete it or pass --out to write somewhere else.`);
         throw error;
     });
-    let publicJwk;
-    let kid;
     try {
         const pair = await generateKeyPair();
         await file.writeFile(`${JSON.stringify(pair.privateJwk)}\n`);
-        ({ publicJwk, kid } = pair);
+        await file.close();
+        return { publicJwk: pair.publicJwk, kid: pair.kid };
     }
     catch (error) {
-        await file.close();
+        await file.close().catch(() => undefined);
         await unlink(path);
         throw error;
     }
-    await file.close();
+}
+/** The `crouter-sdk keygen` command. Returns the process exit code. */
+export async function runKeygen(argv, options = {}) {
+    const { path, app, yes } = parseArgs(argv);
+    const { publicJwk, kid } = await createKeyFile(path);
     const publicLine = JSON.stringify(publicJwk);
     console.error(`Saved the private key to ${path} (key id ${kid}). Keep it out of git.`);
     console.log(publicLine);

package/dist/skill/northlight/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: northlight
+description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
+metadata:
+  sdk-version: "0.3.472"
+---
+
+# Building a Northlight app
+
+An app on Northlight signs people in with their Northlight account, then starts agent runs and calls providers (sms, search, integrations, context, device) on that person's own Northlight-hosted runtime, using their AI subscription. You write and host the app server with `@north-light/sdk`. Northlight hosts the directory (accounts, app registration, consent, the marketplace) and each person's runtime. It does not host your app's code. See [Where your app runs](https://sdk.docs.northlight.ai/docs/how-it-fits.md).
+
+## First: check this skill matches the SDK
+
+This skill is for SDK version `0.3.472`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. That command needs no account and no crtr. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+
+## Where things run
+
+- **Your server** runs wherever you choose (your laptop while developing). It holds the app's private signing key and each person's stored connection.
+- **account.northlight.ai** is the directory. People sign up and consent there. You register the app in its web console, `https://account.northlight.ai/console`.
+- **The person's runtime** runs their agents. Your server reaches it with `oauth.client(userId)` and calls `runs.*` and `providers.*` on it.
+
+An app signs requests with a key pair, not a client secret. The private key stays in `local/app-key.json`; the console holds only the public key.
+
+## The journey
+
+You do the command-line steps. The person does the console steps in a browser: ask them, name the exact field labels, and wait for the values you need back (the client ID).
+
+1. **Account (person).** They sign up at `https://account.northlight.ai/signup`. Signup texts a code over iMessage, so the phone must have iMessage.
+2. **Scaffold (you).** In a new folder run `npx @north-light/sdk@latest init my-app`. In an existing Node project run `npx @north-light/sdk init` instead: it adds the SDK pinned to an exact version, a key and this skill, and overwrites nothing. It prints the public JWK on stdout. `local/app.env` gets the issuer, the origin `http://localhost:3000`, and an empty `CROUTER_CLIENT_ID=`.
+3. **Register (person).** At `https://account.northlight.ai/console/new`, under **Register an app**, they fill in:
+   - **Name**, shown on the consent page.
+   - **Origin URL**: `http://localhost:3000` for development.
+   - **Logo URL**: a square image.
+   - **Why your app needs access**: one sentence, quoted to people on the consent page.
+   - **Redirect URIs**: `http://localhost:3000/auth/callback`. Sign-in returns only to a URI listed here, matched exactly, so `localhost` and `127.0.0.1` differ and the port counts.
+   - **Public key**: the JWK that `init` printed. Never ask for, accept or paste the private key.
+
+   The console then shows the **client ID**. Ask for it.
+4. **Say what the app asks for (person).** On the app's **What it asks for** tab, **Add permissions**, then add every provider scope the code requests (the quickstart needs `sms:send`). A new app starts with `crtr:llm` and `crtr:act`. Without a scope listed here the consent page does not offer it and the provider call is refused ([Scopes and grants](https://sdk.docs.northlight.ai/docs/concepts/scopes-and-grants.md)).
+5. **Write the env file (you).** `npx @north-light/sdk env --client-id <client id>`. It sets `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` in `local/app.env` and keeps every other line.
+6. **Run it (you).** `npm i`, then `node --env-file=local/app.env --import tsx server.ts`. Ask the person to open `http://localhost:3000/auth/login`, sign in, and choose Allow. The page then starts a run and sends them a text.
+7. **Testing mode.** A new app is in testing: only its owner and up to 100 testers can sign in. Testers are added by email or phone on the console's **Testers** tab. Anyone else's callback gets `error=access_denied` with `error_description=app_in_testing` ([Testing mode](https://sdk.docs.northlight.ai/docs/concepts/testing-mode.md)). Going public needs verification: email support@northlight.ai.
+
+Check each step worked before the next: a `local/app-key.json` file exists, a client ID is in `local/app.env`, the server prints `Listening on http://localhost:3000`, `/auth/login` reaches the Northlight consent page, and the callback lands back on your server. If a step fails, read the error and the page it names before changing code.
+
+## Code patterns
+
+These come from the `server.ts` that `init` writes. The SDK reads no environment: your code passes the values in.
+
+### Configure `OAuth2Client`
+
+```ts
+const store = new MemoryConnectionStore(); // one process only; use a persistent ConnectionStore in production
+const oauth = new OAuth2Client({
+  clientId: process.env.CROUTER_CLIENT_ID ?? '',
+  issuer: process.env.CROUTER_ISSUER ?? 'https://account.northlight.ai',
+  redirectUri: `${origin}/auth/callback`,
+  privateKey: JSON.parse(await readFile(process.env.CROUTER_KEY_FILE ?? 'local/app-key.json', 'utf8')),
+  store,
+});
+```
+
+### Sign in: `/auth/login` and `/auth/callback`
+
+```ts
+if (url.pathname === '/auth/login') {
+  const {url: authorizeUrl, codeVerifier, state, nonce} = await oauth.authorizeUrl({
+    scopes: ['openid', 'profile', 'crtr:llm', 'crtr:act', 'sms:send'],
+    state: randomBytes(16).toString('base64url'),
+  });
+  pending.set(state, {codeVerifier, nonce});
+  return void res.writeHead(303, {location: authorizeUrl}).end();
+}
+
+if (url.pathname === '/auth/callback') {
+  if (authorizationRefusalOf(url)?.code === 'app_in_testing') {
+    return page(res, 403, '<h1>This app is still in testing</h1><p>Ask its owner to add you on the Testers tab in the console.</p>');
+  }
+  const state = url.searchParams.get('state') ?? '';
+  const code = url.searchParams.get('code');
+  const saved = pending.get(state);
+  if (!saved || !code) return page(res, 400, '<p>Start sign-in again at <a href="/auth/login">/auth/login</a>.</p>');
+  pending.delete(state);
+  const connection = await oauth.exchangeCode({code, codeVerifier: saved.codeVerifier, state, expectedState: state, nonce: saved.nonce});
+  await store.save(connection);
+  const sid = randomBytes(16).toString('base64url');
+  sessions.set(sid, connection.userId);
+  return void res.writeHead(303, {location: '/', 'set-cookie': `sid=${sid}; HttpOnly; SameSite=Lax; Path=/`}).end();
+}
+```
+
+Keep `codeVerifier` and `nonce` per sign-in, keyed by `state`, and pass the same `state` as `expectedState` when exchanging the code. The example keeps them in a `Map` and sessions in memory; use real sessions in production ([Connections](https://sdk.docs.northlight.ai/docs/concepts/connections.md), [Go live](https://sdk.docs.northlight.ai/docs/guides/go-live.md)).
+
+### Start a run and call a provider
+
+```ts
+const runtime = await oauth.client(userId); // a client on this person's runtime, from their stored connection
+const started = await runtime.runs.start({prompt: 'Reply with exactly the word: pong', scopes: ['crtr:llm', 'crtr:act']});
+const run = await runtime.runs.wait(started.run_id); // status is 'idle' once the reply is done
+
+// Texts the signed-in person's own verified phone through the sms provider (50 per person per UTC day).
+const sent = await runtime.providers.call({provider: 'sms', tool: 'send', arguments: {body: 'Hello from my first Northlight app.'}});
+```
+
+### Get a typed result back with `runs.parse`
+
+```ts
+import {z} from 'zod';
+import type {ConnectedCrouter} from '@north-light/sdk';
+
+const Profile = z.object({
+  display_name: z.string(),
+  bio: z.string(),
+  facts: z.array(z.string()),
+});
+
+/** Start a run on the person's runtime and get a value back that was checked against the schema. */
+export async function draftProfile(runtime: ConnectedCrouter) {
+  const outcome = await runtime.runs.parse({
+    prompt: 'Draft a public profile for me from my notes.',
+    scopes: ['crtr:llm'], // submitting a result needs no other scope
+    output_schema: Profile,
+  });
+
+  if (outcome.kind === 'result') return outcome.output_parsed; // {display_name, bio, facts}, typed from Profile
+  if (outcome.reason === 'declined') {
+    // The agent could not honestly satisfy the schema; outcome.details says why.
+    throw new Error(`Declined: ${outcome.details?.reason ?? 'no reason given'}`);
+  }
+  throw new Error(`The run ended without a result: ${outcome.reason}`); // canceled, deadline_exceeded or runtime_error
+}
+```
+
+### List a provider's tools, then call one
+
+```ts
+import type {ConnectedCrouter} from '@north-light/sdk';
+
+/** List the tools a provider offers this person, then call one. Scope strings come from the console's
+ *  "Add permissions" list; tool names and arguments come from `providers.tools`. Never invent either. */
+export async function textMe(runtime: ConnectedCrouter, body: string) {
+  const sms = await runtime.providers.tools('sms');
+  console.log(JSON.stringify(sms.groups, null, 2)); // each leaf: tool, description, params
+
+  return runtime.providers.call({provider: 'sms', tool: 'send', arguments: {body}});
+}
+```
+
+## Rules
+
+Details behind each rule: [Errors](https://sdk.docs.northlight.ai/docs/errors.md), [Typed results](https://sdk.docs.northlight.ai/docs/guides/typed-results.md), [Connections](https://sdk.docs.northlight.ai/docs/concepts/connections.md).
+
+- **Pin the exact SDK version** (`npm i --save-exact`). A later release can change a type or method, and `^` picks it up on the next `npm i`.
+- **Take scope strings from the console's Add permissions list or from `providers.tools`.** Never invent one. Tool names and arguments also come from `providers.tools('<provider>')`.
+- **Never print, paste, log or commit `local/app-key.json`.** `local/` is in `.gitignore`. If it leaks, add a new key in the console, switch to it, and retire the old one.
+- **Use `oauth.client(userId)` for a person's runtime. Never `new Crouter()`.** `Crouter` is the client for a runtime you run yourself, not for apps.
+- **Use a persistent `ConnectionStore` in production.** `MemoryConnectionStore` loses every sign-in on restart and does not work across processes. `@north-light/sdk/stores/postgres` is the production store.
+- **Use `runs.parse` with a schema for data. Never parse `runs.trace`.** The trace is what the model said; `output_parsed` is a value checked against your schema.
+- **`426 runtime_version_unsupported` means the SDK is newer than production.** Install the previous version (`npm view @north-light/sdk versions`) with `--save-exact`.
+- **Handle a refused connection in one place** with the `onRefusal` option of `OAuth2Client`; `grant_removed` is the only code on which you may delete a person's data.
+- **Do not claim the app is hosted by Northlight.** The server runs where the developer puts it.
+
+## The CLI
+
+`npx @north-light/sdk <command>`. None needs crtr unless noted.
+
+| Command | Effect | Needs crtr |
+|---|---|---|
+| `init [dir] [--agent claude|agents|all] [--global-skill]` | Scaffold a Northlight app in an empty or new directory (server.ts, key, env file, skill), or add the SDK, a key and the skill to an existing project. Never overwrites a file. | No |
+| `skill [--agent claude|agents|all] [--global] [--print]` | Write the packaged `northlight` skill into `.agents/skills` and `.claude/skills` (or `~/` with `--global`), replacing an older copy. `--print` writes it to stdout. | No |
+| `keygen [--out <path>] [--app <client id>] [--yes]` | Write a private signing key to `local/app-key.json` (mode 0600) and print the public JWK to register. | Only with `--app` |
+| `env --client-id <client id> [--origin <url>] [--issuer <url>] [--out <path>]`<br>`env --app <client id> [--out <path>]` | Write `CROUTER_ISSUER`, `CROUTER_CLIENT_ID` and `APP_ORIGIN` into `local/app.env`, keeping every other line. `--client-id` makes no network call; `--app` reads them through crtr. | Only with `--app` |
+
+## Pages
+
+Read a page as markdown by adding `.md` to its URL. The whole site as one file: https://sdk.docs.northlight.ai/llms-full.txt.
+
+- [Quick setup](https://sdk.docs.northlight.ai/docs/quickstart.md)
+- [Use your coding agent](https://sdk.docs.northlight.ai/docs/coding-agents.md)
+- [Where your app runs](https://sdk.docs.northlight.ai/docs/how-it-fits.md)
+- [Apps and sign-in](https://sdk.docs.northlight.ai/docs/concepts/apps-and-sign-in.md)
+- [Scopes and grants](https://sdk.docs.northlight.ai/docs/concepts/scopes-and-grants.md)
+- [Connections](https://sdk.docs.northlight.ai/docs/concepts/connections.md)
+- [Runs](https://sdk.docs.northlight.ai/docs/concepts/runs.md)
+- [Testing mode](https://sdk.docs.northlight.ai/docs/concepts/testing-mode.md)
+- [Providers](https://sdk.docs.northlight.ai/docs/concepts/providers.md)
+- [Typed results](https://sdk.docs.northlight.ai/docs/guides/typed-results.md)
+- [Stream a run](https://sdk.docs.northlight.ai/docs/guides/stream-a-run.md)
+- [Background runs](https://sdk.docs.northlight.ai/docs/guides/background-runs.md)
+- [Many users](https://sdk.docs.northlight.ai/docs/guides/many-users.md)
+- [Grant changes](https://sdk.docs.northlight.ai/docs/guides/grant-changes.md)
+- [Files and documents](https://sdk.docs.northlight.ai/docs/guides/files-and-documents.md)
+- [Test your app](https://sdk.docs.northlight.ai/docs/guides/test-your-app.md)
+- [Manage your app](https://sdk.docs.northlight.ai/docs/guides/manage-your-app.md)
+- [Go live](https://sdk.docs.northlight.ai/docs/guides/go-live.md)
+- [Providers index](https://sdk.docs.northlight.ai/docs/providers.md)
+- [Texting (sms)](https://sdk.docs.northlight.ai/docs/providers/sms.md)
+- [Errors](https://sdk.docs.northlight.ai/docs/errors.md)
+- [CLI reference](https://sdk.docs.northlight.ai/docs/cli.md)
+- [Release notes](https://sdk.docs.northlight.ai/docs/release-notes.md)

package/dist/skill-command.d.ts

@@ -0,0 +1,14 @@
+export declare const SKILL_NAME = "northlight";
+export type SkillAgent = 'claude' | 'agents' | 'all';
+/** The `SKILL.md` paths for `agent` under `base` (the project directory, or the home directory for a global install). */
+export declare function skillTargets(base: string, agent: SkillAgent): string[];
+/** The skill this package ships, generated by `scripts/build-skill.mjs`. */
+export declare const packagedSkill: () => Promise<string>;
+/** Writes `text` to `path` through a temporary file, so an agent reading the skill never sees half of it. */
+export declare function writeSkillFile(path: string, text: string): Promise<void>;
+export declare const isAgent: (value: string | undefined) => value is SkillAgent;
+/** The `crouter-sdk skill` command. Returns the process exit code. */
+export declare function runSkill(argv: string[], options?: {
+    cwd?: string;
+    home?: string;
+}): Promise<number>;

package/dist/skill-command.js

@@ -0,0 +1,65 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { say } from './crtr.js';
+import { usageOf } from './cli-usage.js';
+import { assetPath } from './assets.js';
+export const SKILL_NAME = 'northlight';
+/** Where each agent family reads project skills: Codex, Cursor, Copilot and VS Code read `.agents/skills`; Claude Code reads `.claude/skills`. */
+const SKILL_ROOTS = { agents: '.agents/skills', claude: '.claude/skills' };
+/** The `SKILL.md` paths for `agent` under `base` (the project directory, or the home directory for a global install). */
+export function skillTargets(base, agent) {
+    const agents = agent === 'all' ? ['agents', 'claude'] : [agent];
+    return agents.map((name) => join(base, SKILL_ROOTS[name], SKILL_NAME, 'SKILL.md'));
+}
+/** The skill this package ships, generated by `scripts/build-skill.mjs`. */
+export const packagedSkill = () => readFile(assetPath('skill/northlight/SKILL.md'), 'utf8');
+/** Writes `text` to `path` through a temporary file, so an agent reading the skill never sees half of it. */
+export async function writeSkillFile(path, text) {
+    await mkdir(dirname(path), { recursive: true });
+    const temporary = `${path}.${process.pid}.tmp`;
+    await writeFile(temporary, text);
+    await rename(temporary, path);
+}
+export const isAgent = (value) => value === 'claude' || value === 'agents' || value === 'all';
+function parseArgs(args) {
+    if (args[0] !== 'skill')
+        throw new Error(usageOf('skill'));
+    const parsed = { agent: 'all', global: false, print: false };
+    const seen = new Set();
+    for (let i = 1; i < args.length; i++) {
+        const flag = args[i];
+        if (seen.has(flag))
+            throw new Error(usageOf('skill'));
+        seen.add(flag);
+        if (flag === '--global')
+            parsed.global = true;
+        else if (flag === '--print')
+            parsed.print = true;
+        else if (flag === '--agent') {
+            const value = args[++i];
+            if (!isAgent(value))
+                throw new Error(usageOf('skill'));
+            parsed.agent = value;
+        }
+        else
+            throw new Error(usageOf('skill'));
+    }
+    if (parsed.print && (parsed.global || seen.has('--agent')))
+        throw new Error(usageOf('skill'));
+    return parsed;
+}
+/** The `crouter-sdk skill` command. Returns the process exit code. */
+export async function runSkill(argv, options = {}) {
+    const { agent, global, print } = parseArgs(argv);
+    const skill = await packagedSkill();
+    if (print) {
+        process.stdout.write(skill);
+        return 0;
+    }
+    const targets = skillTargets(global ? options.home ?? homedir() : options.cwd ?? process.cwd(), agent);
+    for (const target of targets)
+        await writeSkillFile(target, skill);
+    say(['Wrote the `northlight` skill (replacing any older copy):', ...targets.map((target) => `  ${target}`)]);
+    return 0;
+}

package/dist/templates/server.ts

@@ -0,0 +1,81 @@
+// The server `npx @north-light/sdk init` writes as server.ts: sign a person in with Northlight, then start a run on
+// their runtime and send them a text. It keeps sign-in state in memory, so it is a sketch for one process, not production.
+import {createServer, type IncomingMessage, type ServerResponse} from 'node:http';
+import {randomBytes} from 'node:crypto';
+import {readFile} from 'node:fs/promises';
+import {MemoryConnectionStore, OAuth2Client, authorizationRefusalOf} from '@north-light/sdk';
+
+const origin = process.env.APP_ORIGIN ?? 'http://localhost:3000';
+
+const store = new MemoryConnectionStore(); // one process only; use a persistent ConnectionStore in production
+const oauth = new OAuth2Client({
+  clientId: process.env.CROUTER_CLIENT_ID ?? '',
+  issuer: process.env.CROUTER_ISSUER ?? 'https://account.northlight.ai',
+  redirectUri: `${origin}/auth/callback`,
+  privateKey: JSON.parse(await readFile(process.env.CROUTER_KEY_FILE ?? 'local/app-key.json', 'utf8')),
+  store,
+});
+
+const pending = new Map<string, {codeVerifier: string; nonce: string}>(); // sign-ins in flight, keyed by state
+const sessions = new Map<string, string>(); // session id -> userId; use a real session store in production
+
+const escapeHtml = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const page = (res: ServerResponse, status: number, body: string) => {
+  res.writeHead(status, {'content-type': 'text/html; charset=utf-8'}).end(`<!doctype html><meta charset="utf-8"><title>Northlight app</title><body style="font-family:system-ui;max-width:40rem;margin:3rem auto">${body}`);
+};
+const userOf = (req: IncomingMessage) => {
+  const sid = /(?:^|; )sid=([\w-]+)/.exec(req.headers.cookie ?? '')?.[1];
+  return sid ? sessions.get(sid) : undefined;
+};
+
+const server = createServer(async (req, res) => {
+  const url = new URL(req.url ?? '/', origin);
+  try {
+    if (!process.env.CROUTER_CLIENT_ID) {
+      return page(res, 200, '<h1>One step left</h1><p>Register the app in the console, then run <code>npx @north-light/sdk env --client-id &lt;client id&gt;</code> and restart this server.</p>');
+    }
+
+    if (url.pathname === '/auth/login') {
+      const {url: authorizeUrl, codeVerifier, state, nonce} = await oauth.authorizeUrl({
+        scopes: ['openid', 'profile', 'crtr:llm', 'crtr:act', 'sms:send'],
+        state: randomBytes(16).toString('base64url'),
+      });
+      pending.set(state, {codeVerifier, nonce});
+      return void res.writeHead(303, {location: authorizeUrl}).end();
+    }
+
+    if (url.pathname === '/auth/callback') {
+      if (authorizationRefusalOf(url)?.code === 'app_in_testing') {
+        return page(res, 403, '<h1>This app is still in testing</h1><p>Ask its owner to add you on the Testers tab in the console.</p>');
+      }
+      const state = url.searchParams.get('state') ?? '';
+      const code = url.searchParams.get('code');
+      const saved = pending.get(state);
+      if (!saved || !code) return page(res, 400, '<p>Start sign-in again at <a href="/auth/login">/auth/login</a>.</p>');
+      pending.delete(state);
+      const connection = await oauth.exchangeCode({code, codeVerifier: saved.codeVerifier, state, expectedState: state, nonce: saved.nonce});
+      await store.save(connection);
+      const sid = randomBytes(16).toString('base64url');
+      sessions.set(sid, connection.userId);
+      return void res.writeHead(303, {location: '/', 'set-cookie': `sid=${sid}; HttpOnly; SameSite=Lax; Path=/`}).end();
+    }
+
+    const userId = userOf(req);
+    if (!userId) return page(res, 200, '<h1>Northlight app</h1><p><a href="/auth/login">Sign in with Northlight</a></p>');
+
+    if (url.pathname === '/run' && req.method === 'POST') {
+      const runtime = await oauth.client(userId); // a client on this person's runtime, from their stored connection
+      const started = await runtime.runs.start({prompt: 'Reply with exactly the word: pong', scopes: ['crtr:llm', 'crtr:act']});
+      const run = await runtime.runs.wait(started.run_id); // status is 'idle' once the reply is done
+      // Texts the signed-in person's own verified phone through the sms provider (50 per person per UTC day).
+      const sent = await runtime.providers.call({provider: 'sms', tool: 'send', arguments: {body: 'Hello from my first Northlight app.'}});
+      return page(res, 200, `<h1>Done</h1><p>The run finished with status <code>${escapeHtml(run.status)}</code>. A text is on its way to your phone.</p><pre>${escapeHtml(JSON.stringify({run: run.run_id, outcome: run.outcome, report: run.last_report, text: sent}, null, 2))}</pre><p><a href="/">Back</a></p>`);
+    }
+    return page(res, 200, `<h1>Signed in</h1><p>You are <code>${escapeHtml(userId)}</code>.</p><form method="post" action="/run"><button>Start a run and send me a text</button></form>`);
+  } catch (error) {
+    console.error(error);
+    return page(res, 500, `<h1>Something failed</h1><pre>${escapeHtml(error instanceof Error ? error.message : String(error))}</pre>`);
+  }
+});
+
+server.listen(Number(new URL(origin).port) || 3000, () => console.log(`Listening on ${origin}`));

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.470";
+export declare const SDK_VERSION = "0.3.472";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.470';
+export const SDK_VERSION = '0.3.472';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.470",
+  "version": "0.3.472",
   "crouterContract": "1.7",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
@@ -37,12 +37,12 @@
   ],
   "sideEffects": false,
   "scripts": {
-    "build": "tsc -p tsconfig.json && chmod 755 dist/keygen-cli.js",
+    "build": "tsc -p tsconfig.json && node scripts/build-skill.mjs && chmod 755 dist/keygen-cli.js",
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.470",
-    "@north-light/identity": "0.3.470",
+    "@north-light/api": "0.3.472",
+    "@north-light/identity": "0.3.472",
     "jose": "^6.2.1"
   },
   "peerDependencies": {