@north-light/sdk 0.3.477 → 0.3.479

package/dist/init-command.js

@@ -1,6 +1,6 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { mkdir, open, readFile, stat } from 'node:fs/promises';
+import { appendFile, 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';
@@ -65,6 +65,25 @@ async function createFile(path, text, mode = 0o644) {
         await file.close();
     }
 }
+/** The `.gitignore` lines that already keep `local/` (the key and env file) out of git. */
+const IGNORES_LOCAL = new Set(['local', 'local/', '/local', '/local/', 'local/*', '/local/*', 'local/**', '/local/**']);
+/** Makes sure `<root>/.gitignore` ignores `local/`: creates it, or appends the entry once. Returns what it did. */
+async function ensureLocalIgnored(root) {
+    const path = join(root, '.gitignore');
+    const current = await readFile(path, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    });
+    if (current === undefined) {
+        await createFile(path, 'local/\n');
+        return 'created';
+    }
+    if (current.split(/\r?\n/).some((line) => IGNORES_LOCAL.has(line.trim())))
+        return 'present';
+    await appendFile(path, `${current === '' || current.endsWith('\n') ? '' : '\n'}local/\n`);
+    return 'added';
+}
 /** 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] });
@@ -125,6 +144,8 @@ export async function runInit(argv, options = {}) {
         for (const [name, text] of Object.entries(scaffold))
             await createFile(join(root, name), text, name === ENV_FILE ? 0o600 : 0o644);
     }
+    // Before the key exists, so a key is never on disk in a directory git would pick up. A new app's scaffold already wrote it.
+    const ignored = existingProject ? await ensureLocalIgnored(root) : 'present';
     let publicJwk;
     if (!(await exists(keyPath)))
         publicJwk = JSON.stringify((await createKeyFile(keyPath)).publicJwk);
@@ -134,7 +155,8 @@ export async function runInit(argv, options = {}) {
     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.`,
+        ...(ignored === 'present' ? [] : [`${ignored === 'created' ? 'Created' : 'Updated'} ${shown(join(root, '.gitignore'))} so git ignores local/.`]),
+        `Private key: ${shown(keyPath)} (mode 0600, ignored by git). Never paste or commit it.`,
         'Skill:',
         ...skillPaths.map((path) => `  ${globalSkill ? path : shown(path)}`),
         '',

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 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.477"
+  sdk-version: "0.3.479"
 ---
 
 # Building a Northlight app
@@ -11,7 +11,7 @@ An app on Northlight signs people in with their Northlight account, then starts
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.477`. 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>`.
+This skill is for SDK version `0.3.479`. 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
 
@@ -36,7 +36,7 @@ You do the command-line steps. The person does the console steps in a browser: a
    - **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)).
+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`: choose Texting, tick it, choose **Done**, then choose **Save**; **Done** alone stores nothing). 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.
@@ -95,7 +95,9 @@ Keep `codeVerifier` and `nonce` per sign-in, keyed by `state`, and pass the same
 
 ```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']});
+// The prompt is the instruction; the message stored with it joins the first turn, so `reply` can follow that turn.
+const started = await runtime.runs.start({prompt: 'Reply with exactly the word: pong', message: 'ping', scopes: ['crtr:llm', 'crtr:act']});
+const reply = await runtime.runs.reply(started.run_id, started.message!).collect(); // reply.text is what the agent said
 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).

package/dist/templates/server.ts

@@ -65,11 +65,14 @@ const server = createServer(async (req, res) => {
 
     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']});
+      // The prompt is the instruction; the message stored with it joins the first turn, so `reply` can follow that turn.
+      const started = await runtime.runs.start({prompt: 'Reply with exactly the word: pong', message: 'ping', scopes: ['crtr:llm', 'crtr:act']});
+      const reply = await runtime.runs.reply(started.run_id, started.message!).collect(); // reply.text is what the agent said
       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>`);
+      const {message_id} = sent as {message_id: string}; // the provider also returns a note meant for agents; it is not shown here
+      return page(res, 200, `<h1>Done</h1><p>The run finished with status <code>${escapeHtml(run.status)}</code> and replied <code>${escapeHtml(reply.text)}</code>. A text is on its way to your phone.</p><pre>${escapeHtml(JSON.stringify({run: run.run_id, status: run.status, reply: reply.text, message_id}, 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) {

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.477";
+export declare const SDK_VERSION = "0.3.479";
 /** 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.477';
+export const SDK_VERSION = '0.3.479';
 // 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.477",
+  "version": "0.3.479",
   "crouterContract": "1.7",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
@@ -35,14 +35,17 @@
     "dist",
     "README.md"
   ],
+  "engines": {
+    "node": ">=20.6.0"
+  },
   "sideEffects": false,
   "scripts": {
     "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.477",
-    "@north-light/identity": "0.3.477",
+    "@north-light/api": "0.3.479",
+    "@north-light/identity": "0.3.479",
     "jose": "^6.2.1"
   },
   "peerDependencies": {