@north-light/sdk 0.3.484 → 0.3.486

package/README.md

@@ -137,7 +137,7 @@ const {text, ended, error} = await client.runs.reply(run.run_id, run.message!).c
 
 A run working in the background reports what it is doing on `runs.get(runId).activity` (`starting`, `thinking`, `tool` with `tool.name` and `tool.summary`, `writing`, or `between_turns`; `null` once it is no longer `running`), so a polling page shows progress without reading `runs.trace`.
 
-`runs.listAll(filters)` and `memory.listAll(params)` (the person's knowledge and preference documents the caller can read: `public` by default, every privacy level with `crtr:memory:manage:user`) iterate every item across pages with `for await`, fetching the next page only as you go. `runs.delete(runId)` deletes a running run too — it stops the run's turns and sandboxes itself, so there is no need to `cancel` first; deleting a run that is already gone throws `NotFoundError`.
+`runs.listAll(filters)` and `memory.listAll(params)` (the person's knowledge and preference documents the caller can read: `public` by default, `private` too with `crtr:memory:read_private:user`, every privacy level with `crtr:memory:manage:user`) iterate every item across pages with `for await`, fetching the next page only as you go. `runs.delete(runId)` deletes a running run too — it stops the run's turns and sandboxes itself, so there is no need to `cancel` first; deleting a run that is already gone throws `NotFoundError`.
 
 ## Read files and run bash
 

package/dist/client.d.ts

@@ -124,7 +124,8 @@ export declare class Crouter {
     readonly shares: Shares;
     /** Questions agents in runs ask the user (app listener only). */
     readonly questions: Questions;
-    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, and every privacy level with a `crtr:memory:manage:user` grant. */
+    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, `private` ones too while the grant holds
+     *  `crtr:memory:read_private:user` (read-only; `friends` never), and every privacy level with a `crtr:memory:manage:user` grant. */
     readonly memory: Memory;
     /** Scope-filtered provider tools and daemon-mediated calls. */
     readonly providers: Providers;

package/dist/client.js

@@ -63,7 +63,8 @@ export class Crouter {
     shares;
     /** Questions agents in runs ask the user (app listener only). */
     questions;
-    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, and every privacy level with a `crtr:memory:manage:user` grant. */
+    /** Read the documents the person owns (`store: 'user'`): an app sees their `public` documents, `private` ones too while the grant holds
+     *  `crtr:memory:read_private:user` (read-only; `friends` never), and every privacy level with a `crtr:memory:manage:user` grant. */
     memory;
     /** Scope-filtered provider tools and daemon-mediated calls. */
     providers;

package/dist/oauth/index.d.ts

@@ -148,6 +148,17 @@ export declare class OAuth2Client {
      * is absent, does not contain `{client_id}` exactly once, or does not expand to a URL on the issuer's origin.
      */
     accountAppUrl(): Promise<string>;
+    /**
+     * A link to the app's account page with one optional permission opened first: `accountAppUrl()` plus `permission=<scope>`
+     * and, when given, `return_to=<returnTo>`. The directory shows the switch for that scope and, once the person turns it
+     * on, a "Back to <app>" button to `returnTo` (accepted only on the origin of one of the app's registered redirect URIs;
+     * anything else is ignored). Async because it reads discovery as `accountAppUrl` does. Throws `CrouterError` when `scope`
+     * fails `parseScope`, and whatever `accountAppUrl` throws. The person's choice lands in the grant's `resolved_scopes`
+     * (read it with `grants.get`, follow it with `watchGrants`).
+     */
+    permissionUrl(scope: string, options?: {
+        returnTo?: string;
+    }): Promise<string>;
     /** Start a sign-in. When `scopes` includes `openid` the result carries the `nonce` to pass to the exchange; with literal scopes its type is `string`.
      * `prompt: 'consent'` makes the directory show its consent screen even when the person already approved these scopes. */
     authorizeUrl<const S extends readonly string[]>({ scopes, state, codeVerifier, prompt }: {

package/dist/oauth/index.js

@@ -191,6 +191,27 @@ export class OAuth2Client {
             throw new CrouterError(`Directory discovery's account_app_uri_template is not a URL on ${origin}`);
         return expanded;
     }
+    /**
+     * A link to the app's account page with one optional permission opened first: `accountAppUrl()` plus `permission=<scope>`
+     * and, when given, `return_to=<returnTo>`. The directory shows the switch for that scope and, once the person turns it
+     * on, a "Back to <app>" button to `returnTo` (accepted only on the origin of one of the app's registered redirect URIs;
+     * anything else is ignored). Async because it reads discovery as `accountAppUrl` does. Throws `CrouterError` when `scope`
+     * fails `parseScope`, and whatever `accountAppUrl` throws. The person's choice lands in the grant's `resolved_scopes`
+     * (read it with `grants.get`, follow it with `watchGrants`).
+     */
+    async permissionUrl(scope, options = {}) {
+        try {
+            parseScope(scope);
+        }
+        catch {
+            throw new CrouterError(`Unsupported scope: ${scope}`);
+        }
+        const url = new URL(await this.accountAppUrl());
+        url.searchParams.set('permission', scope);
+        if (options.returnTo !== undefined)
+            url.searchParams.set('return_to', options.returnTo);
+        return url.toString();
+    }
     /** Start a sign-in. When `scopes` includes `openid` the result carries the `nonce` to pass to the exchange; with literal scopes its type is `string`.
      * `prompt: 'consent'` makes the directory show its consent screen even when the person already approved these scopes. */
     async authorizeUrl({ scopes, state, codeVerifier, prompt }) {

package/dist/resources/memory.d.ts

@@ -26,7 +26,7 @@ export interface MemoryListItem {
     kind: 'knowledge' | 'preference';
     preview: string;
     summary: string | null;
-    /** Without a `crtr:memory:manage:user` grant an app only ever sees `public`. */
+    /** An app sees `public`; `private` too while its grant holds `crtr:memory:read_private:user`; `friends` only with `crtr:memory:manage:user`. */
     privacy: 'public' | 'friends' | 'private';
     /** The current revision number. */
     revision: number;
@@ -54,9 +54,11 @@ export interface MemoryDocument extends MemoryListItem {
 }
 /**
  * Reads the documents the person owns. The daemon filters each one by the caller's
- * grant: an app reads `public` documents with no scope, and every privacy level with
- * `crtr:memory:manage:user`; without it a `friends` or `private` document reads
- * exactly as an absent one (`NotFoundError`). Reading records nothing.
+ * grant: an app reads `public` documents with no scope, `private` ones too while the grant
+ * holds `crtr:memory:read_private:user` (the person may switch it on and off; `friends` never),
+ * and every privacy level with `crtr:memory:manage:user`; a document above the grant's level
+ * reads exactly as an absent one (`NotFoundError`). A run started with a `scopes` list sees
+ * `private` only if that list covers `crtr:memory:read_private:user` (names it, or `crtr:memory:manage:user`). Reading records nothing.
  */
 export declare class Memory {
     private readonly request;

package/dist/resources/memory.js

@@ -1,9 +1,11 @@
 import { withQuery } from './request.js';
 /**
  * Reads the documents the person owns. The daemon filters each one by the caller's
- * grant: an app reads `public` documents with no scope, and every privacy level with
- * `crtr:memory:manage:user`; without it a `friends` or `private` document reads
- * exactly as an absent one (`NotFoundError`). Reading records nothing.
+ * grant: an app reads `public` documents with no scope, `private` ones too while the grant
+ * holds `crtr:memory:read_private:user` (the person may switch it on and off; `friends` never),
+ * and every privacy level with `crtr:memory:manage:user`; a document above the grant's level
+ * reads exactly as an absent one (`NotFoundError`). A run started with a `scopes` list sees
+ * `private` only if that list covers `crtr:memory:read_private:user` (names it, or `crtr:memory:manage:user`). Reading records nothing.
  */
 export class Memory {
     request;

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.484"
+  sdk-version: "0.3.486"
 ---
 
 # 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.484`. 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.486`. 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
 

package/dist/testing/cloud.d.ts

@@ -298,6 +298,9 @@ export declare class FakeCloud {
     private runMessage;
     private question;
     private memoryStore;
+    /** `public` always; `private` with `crtr:memory:read_private:user`; every level with `crtr:memory:manage:user`; `friends` never
+     *  below manage. Unlike the real runtime, which narrows a run to the `scopes` it was started with, this reads the user's whole
+     *  grant (`user.grant.set`): narrowed runs are tested on the real runtime. */
     private memoryVisible;
     private memoryList;
     private providerEntry;

package/dist/testing/cloud.js

@@ -965,8 +965,14 @@ export class FakeCloud {
         if (value !== 'user')
             throw invalid('store must be "user"', 'store');
     }
+    /** `public` always; `private` with `crtr:memory:read_private:user`; every level with `crtr:memory:manage:user`; `friends` never
+     *  below manage. Unlike the real runtime, which narrows a run to the `scopes` it was started with, this reads the user's whole
+     *  grant (`user.grant.set`): narrowed runs are tested on the real runtime. */
     memoryVisible(user, doc) {
-        return doc.privacy === 'public' || user.scopeStrings().some((scope) => covers(scope, 'crtr:memory:manage:user'));
+        const scopes = user.scopeStrings();
+        if (doc.privacy === 'public' || scopes.some((scope) => covers(scope, 'crtr:memory:manage:user')))
+            return true;
+        return doc.privacy === 'private' && scopes.some((scope) => covers(scope, 'crtr:memory:read_private:user'));
     }
     memoryList(user, query) {
         this.memoryStore(query);

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.484";
+export declare const SDK_VERSION = "0.3.486";
 /** 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.484';
+export const SDK_VERSION = '0.3.486';
 // 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,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.484",
-  "crouterContract": "1.10",
+  "version": "0.3.486",
+  "crouterContract": "1.11",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,8 +44,8 @@
     "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.484",
-    "@north-light/identity": "0.3.484",
+    "@north-light/api": "0.3.486",
+    "@north-light/identity": "0.3.486",
     "jose": "^6.2.1"
   },
   "peerDependencies": {