@north-light/cli 0.3.478 → 0.3.479

package/dist/builtin-memory/northlight-apps/coding-agents.md

@@ -39,7 +39,7 @@ npx @north-light/sdk skill
 
 The project copy is the default so it is committed with the project, and teammates get it from git. It matches the SDK version your project pins.
 
-Checked on production: the files `init` writes, that `init` in a directory that already has a `package.json` pins the SDK and writes the key and skill but no app code, and that `skill` rewrites both skill files. `init` in such a directory writes no `.gitignore`, so add `local/` to yours. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
+Checked on production: the files `init` writes, that `init` in a directory that already has a `package.json` pins the SDK and writes the key and skill but no app code, and that `skill` rewrites both skill files. In such a directory `init` creates a `.gitignore` with `local/`, or adds `local/` to the one you have, so the key stays out of git. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
 
 ## Without a project: the hosted skill
 

package/dist/builtin-memory/northlight-apps/concepts/runs.md

@@ -12,11 +12,13 @@ A run is an agent that works on a person's Northlight runtime, on your behalf an
 
 ```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
 ```
 
-`runs.start` returns at once with a `run_id`. `runs.wait(runId)` long-polls until the run is no longer `running`.
+`runs.start` returns at once with a `run_id`. Passing `message` stores a first message with the run, and `runs.reply(runId, started.message)` follows the turn that answers it (`collect()` gives its `text`). `runs.wait(runId)` long-polls until the run is no longer `running`.
 
 ## Status
 
@@ -43,7 +45,7 @@ A `settled` run has an `outcome`:
 | `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 [[northlight-apps/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.
+A run that is only `idle` has no `outcome`. Read what the agent said from `runs.reply(...).collect()`. `last_report` is present only if the agent pushed a report. To get data back, give the run an `output_schema` and read it with `runs.parse`: see [[northlight-apps/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
 

package/dist/builtin-memory/northlight-apps/quickstart.md

@@ -13,7 +13,7 @@ npx @north-light/sdk@latest init my-app
 
 This command creates a small Node server, a signing key and an env file. About ten minutes later you have an app on your laptop that signs you in with Northlight, starts an agent run on your own Northlight runtime, and texts your phone. The app runs on your machine and talks to Northlight's production directory at `https://account.northlight.ai`. There is no local Northlight stack to run, and you do not need crouter.
 
-You need Node.js 22 or later and a phone that can receive iMessage. The quickstart ran on Node 22.14, 22.22 and 26.12; `--env-file` needs Node 20.6 or later.
+You need Node.js 20.6 or later (the start command uses `--env-file`) and a phone that can receive iMessage. The server was run on Node 20.6, 20.20, 22.14, 22.22 and 26.12.
 
 Using a coding agent? Run the same `init` command, or tell your agent: *Read https://sdk.docs.northlight.ai/SKILL.md and follow it.* See [[northlight-apps/coding-agents]].
 
@@ -109,9 +109,9 @@ node --env-file=local/app.env --import tsx server.ts
 
 (`npm start` runs the same command.) You should see `Listening on http://localhost:3000`.
 
-Open `http://localhost:3000/auth/login`. Your browser goes to `account.northlight.ai`. Sign in if asked, read the consent page, and choose Allow. You land back on `http://localhost:3000/` with "Signed in" and your Northlight user id. Press **Start a run and send me a text**. The page answers "Done", shows the run's status `idle` and the JSON of the text request (a `message_id` and a `note` from the sms provider), and your phone receives "Hello from my first Northlight app." from Northlight's number.
+Open `http://localhost:3000/auth/login`. Your browser goes to `account.northlight.ai`. Sign in if asked, read the consent page, and choose Allow. You land back on `http://localhost:3000/` with "Signed in" and your Northlight user id. Press **Start a run and send me a text**. The page answers "Done", shows the run's status `idle`, the run's reply (`pong`) and the text's `message_id`, and your phone receives "Hello from my first Northlight app." from Northlight's number.
 
