@north-light/cli 0.3.485 → 0.3.486

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.10";
+export declare const CONTRACT_LEVEL = "1.11";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -1 +1 @@
-var c=Object.defineProperty;var e=(r,t)=>c(r,"name",{value:t,configurable:!0});const f="1.10",i="Crouter-Required-Contract",p="Crouter-Contract";function l(r){const t=/^(\d+)\.(\d+)$/.exec(r.trim());return t===null?null:{major:Number(t[1]),minor:Number(t[2])}}e(l,"parseContractLevel");function a(r){return r==null?[]:r.split(",").map(t=>l(t)).filter(t=>t!==null)}e(a,"parseServedContracts");function s(r,t){const n=l(r);return n===null?!1:(typeof t=="string"||t===null||t===void 0?a(t):t).some(u=>u.major===n.major&&u.minor>=n.minor)}e(s,"contractSatisfies");function C(r,t,n={}){if(r===void 0)return null;if(l(r)===null)return{status:400,code:"invalid_request",param:i,message:`${i} must be a contract level like 1.0.`};if(s(r,t))return null;const o=r.trim();return{status:426,code:"runtime_version_unsupported",message:t===null||a(t).length===0?`The runtime did not name its contract level; the caller requires contract ${o} or later. Roll the runtime forward.`:`The runtime serves contract ${t}; the caller requires contract ${o} or later within the same major. Roll the runtime forward, or pin an SDK whose crouterContract the runtime serves.`,details:{sdk_version:(n.legacyMinimum??"").trim(),runtime_version:n.runtimeVersion??null,required_contract:o,runtime_contract:t}}}e(C,"contractRefusal");export{p as CONTRACT_HEADER,f as CONTRACT_LEVEL,i as REQUIRED_CONTRACT_HEADER,C as contractRefusal,s as contractSatisfies,l as parseContractLevel,a as parseServedContracts};
+var c=Object.defineProperty;var e=(r,t)=>c(r,"name",{value:t,configurable:!0});const f="1.11",i="Crouter-Required-Contract",p="Crouter-Contract";function l(r){const t=/^(\d+)\.(\d+)$/.exec(r.trim());return t===null?null:{major:Number(t[1]),minor:Number(t[2])}}e(l,"parseContractLevel");function a(r){return r==null?[]:r.split(",").map(t=>l(t)).filter(t=>t!==null)}e(a,"parseServedContracts");function s(r,t){const n=l(r);return n===null?!1:(typeof t=="string"||t===null||t===void 0?a(t):t).some(u=>u.major===n.major&&u.minor>=n.minor)}e(s,"contractSatisfies");function C(r,t,n={}){if(r===void 0)return null;if(l(r)===null)return{status:400,code:"invalid_request",param:i,message:`${i} must be a contract level like 1.0.`};if(s(r,t))return null;const o=r.trim();return{status:426,code:"runtime_version_unsupported",message:t===null||a(t).length===0?`The runtime did not name its contract level; the caller requires contract ${o} or later. Roll the runtime forward.`:`The runtime serves contract ${t}; the caller requires contract ${o} or later within the same major. Roll the runtime forward, or pin an SDK whose crouterContract the runtime serves.`,details:{sdk_version:(n.legacyMinimum??"").trim(),runtime_version:n.runtimeVersion??null,required_contract:o,runtime_contract:t}}}e(C,"contractRefusal");export{p as CONTRACT_HEADER,f as CONTRACT_LEVEL,i as REQUIRED_CONTRACT_HEADER,C as contractRefusal,s as contractSatisfies,l as parseContractLevel,a as parseServedContracts};

package/dist/builtin-memory/crouter-concepts/scopes-and-trust.md

@@ -17,6 +17,7 @@ Scope strings are prefixed with `crtr:`. These are the ones the daemon and CLI c
 | `crtr:act` | Creating, forking, reviving, closing and messaging nodes; `bash` and `files`; creating a human request or review (the `crtr human` commands are hidden from a run without it) |
 | `crtr:schedule` | Creating, pausing, resuming, running and deleting crons (the `crtr cron` commands are hidden without it) |
 | `crtr:memory:read:user[:path]`, `crtr:memory:rw:user[:path]`, `crtr:memory:manage:user` | The person's documents: reading, writing (`crtr doc`), and `manage` for every privacy level and every document |
