@north-light/cli 0.3.542 → 0.3.544

package/docs/apps/reach-people-by-text.md

@@ -0,0 +1,47 @@
+---
+title: Reach people by text
+description: Give your app its own iMessage number with Comms. People text it, your server answers with an agent run on their runtime, and you can text them again later.
+---
+
+# Reach people by text
+
+Comms gives your app its own iMessage number, under your app's name and avatar. People text that number, Comms sends each text to your server as a signed webhook, and your server answers with an agent run on the person's own runtime. Once a person has texted you, your app can text them again later, for example from a timer.
+
+```ts
+import {continueInRuntime, formatReply, verifyWebhook} from '@north-light/comms';
+
+const event = verifyWebhook(req.headers, rawBody, [process.env.COMMS_WEBHOOK_SECRET!]);
+if (event.type === 'message.received' && event.data.content.type === 'text') {
+  const {contact, content} = event.data;
+  if (!contact.user) return; // only a sender texting from an Apple ID email has no user
+  const client = await oauth.client(contact.user.id); // their Northlight user id, the same as Connection.userId
+  const {runId, reply} = await continueInRuntime({client, message: content.text, runId: runs.get(contact.id), idempotencyKey: event.id});
+  runs.set(contact.id, runId); // later texts continue the same run
+  const {text} = await reply.collect();
+  for (const part of formatReply(text)) {
+    await comms.sendMessage({environment: event.environment, to: {contact_id: contact.id}, text: part, idempotency_key: `reply:${event.id}:${part.length}`});
+  }
+}
+```
+
+`oauth.client` throws `CrouterError` with code `not_connected` when the person has not signed in to your app yet. Answer that with `sendSignInLink(comms, contact, {environment: event.environment})`: Comms texts them a link that signs them in to your app, which lands on your **Sign-in start URL** (console → **Profile** → **Marketplace**).
+
+## The steps
+
+The [Comms guide for coding agents](https://comms.northlight.ai/llms.txt) is the whole reference: the webhook events, the send API, its errors, STOP and HELP handling, and the `crtr comms` commands. In short:
+
+1. **Build in fake mode.** `npx @north-light/comms fake --webhook http://localhost:3000/hook` runs a local Comms with no account. `npx @north-light/comms fake send --from +15550001 --text "hi"` plays a person texting you.
+2. **Register your app on Northlight.** [Quick setup](/docs/quickstart) steps 1 to 4: sign up, `npx @north-light/sdk login`, `npx @north-light/sdk register`. Comms signs in with the same app key.
+3. **Connect the app to Comms.** At `https://comms.northlight.ai`, sign in and choose **Connect an app**. This is done in a browser only.
+4. **Turn Texting on.** On the app's page there, or with `crtr comms turn-on`: a display name, a square avatar, the HELP text and your test webhook URL. The page shows the test webhook signing secret.
+5. **Text it from your own phone, in test mode.** Add yourself as a tester (`crtr comms testers add --app-id <id> --phone <number> --label <name>`, or the site), then text `JOIN <code>` to the test number. Test mode is free; the [Comms guide](https://comms.northlight.ai/llms.txt) has the tester limit.
+6. **Go to production** when you want your app's own number and anyone to text it. Production is paid: add a card on the billing account, and Comms gets your app its own number.
+
+Comms is priced per person your app texts with in production each month; fake mode and testing are free. The SDK is [`@north-light/comms`](https://www.npmjs.com/package/@north-light/comms) on npm. Its 0.3.0 release declares `@north-light/sdk` 0.3.457 as an exact optional peer, so in a project pinned to a newer SDK install it with `npm i @north-light/comms --legacy-peer-deps`.
+
+## Rules
+
+- **People text first.** Your app can text a person only after they texted your number in that environment, and until they send STOP. A send to anyone else fails `403 not_texted_first`.
+- **Address people by `contact_id` or `user_id`**, never by phone number.
+- **Derive `idempotency_key` from the event you are answering**, so a retried webhook sends nothing twice. Deduplicate deliveries on `event.id`.
+- **Verify the raw body** with `verifyWebhook` before you parse it, and answer `2xx` within 15 seconds.

package/docs/apps/use-our-ai.md

@@ -0,0 +1,27 @@
+---
+title: Let your app use our AI
+description: Start agent runs on each person's own Northlight runtime, with their memory, files and tools, paid by their AI subscription. Typed results, streaming, background runs and documents.
+---
+
+# Let your app use our AI
+
+Your app starts agents on the person's own Northlight runtime. Each run has their memory, files and tools, works under the scopes they approved, and its model calls are paid by their AI subscription, not by you.
+
+<include lang="ts">../../examples/apps/runs-parse.ts</include>
+
+`runs.parse` starts a run and returns a value checked against your schema. `runs.start` returns at once and lets you follow the run, reply to it or leave it running.
+
+## Guides
+
+| Page | What it covers |
+|---|---|
+| [Runs](/docs/concepts/runs) | Start a run, its status and outcome, a run's own scopes, and how to bound one |
+| [Typed results](/docs/guides/typed-results) | Get a value back with `runs.parse` and a schema; never parse the trace |
+| [Stream a run](/docs/guides/stream-a-run) | Show the agent's text and tool calls as they happen |
+| [Background runs](/docs/guides/background-runs) | Learn when a run you did not wait on has ended, with `RunWatcher` or run notices |
+| [Files and documents](/docs/guides/files-and-documents) | Download a file from a run, and read the person's public documents |
+| [Many users](/docs/guides/many-users) | Keep each person's runtime separate when people meet in your app |
+
+To schedule work, call `runs.start` from your own timer. A run's agent may also schedule itself with `crtr cron add` when the run holds `crtr:schedule` ([Scopes and grants](/docs/concepts/scopes-and-grants)).
+
+An app that pays for its own model calls instead can serve them from its own service with `inferenceEndpoint` from `@north-light/sdk`; see the [release notes](/docs/release-notes) and the [reference](/docs/reference).

package/docs/apps/use-our-apps.md

@@ -0,0 +1,32 @@
+---
+title: Let your app use our apps
+description: Call Northlight's providers from your app on the person's runtime — texting their phone, web search, their connected accounts, their Mac — with providers.tools and providers.call.
+---
+
+# Let your app use our apps
+
+Northlight's own apps are providers your app can call on the person's runtime: text their phone, place calls, search the web, open a cloud browser, read and act in the accounts they connected, and use their Mac. The person approves each provider's scope once, on your app's consent page.
+
+<include lang="ts">../../examples/apps/provider-tools.ts</include>
+
+Every provider works the same way: ask for its scope, list its tools with `providers.tools('<provider>')`, then call one with `providers.call`. Scope strings, tool names and arguments come from those lists, never from memory.
+
+## Providers
+
+| Provider id | What it does | Page |
+|---|---|---|
+| `sms` | Texts the signed-in person's own verified phone | [Texting (sms)](/docs/providers/sms) |
+| `search` | Web search, sourced answers, page contents and paid data endpoints | [Search](/docs/providers/search) |
+| `integrations` | The person's own accounts at other services | [Integrations](/docs/providers/integrations) |
+| `context` | Ask about the person from their memory, and look up public profiles | [Context](/docs/providers/context) |
+| `device` | The person's Mac: browser, files, Messages and shell | [Device](/docs/providers/device) |
+
+These five have pages here. Northlight also runs `phone` (calls from Northlight's number, with an AI voice), `browser` (cloud browser sessions) and `meetings` (the person's meeting notes and transcripts), which have no page yet. For any of them, `providers.tools()` with no argument lists every provider installed on the person's runtime, `providers.tools('<provider>')` lists its tools and arguments, and the console's **Add permissions** list shows every scope your app can ask for.
+
+## Guides
+
+| Page | What it covers |
+|---|---|
+| [Providers](/docs/concepts/providers) | Scopes, finding and calling tools, and providers your app requires |
+| [Providers index](/docs/providers) | Every first-party provider, its scopes and where names come from |
+| [Grant changes](/docs/guides/grant-changes) | When a person adds or removes a scope, and waiting on a provider's setup |

package/docs/cli/join-northlight.md

@@ -5,7 +5,7 @@ description: Join a laptop to your Northlight account with crtr sys join so crtr
 
 # Join a machine to your Northlight account
 
-Joining makes this machine one of your Northlight account's machines, so `crtr cloud …` commands run as you. Building an app does not need it: the [SDK docs site](https://sdk.docs.northlight.ai/docs/quickstart) takes you through the web console. Join when you want to run `crtr cloud apps` yourself.
+Joining makes this machine one of your Northlight account's machines, so `crtr cloud …` commands run as you. Join when you want to run `crtr cloud apps` yourself, or to let your own crtr agents build and manage your Northlight apps. Building an app works without it too: the [SDK docs site](https://sdk.docs.northlight.ai/docs/get-started) uses `npx @north-light/sdk` and the web console.
 
 Create your account at `https://account.northlight.ai/signup` first. Then install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.436 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
 

package/docs/plugin/commands.md

@@ -30,7 +30,7 @@ definePlugin({
 });
 ```
 
-Each group has `consentLine`, the line the directory's consent page shows, and optionally `who` (`own`, `user`, `allowlist`, `any` or `team:<id>`; the directory treats an omitted `who` as `user`) and `allowlist` (app principals `app:<id>`, required with `who: 'allowlist'` and refused otherwise). `buildBundle` writes the block into `bundle.json` as `groups`, and the directory applies it when it refreshes the provider's manifest. The directory refuses a provider archive whose `bundle.json` has no `groups` (`bundle.json groups: is required`), and a provider's groups come only from this declaration: the directory's console and CLI do not edit groups. `definePlugin` itself accepts a provider without `groups`, but once declared every leaf's `group` must name a declared group and every declared group must be used by at least one leaf; `definePlugin` throws `PluginDefinitionError` otherwise. A plugin that is not `provider: true` must not declare `groups`.
+Each group has `consentLine`, the line the directory's consent page shows, and optionally `who` (`own`, `user`, `allowlist`, `any` or `team:<id>`; the directory treats an omitted `who` as `user`) and `allowlist` (app principals `app:<id>`, required with `who: 'allowlist'` and refused otherwise). `buildBundle` writes the block into `bundle.json` as `groups`, and the directory applies it when it refreshes the provider's manifest. The directory refuses a provider archive whose `bundle.json` has no `groups` (`bundle.json groups: is required`), and a provider's groups come only from this declaration: the directory's console and CLI do not edit groups. `definePlugin` itself accepts a provider without `groups`, but once declared every leaf's `group` must name a declared group, or `definePlugin` throws `PluginDefinitionError`. A declared group no leaf uses is allowed: a provider that ships documents only (`commands: {}` and a `memory` array) declares one so a grant naming it installs the bundle, and it adds no `crtr` command. A plugin that is not `provider: true` must not declare `groups`.
 
 A branch or leaf may set `tier` to `common` or `important` to be promoted into its parent's `-h`. A command with more than 40 children lists only its promoted children in its own `-h`, followed by the count of the rest; the others still run and answer `-h` by name. Use this when a plugin mounts one command per entry of a large catalog. On such a command only promoted leaves reach the top-level `crtr -h`; a promoted branch shows in the command's own `-h`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.542",
+  "version": "0.3.544",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -140,7 +140,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.542",
+    "@north-light/identity": "0.3.544",
     "@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.542",
+  "version": "0.3.544",
   "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.542",
+  "version": "0.3.544",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.542",
+      "version": "0.3.544",
       "hasInstallScript": true,
       "license": "UNLICENSED",
       "workspaces": [
@@ -24,7 +24,7 @@
         "@milkdown/preset-gfm": "^7.22.3",
         "@milkdown/prose": "^7.22.3",
         "@milkdown/utils": "^7.22.3",
-        "@north-light/identity": "0.3.542",
+        "@north-light/identity": "0.3.544",
         "cron-parser": "^5.6.0",
         "esbuild": "^0.27.7",
         "jose": "^6.2.12",
@@ -12455,17 +12455,17 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/api",
-      "version": "0.3.542",
+      "version": "0.3.544",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.542",
+      "version": "0.3.544",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.542",
+      "version": "0.3.544",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12473,20 +12473,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.542",
+      "version": "0.3.544",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.542",
-        "@north-light/identity": "0.3.542"
+        "@north-light/api": "0.3.544",
+        "@north-light/identity": "0.3.544"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.542",
+      "version": "0.3.544",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.542",
-        "@north-light/identity": "0.3.542",
+        "@north-light/api": "0.3.544",
+        "@north-light/identity": "0.3.544",
         "jose": "^6.2.1"
       },
       "bin": {