-Checked on production, as the account that owns the app: the server starts (with `npm start` too), `/` shows the sign-in link, and `/auth/login` answers `303` to `https://account.northlight.ai/authorize?client_id=…&scope=openid+profile+crtr%3Allm+crtr%3Aact+sms%3Asend…&code_challenge_method=S256…`. The consent page listed the four permissions and the monthly cap, **Allow** returned to `http://localhost:3000/` with "Signed in" and the user id, and the button page answered "Done" with status `idle` and a `message_id` for the text. In the console the key then read "Last used just now". Not yet checked on production: that the text reached the phone (the `message_id` is the provider's answer, not a delivery receipt), that the run's reply was `pong`, and the `426` case. Signing in as a second person needs a second account and is not covered here.
+Checked on production, as the account that owns the app: the server starts (with `npm start` too), `/` shows the sign-in link, and `/auth/login` answers `303` to `https://account.northlight.ai/authorize?client_id=…&scope=openid+profile+crtr%3Allm+crtr%3Aact+sms%3Asend…&code_challenge_method=S256…`. The consent page listed the four permissions and the monthly cap, **Allow** returned to `http://localhost:3000/` with "Signed in" and the user id, and the button page answered "Done" with status `idle` and a `message_id` for the text. In the console the key then read "Last used just now". Not yet checked on production: that the text reached the phone (the `message_id` is the provider's answer, not a delivery receipt), and the `426` case. The `pong` reply is read through `runs.reply` and has not been run on production since this example changed. Signing in as a second person needs a second account and is not covered here.
 
 If `/` shows "One step left", `CROUTER_CLIENT_ID` is empty: repeat step 5 and restart. If a call fails with `426 runtime_version_unsupported`, your SDK is newer than the Northlight runtimes. Install the previous version with `npm i --save-exact @north-light/sdk@<version>` and tell support@northlight.ai.
 
@@ -193,11 +193,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/docs/apps/coding-agents.md

@@ -36,7 +36,7 @@ npx @north-light/sdk skill
 
 The project copy is the default so it is committed with the project, and teammates get it from git. It matches the SDK version your project pins.
 
-Checked on production: the files `init` writes, that `init` in a directory that already has a `package.json` pins the SDK and writes the key and skill but no app code, and that `skill` rewrites both skill files. `init` in such a directory writes no `.gitignore`, so add `local/` to yours. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
+Checked on production: the files `init` writes, that `init` in a directory that already has a `package.json` pins the SDK and writes the key and skill but no app code, and that `skill` rewrites both skill files. In such a directory `init` creates a `.gitignore` with `local/`, or adds `local/` to the one you have, so the key stays out of git. Which agent loads which directory is from each agent's documentation and is not yet checked on production for every agent.
 
 ## Without a project: the hosted skill
 

package/docs/apps/concepts/runs.md

@@ -9,7 +9,7 @@ A run is an agent that works on a person's Northlight runtime, on your behalf an
 
 <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`.
+`runs.start` returns at once with a `run_id`. Passing `message` stores a first message with the run, and `runs.reply(runId, started.message)` follows the turn that answers it (`collect()` gives its `text`). `runs.wait(runId)` long-polls until the run is no longer `running`.
 
 ## Status
 
@@ -36,7 +36,7 @@ A `settled` run has an `outcome`:
 | `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.
+A run that is only `idle` has no `outcome`. Read what the agent said from `runs.reply(...).collect()`. `last_report` is present only if the agent pushed a report. 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
 

package/docs/apps/quickstart.md

@@ -11,7 +11,7 @@ npx @north-light/sdk@latest init my-app
 
 This command creates a small Node server, a signing key and an env file. About ten minutes later you have an app on your laptop that signs you in with Northlight, starts an agent run on your own Northlight runtime, and texts your phone. The app runs on your machine and talks to Northlight's production directory at `https://account.northlight.ai`. There is no local Northlight stack to run, and you do not need crouter.
 
-You need Node.js 22 or later and a phone that can receive iMessage. The quickstart ran on Node 22.14, 22.22 and 26.12; `--env-file` needs Node 20.6 or later.
+You need Node.js 20.6 or later (the start command uses `--env-file`) and a phone that can receive iMessage. The server was run on Node 20.6, 20.20, 22.14, 22.22 and 26.12.
 
 Using a coding agent? Run the same `init` command, or tell your agent: *Read https://sdk.docs.northlight.ai/SKILL.md and follow it.* See [Use your coding agent](/docs/coding-agents).
 
@@ -107,9 +107,9 @@ node --env-file=local/app.env --import tsx server.ts
 
 (`npm start` runs the same command.) You should see `Listening on http://localhost:3000`.
 
-Open `http://localhost:3000/auth/login`. Your browser goes to `account.northlight.ai`. Sign in if asked, read the consent page, and choose Allow. You land back on `http://localhost:3000/` with "Signed in" and your Northlight user id. Press **Start a run and send me a text**. The page answers "Done", shows the run's status `idle` and the JSON of the text request (a `message_id` and a `note` from the sms provider), and your phone receives "Hello from my first Northlight app." from Northlight's number.
+Open `http://localhost:3000/auth/login`. Your browser goes to `account.northlight.ai`. Sign in if asked, read the consent page, and choose Allow. You land back on `http://localhost:3000/` with "Signed in" and your Northlight user id. Press **Start a run and send me a text**. The page answers "Done", shows the run's status `idle`, the run's reply (`pong`) and the text's `message_id`, and your phone receives "Hello from my first Northlight app." from Northlight's number.
 
-Checked on production, as the account that owns the app: the server starts (with `npm start` too), `/` shows the sign-in link, and `/auth/login` answers `303` to `https://account.northlight.ai/authorize?client_id=…&scope=openid+profile+crtr%3Allm+crtr%3Aact+sms%3Asend…&code_challenge_method=S256…`. The consent page listed the four permissions and the monthly cap, **Allow** returned to `http://localhost:3000/` with "Signed in" and the user id, and the button page answered "Done" with status `idle` and a `message_id` for the text. In the console the key then read "Last used just now". Not yet checked on production: that the text reached the phone (the `message_id` is the provider's answer, not a delivery receipt), that the run's reply was `pong`, and the `426` case. Signing in as a second person needs a second account and is not covered here.
+Checked on production, as the account that owns the app: the server starts (with `npm start` too), `/` shows the sign-in link, and `/auth/login` answers `303` to `https://account.northlight.ai/authorize?client_id=…&scope=openid+profile+crtr%3Allm+crtr%3Aact+sms%3Asend…&code_challenge_method=S256…`. The consent page listed the four permissions and the monthly cap, **Allow** returned to `http://localhost:3000/` with "Signed in" and the user id, and the button page answered "Done" with status `idle` and a `message_id` for the text. In the console the key then read "Last used just now". Not yet checked on production: that the text reached the phone (the `message_id` is the provider's answer, not a delivery receipt), and the `426` case. The `pong` reply is read through `runs.reply` and has not been run on production since this example changed. Signing in as a second person needs a second account and is not covered here.
 
 If `/` shows "One step left", `CROUTER_CLIENT_ID` is empty: repeat step 5 and restart. If a call fails with `426 runtime_version_unsupported`, your SDK is newer than the Northlight runtimes. Install the previous version with `npm i --save-exact @north-light/sdk@<version>` and tell support@northlight.ai.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.478",
+  "version": "0.3.479",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -137,7 +137,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.478",
+    "@north-light/identity": "0.3.479",
     "@earendil-works/pi-agent-core": "1.1.0",
     "@earendil-works/pi-ai": "1.1.0",
     "@earendil-works/pi-coding-agent": "1.1.0",

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.478",
+  "version": "0.3.479",
   "description": "Northlight access-token verification and scope rules",
   "type": "module",
   "main": "./dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.478",
+  "version": "0.3.479",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.478",
+      "version": "0.3.479",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -18,7 +18,7 @@
         "@earendil-works/pi-ai": "1.1.0",
         "@earendil-works/pi-coding-agent": "1.1.0",
         "@earendil-works/pi-tui": "1.1.0",
-        "@north-light/identity": "0.3.478",
+        "@north-light/identity": "0.3.479",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12116,17 +12116,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.478",
+      "version": "0.3.479",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.478",
+      "version": "0.3.479",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.478",
+      "version": "0.3.479",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12134,25 +12134,28 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.478",
+      "version": "0.3.479",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.478",
-        "@north-light/identity": "0.3.478"
+        "@north-light/api": "0.3.479",
+        "@north-light/identity": "0.3.479"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.478",
+      "version": "0.3.479",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.478",
-        "@north-light/identity": "0.3.478",
+        "@north-light/api": "0.3.479",
+        "@north-light/identity": "0.3.479",
         "jose": "^6.2.1"
       },
       "bin": {
         "crouter-sdk": "dist/keygen-cli.js"
       },
+      "engines": {
+        "node": ">=20.6.0"
+      },
       "peerDependencies": {
         "pg": "^8.0.0"
       },