+| `crtr:memory:read_private:user` | Read-only access to the person's `public` and `private` documents, never `friends`; no path suffix; an optional permission the person switches on; `manage:user` covers it, `read:user` and `rw:user` do not |
 | `crtr:memory:read:app:<id>`, `crtr:memory:rw:app:<id>` | An app's documents; `…:profile:<profile>` narrows to one of its profiles. A run with no `scopes` list, and an app's own server, reads and writes its own app's space freely; a run started with a `scopes` list needs these for its own app too |
 | `crtr:files:read\|rw:user:<dir>`, `crtr:files:read\|rw:app:<id>:<dir>`, `crtr:files:share` | Host files the run may mount, and sharing files beyond the app's own space |
 | `crtr:conversations:read:app:<id>`, `crtr:objects:read:app:<id>` | Reading another app's conversations or node objects |
@@ -24,7 +25,7 @@ Scope strings are prefixed with `crtr:`. These are the ones the daemon and CLI c
 
 The `memory` in `crtr:memory:*` is the scope family's name for access to **documents** (see [[crouter-concepts/documents]]); there is no separate memory store. The older short names (`ask`, `act`, `schedule`, `memory:read`, `memory:write`, `llm`) are not accepted by `crtr sys connect --scopes`. A node's own documents, and an app's documents for its own nodes, need no `crtr:memory` scope.
 
-This is an allow-list, not a claim that code will behave. The daemon checks the scope at the route that performs the action and rejects an unavailable one. The SDK’s [[crouter-sdk/nodes]] `scopes` field narrows a run: a run's list must stay inside what its creator and grant hold, and `crtr:act` requires `crtr:llm`. `client.memory` is not scope-gated: it lists and reads the person's `knowledge` and `preference` documents, and the answer is filtered by privacy — an app sees `public` documents, and a grant holding `crtr:memory:manage:user` also sees `friends` and `private` ones. Who may read any document is the owner-and-privacy model, not a per-call scope. The exception is a run started with a `scopes` list: it reads its own app's documents (including automatic delivery of them at boot) only with `crtr:memory:read:app:<id>` and writes or edits them only with `crtr:memory:rw:app:<id>`; a refused write answers `scope_missing` naming the scope. Such a run still publishes its own reports with `crtr push` and its promoted node still gets a roadmap, but cannot edit any other document through that path, and a child never regains a scope its parent's list dropped.
+This is an allow-list, not a claim that code will behave. The daemon checks the scope at the route that performs the action and rejects an unavailable one. The SDK’s [[crouter-sdk/nodes]] `scopes` field narrows a run: a run's list must stay inside what its creator and grant hold, and `crtr:act` requires `crtr:llm`. `client.memory` is not scope-gated: it lists and reads the person's `knowledge` and `preference` documents, and the answer is filtered by privacy — an app sees `public` documents, a grant holding `crtr:memory:read_private:user` also sees `private` ones, and a grant holding `crtr:memory:manage:user` sees `friends` and `private` ones. Who may read any document is the owner-and-privacy model, not a per-call scope. The exception is a run started with a `scopes` list: it reads its own app's documents (including automatic delivery of them at boot) only with `crtr:memory:read:app:<id>` and writes or edits them only with `crtr:memory:rw:app:<id>`; a refused write answers `scope_missing` naming the scope. Such a run still publishes its own reports with `crtr push` and its promoted node still gets a roadmap, but cannot edit any other document through that path, and a child never regains a scope its parent's list dropped.
 
 ```mermaid
 flowchart LR

package/dist/builtin-memory/crouter-sdk/getting-started.md

@@ -80,7 +80,7 @@ crtr sys connect --app my-app --scopes crtr:llm,crtr:act,crtr:memory:read:user
 
 `--scopes` requires `--app` (the app id, without the `app:` prefix) and accepts only `crtr:llm`, `crtr:act`, `crtr:schedule`, `crtr:memory:read:user`, `crtr:memory:read:app`, `crtr:memory:rw:app`, `crtr:files:read:user:.` and `crtr:files:rw:user:.`. This mints a new token for that app whose scope list is a ceiling, appends it to the same secrets store, prints it in place of the owner token, and always hands the daemon over (it reads tokens once, at boot). The ceiling is checked on every request that carries the token:
 
-- A scope-gated operation the ceiling lacks answers `403 scope_denied`. Creating, reviving, forking, messaging, or yielding a node needs `crtr:act`, as do `bash`, `files`, and creating a human request or review (there is no separate scope for human requests); arming or running a cron needs `crtr:schedule`; `/v1/llm` needs `crtr:llm`. `client.memory` has no scope of its own: it reads the person's documents filtered by privacy, and a grant holding `crtr:memory:manage:user` sees every level.
+- A scope-gated operation the ceiling lacks answers `403 scope_denied`. Creating, reviving, forking, messaging, or yielding a node needs `crtr:act`, as do `bash`, `files`, and creating a human request or review (there is no separate scope for human requests); arming or running a cron needs `crtr:schedule`; `/v1/llm` needs `crtr:llm`. `client.memory` has no scope of its own: it reads the person's documents filtered by privacy, and a grant holding `crtr:memory:read_private:user` also sees `private` documents, and one holding `crtr:memory:manage:user` sees every level.
 - `nodes.create` with `scopes` outside the ceiling answers `403 scope_denied`; `details.scopes` lists the offending scopes. Omit `scopes` and the run gets the ceiling.
 - Owner-only operations — daemon restart, the attach viewer, broker internals, canvas prune, profile pause/resume/delete, model credential install — answer `403 owner_only` to any scoped token.
 

package/dist/builtin-memory/crouter-sdk/release-notes.md

@@ -9,6 +9,15 @@ when-and-why-to-read: When you need Release notes, this knowledge should be read
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.486
+
+### `crtr:memory:read_private:user` and `oauth.permissionUrl` (additive, no app change)
+
+- The scope `crtr:memory:read_private:user` lets an app read the person's `private` memory as well as `public`, read-only. `friends` documents are never included, and the scope grants no write. `crtr:memory:manage:user` covers it; `read:user` and `rw:user` do not. It takes no path suffix. With it, `memory.list` and `memory.get` (and the memory a run reads) return `private` documents marked `privacy: 'private'`; without it they read as absent. A run started with a `scopes` list sees `private` only if that list covers it (names it, or names `crtr:memory:manage:user`). The grant can lose the scope while a run is live: the run's next read stops returning private documents, but what it already read stays in its context, so restart runs when access turns off.
+- New `await oauth.permissionUrl(scope, {returnTo?})` returns `accountAppUrl()` with `permission=<scope>` and, when given, `return_to=<returnTo>`, so the person lands on the account page with that optional permission's switch first. It throws `CrouterError` when `scope` is not a valid scope string.
+- `FakeCloud` memory visibility honors `read_private` (public and private, never friends). It follows the user's whole grant, not a run's narrowed `scopes`.
+- A runtime older than this release cannot parse the scope and marks a grant that holds it inactive, so a directory change that offers it waits until hosted runtimes are on this release.
+
 ## 0.3.484
 
 Plugins can now declare canvas object kinds and act on the canvas, and an app token can be granted canvas scopes. Everything below is additive: no request or response an existing app sends or reads changes, with one runtime-side exception under [Unknown bearers](#unknown-bearers-are-refused).

package/dist/builtin-memory/northlight-apps/guides/files-and-documents.md

@@ -21,7 +21,7 @@ A non-2xx answer is thrown as an `APIError`, never returned as bytes. A bad `ran
 
 ## Read the person's public documents
 
-`runtime.memory` is a read-only view of the `knowledge` and `preference` documents the person owns (`memory` and the `/v1/memory` routes are the API's names for this). An app reads the person's `public` documents with `memory.list` and `memory.get`, and needs no scope to do it. It never sees a `friends` or `private` document and cannot tell one from a document that does not exist: both answer `404 not_found`. The list is what the app's agents can read about the person, so an app can show the person exactly which of their documents it draws on.
+`runtime.memory` is a read-only view of the `knowledge` and `preference` documents the person owns (`memory` and the `/v1/memory` routes are the API's names for this). An app reads the person's `public` documents with `memory.list` and `memory.get`, and needs no scope to do it. Without more, it never sees a `friends` or `private` document and cannot tell one from a document that does not exist: both answer `404 not_found`. The optional scope [`crtr:memory:read_private:user`](#private-memory) adds `private`. The list is what the app's agents can read about the person, so an app can show the person exactly which of their documents it draws on.
 
 ```ts
 const page = await runtime.memory.list({store: 'user'});
@@ -31,7 +31,7 @@ const doc = await runtime.memory.get({store: 'user', name: page.items[0].name});
 console.log(doc.body);
 ```
 
-`store` is `'user'` in this release; any other value answers `400 invalid_request` with `param: "store"`. An app whose grant holds `crtr:memory:manage:user` (a first-party app) sees every privacy level. Reading records nothing: no watch, no `read` event, no audit row. Both methods are `GET` requests and follow the SDK's retry rule for safe requests.
+`store` is `'user'` in this release; any other value answers `400 invalid_request` with `param: "store"`. An app whose grant holds `crtr:memory:manage:user` (a first-party app) sees every privacy level; one that holds `crtr:memory:read_private:user` sees `public` and `private`. Reading records nothing: no watch, no `read` event, no audit row. Both methods are `GET` requests and follow the SDK's retry rule for safe requests.
 
 ### List
 
@@ -58,4 +58,13 @@ for await (const item of runtime.memory.listAll({store: 'user', path: 'work'}))
 
 - `body` is the current markdown as stored; `[[links]]` are not resolved. A body over 1 MiB is cut to its longest whole-character prefix of at most 1 MiB, with `truncated: true`; `size` is always the full length in UTF-8 bytes.
 - `grantee` is `app:<id>` of the app whose agent wrote the first revision, or `null` when the person wrote it.
-- An absent, deleted, `friends` or `private` name rejects with `NotFoundError` (`code: 'not_found'`); a malformed field rejects with `BadRequestError`.
+- An absent or deleted name, a `friends` name, and a `private` name without `crtr:memory:read_private:user` reject with `NotFoundError` (`code: 'not_found'`); a malformed field rejects with `BadRequestError`.
+
+## Private memory
+
+`crtr:memory:read_private:user` is an [[northlight-apps/guides/grant-changes]] that lets your app read the person's `private` documents. Declare it, then let the person switch it on from your app (sign-in request or `permissionUrl`).
+
+- **Read-only, and never `friends`.** With the scope `memory.list` and `memory.get` return `public` and `private` documents; a `friends` document still reads as absent, and the scope writes nothing. Each private document arrives with `privacy: 'private'`.
+- **Both server reads and runs.** Your server's `memory` calls see private documents while the grant holds the scope. A run sees them only if it was started with the scope: `runs.start` `scopes` must cover `crtr:memory:read_private:user` (name it, or name `crtr:memory:manage:user` if the grant holds that) (a run with no `scopes` list gets what the grant holds), and the start is refused `403 scope_missing` while the grant lacks it. Add the scope to the runs that need it only while `resolved_scopes` holds it.
+- **The person can turn it off at any time.** Reads then stop returning private documents at once, including from a run that is still live. That run keeps what it already read in its context, so restart the runs that used it when the permission turns off (`watchGrants` tells you).
+- **Never show a private detail to anyone but the owner**, unless the owner asked your app to. A visitor, a guest or another user must not see a fact, quote or summary taken from a private document.

package/dist/builtin-memory/northlight-apps/guides/grant-changes.md

@@ -39,6 +39,22 @@ await watcher.stop();
 - **If `onChanged` throws**, the same version is delivered again after 5 s, doubling to 5 min. A transient runtime error backs off the same way. A missing or refused connection drops that user and reports to `onError`; the next sweep decides again from `users()`.
 - For one person without the watcher, `runtime.grant.get({wait: 25, since: grant.version})` holds a single read the same way. `wait` outside 1–25 throws `RangeError` before sending.
 
+## Optional permissions
+
+An optional permission is a scope your app can use but does not need to work. The person turns it on or off for your app, on the consent page and later on the app's Northlight account page, and your app keeps working when it is off.
+
+- **Declare it** in the app's registration: `crtr cloud apps set-optional-scopes` (or the console's **What it asks for** tab). The first one is `crtr:memory:read_private:user`: see [[northlight-apps/guides/files-and-documents]].
+- **Ask at sign-in only when the person chose to.** Add the scope to `authorizeUrl`'s `scopes` only after the person said they want it in your app. A person who declines an optional row on the consent page sees the page again on every sign-in request that names it, so naming it for everyone nags everyone. Leave the sign-in request unchanged for everyone else.
+- **Or link to the switch** with `permissionUrl`. It opens the account page with that scope's switch first, and `returnTo` (an absolute URL on one of your registered redirect origins; anything else is ignored) puts a "Back to your app" button on it once the person turns it on:
+
+```ts
+const href = await oauth.permissionUrl('crtr:memory:read_private:user', {returnTo: 'https://app.example.com/settings'});
+```
+
+  It needs no user or connection, like `accountAppUrl`, and throws `CrouterError` when the scope is not a valid scope string.
+- **Read the state from the grant.** The permission is on when the scope is in `grant.resolved_scopes` and off when it is not. Never keep your own copy of the person's choice.
+- **Follow changes with `watchGrants`** (above). A switch changes the grant's `version`, so `onChanged` delivers it. Decide from the grant as it is now: start the work that needs the scope when it appears, and stop or restart it when it disappears.
+
 ## Wait on a provider your app requires
 
 An app whose registration `requires` a provider (the console's **What your app requires**) needs that provider set up for the person before the operations that depend on it work. The runtime does not check this for you. `grant.get()` returns `dependencies`: one entry per setup id the app requires or lists as optional (plus any the directory implies, such as `device` for `context.deep`), keyed by setup id, or `{}` when it has none. Read it on each request that needs the provider; do not store it.

package/dist/builtin-memory/northlight-apps/guides/many-users.md

@@ -48,7 +48,7 @@ A visitor chatting with B's clone starts an app run on **B's runtime and B's AI
 
 A run your app starts is **your app's agent**, not a continuation of another app's agent. It starts in `/apps/<app>/files`, uses the person's AI under `crtr:llm`, and reaches your app's own documents (owned by `app:<your app>`) without a `crtr:memory` scope. Other people's or apps' data is not shared merely because the app has many users. The grant's resolved permissions govern access to the person's files (`crtr:files:<access>:user:<dir>`), the person's documents (`crtr:memory:<access>:user`), another app's space (only where that app allows it), and another app's conversations (`crtr:conversations:read:app:<B>`).
 
-The exception is the person's **public** documents (owned by the person, read through `memory`; see [[northlight-apps/guides/files-and-documents]]): an app with an active grant can read these even without a user-memory scope. A third-party app cannot see `friends` or `private` documents, even with `crtr:memory:read:user`. They look absent from lists, searches, reads and history. Only a holder of `crtr:memory:manage:user` (a first-party app), or the person, reads all three levels. A document without a privacy field reads as `private`. Public read access is not write access.
+The exception is the person's **public** documents (owned by the person, read through `memory`; see [[northlight-apps/guides/files-and-documents]]): an app with an active grant can read these even without a user-memory scope. A third-party app cannot see `friends` documents, and sees `private` ones only with the optional `crtr:memory:read_private:user` the person switched on; `crtr:memory:read:user` reveals neither. They look absent from lists, searches, reads and history. Only a holder of `crtr:memory:manage:user` (a first-party app), or the person, reads all three levels. A document without a privacy field reads as `private`. Public read access is not write access.
 
 Every run is sandboxed: its shell runs as the app's OS user and sees only the app's space and the folders its permissions name. Normal runs have network access. Start a run with `isolated: true` when the agent should have **no network** and **no `/apps/<app>/files` mount**: its cwd is its own node folder, and all children inherit the restriction. The shell, stored conversation and model calls still work, and the run's `scopes` can narrow its commands. An isolated run cannot turn isolation off in a child or schedule, or use an outside cwd or worktree.
 

package/dist/builtin-memory/northlight-apps/guides/test-your-app.md

@@ -119,7 +119,7 @@ In your callback handler, check `authorizationRefusalOf(url)` before reading `co
 
 ## Memory and providers
 
-`user.memory.put({name, body, privacy = 'public', kind = 'knowledge', ...})` and `remove(name)`. Without `crtr:memory:manage:user` in the grant, only `public` documents are listed and others read as 404, as on the runtime. List items carry the full `MemoryListItem` fields.
+`user.memory.put({name, body, privacy = 'public', kind = 'knowledge', ...})` and `remove(name)`. Without `crtr:memory:manage:user` in the grant, only `public` documents are listed and others read as 404, as on the runtime; `crtr:memory:read_private:user` adds `private` (never `friends`). FakeCloud applies the user's whole grant (`user.grant.set`), not the `scopes` a run was started with; test narrowed runs on the real runtime. List items carry the full `MemoryListItem` fields.
 
 ```ts
 cloud.providers.define('sms', { tools: { send: { group: 'send', handler: ({ userId, arguments: args }) => ({ sent: true }) } } });