@north-light/cli 0.3.483 → 0.3.485

package/dist/daemon/plugin-objects/read-leaf.d.ts

@@ -0,0 +1,20 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ObjectRow } from '../../core/graph/types.js';
+import type { RequestPrincipal } from '../api/router.js';
+export declare const READ_LEAF_DEADLINE_MS = 15000;
+export interface ReadDelegation {
+    plugin: string;
+    command: string[];
+    id: string;
+    name: string;
+}
+export type ReadLeafResult = {
+    markdown: string;
+} | {
+    unavailable: string;
+};
+/** The delegation for a custom object, or null when its kind has no read leaf or no installed plugin declares it any more (`declared=0`: an inert
+ *  kind shows the last announcement). Sync: runs inside the first read transaction. */
+export declare function readDelegationFor(db: DatabaseSync, object: ObjectRow): ReadDelegation | null;
+/** Run the declared read leaf as `principal`. Never throws. */
+export declare function runReadLeaf(d: ReadDelegation, principal: RequestPrincipal, deadlineMs?: number): Promise<ReadLeafResult>;

package/dist/daemon/plugin-objects/read-leaf.js

@@ -0,0 +1,2 @@
+var f=Object.defineProperty;var l=(n,o)=>f(n,"name",{value:o,configurable:!0});import{randomUUID as g}from"node:crypto";import{prepared as h}from"../../core/sqlite-statements.js";import{listInstalledPlugins as v}from"../../core/resolver.js";import{validatePluginCommands as b}from"../../core/command-plugins/discovery.js";import{executeExternalLeafAsync as E}from"../../core/command-plugins/transport/exec-invoke-async.js";import{invokeHttpLeaf as k}from"../../core/command-plugins/transport/http-invoke.js";import{sha256Hex as x,signedHeaderDigest as _}from"../../core/command-plugins/transport/sign.js";import{pluginAppEnv as w}from"../../core/plugin-app.js";import{callProvider as y}from"../../core/providers/call.js";import{callerFromRequest as L}from"../api/handlers/providers.js";import{signCallHeaders as P}from"../api/handlers/plugin-app-token.js";const j=15e3;function C(n,o){const a=h(n,`SELECT k.read_json, k.declared, i.scheme, i.external_id FROM object_kinds k
+    LEFT JOIN identities i ON i.object = k.owner WHERE k.name = ?`).get(o.type);if(a===void 0||a.read_json===null||a.declared===0||a.scheme!=="app"||a.external_id===null||!a.external_id.startsWith("app:"))return null;const e=JSON.parse(a.read_json).command;return{plugin:a.external_id.slice(4),command:e,id:o.id,name:o.name}}l(C,"readDelegationFor");async function J(n,o,a=j){try{const e=v("user").find(r=>r.name===n.plugin);if(e===void 0||!e.enabled)return{unavailable:`plugin ${n.plugin} is not installed`};const u={id:n.id,name:n.name};let d;if(e.manifest.provider?.id===e.name){const r=AbortSignal.timeout(a),t=y(L(o),{provider:e.name,tool:n.command.join(" "),arguments:u},{requestId:g(),signal:r});t.catch(()=>{}),d=(await Promise.race([t,new Promise((p,i)=>{r.addEventListener("abort",()=>i(new Error(`provider read leaf gave no answer within ${a} ms`)),{once:!0})})])).body}else{const r=b(e),t=r.transport;let i=r.manifest?.roots.find(m=>m.name===e.name);for(const m of n.command)i=i?.kind==="branch"?i.children.find(s=>s?.name===m):void 0;if(i?.kind!=="leaf"||t?.kind!=="exec"&&t?.kind!=="http")return{unavailable:`plugin ${n.plugin} has no read leaf ${n.command.join(" ")}`};if(t.kind==="http"){const m=i;d=await k({registration:{name:e.name,endpoint:t.endpoint,...t.authEnv!==void 0?{authEnv:t.authEnv}:{}},...r.manifest?.baseUrl!==void 0?{baseUrl:r.manifest.baseUrl}:{},timeouts:{...r.manifest?.timeouts,requestMs:a},params:m.params,rest:m.rest,output:m.output,commandPath:[e.name,...n.command]},u,void 0,{callHeaders:l(async s=>P(e.name,o,{method:s.method,url:s.url.href,body_sha256:x(s.body),..._(s.headers)}).headers,"callHeaders")})}else{if(t.executable===void 0)return{unavailable:`plugin ${n.plugin} has no read leaf ${n.command.join(" ")}`};d=await E({plugin:e,executable:t.executable,commandPath:[e.name,...n.command],output:i.output},u,{deadlineMs:a,cwd:e.root,env:{...process.env,...w(e.name)??{}}})}}const c=d?.markdown;return typeof c=="string"?{markdown:c}:{unavailable:"read leaf returned no markdown"}}catch(e){return{unavailable:e instanceof Error?e.message:String(e)}}}l(J,"runReadLeaf");export{j as READ_LEAF_DEADLINE_MS,C as readDelegationFor,J as runReadLeaf};

package/dist/types.d.ts

@@ -60,6 +60,18 @@ export type MemoryExtensionDeclaration = BooleanMemoryExtensionDeclaration | Str
 /** Field declarations owned by one plugin manifest. The plugin's `name` is
  * the namespace; keys here are its lowercase kebab-case local field names. */
 export type MemoryExtensionDeclarations = Record<string, MemoryExtensionDeclaration>;
+/** One canvas object kind a plugin declares in `object_kinds`. */
+export interface ObjectKindDeclaration {
+    description: string;
+    events: Record<string, {
+        level: number;
+        supersedes?: boolean;
+    }>;
+    /** A leaf path of the plugin's own commands, run to render an instance as markdown. */
+    read?: {
+        command: string[];
+    };
+}
 export interface PluginManifest {
     name: string;
     version?: string;
@@ -124,6 +136,10 @@ export interface PluginManifest {
     /** App-scoped env variables required by this plugin, collected during install. */
     env?: Record<string, import('./core/plugin-env.js').PluginEnvDeclaration>;
     transport?: PluginTransport;
+    /** Canvas object kinds this plugin declares, keyed by kind name (`<plugin>.<name>`). */
+    object_kinds?: Record<string, ObjectKindDeclaration>;
+    /** Canvas scopes (`crtr:objects:<verb>:<target>`) a local plugin's app credential holds. */
+    scopes?: string[];
     /** Archive source for a crouter-materialized HTTP plugin. Distinct from the invocation transport. */
     bundle?: PluginBundle;
     /** A capability provider's `bundle.json` `provider` block, copied by the

package/docs/ci-runner.md

@@ -62,7 +62,8 @@ Isolation, per instance `~/ci-runners/crouter-N/`:
 - its own runner directory, and its own **short** work directory `/Users/Shared/ci/N` (checkout and `_temp`; override with `CI_RUNNER_WORK`). Short is a requirement: the suite binds unix sockets under `$RUNNER_TEMP/t` (the workflow sets `TMPDIR` there), and macOS refuses a socket path over 104 bytes with `listen EINVAL`. The longest test socket adds ~76 bytes, so the work dir plus `/_temp/t` must stay under ~27 (hosted runners use `/Users/runner/work/_temp/t`, 26). Do not put the work dir under the account's home;
 - its own `HOME` (`~/ci-runners/crouter-N/home`), never the account's. The suite refuses to start if `$HOME/.crouter` exists, so the account's own crouter install (`~/.crouter`, the selected runtime, `~/.local/bin/crtr`, any running `crtrd`) is neither read nor written;
 - a minimal `PATH` (Homebrew + system) that does not include the account's crtr or npm globals;
-- `hook-job-started.sh` / `hook-job-completed.sh` (`ACTIONS_RUNNER_HOOK_JOB_*`), which kill every process whose environment or command line points into that instance's directory (brokers, `crtrd`, test tmux servers, orphaned node processes) and wipe `home/.crouter*` and the work dir's `_temp`. They match only that instance's path, so one instance's cleanup cannot touch another's job or the account's processes.
+- `hook-job-started.sh` / `hook-job-completed.sh` (`ACTIONS_RUNNER_HOOK_JOB_*`), which kill every process whose environment or command line points into that instance's directory or work dir (brokers, `crtrd`, test tmux servers, orphaned node processes) and wipe `home/.crouter*` and `_temp`. They match only that instance's paths, so one instance's cleanup cannot touch another's job or the account's processes.
+- `ci-watchdog.sh`, one detached copy per instance, started by either hook (pidfile `watchdog.pid`, log `watchdog.log`; kills are logged there). The hooks are not enough on their own: cancelling a run makes the runner SIGINT, SIGTERM, then kill the step's process *tree*, and brokers, `crtrd` and tmux servers that daemonized are reparented to launchd and are outside that tree. The completed hook does run after a cancel (it did in all 77 cancelled jobs in the runners' logs) and kills what it can match by path, but it never runs when the Worker is killed hard, and it cannot see a process whose argv and environment name neither the instance dir nor the work dir (the per-job directory `/private/tmp/c.XXXXXX` is neither). The watchdog polls every 5 s and, once this instance has had no `Runner.Worker` for two polls in a row, kills every process that has `RUNNER_TEMP=<work>/_temp` in its environment, names `<work>/`, or names a per-job directory whose `.runner-temp` marker (written by `test.yml`'s "Move HOME" step) holds this instance's `<work>/_temp`, then removes those directories. It re-checks for a `Runner.Worker` before every kill pass and before removing the directories, so a job that starts mid-sweep is left alone after at most one pass; the marker and `RUNNER_TEMP` keys are per instance, and matching is by substring of a process's command line and environment, so another instance's job or the account's own processes are touched only if their command line or environment literally names this instance's work dir, `RUNNER_TEMP`, or marked per-job directory. The completed hook also runs one unconditional sweep (`ci-watchdog.sh --once --now`).
 
 The tests bind unix sockets under per-test temp dirs and tmux servers under the per-test `HOME`, with no fixed TCP ports, so instances do not collide.
 
@@ -77,6 +78,8 @@ tail -f ~/ci-runners/crouter-1/runner.log                                    # l
 gh api repos/Northlight-Systems/crouter/actions/runners --jq '.runners[]|[.name,.status,.busy]|@tsv'
 ```
 
+Updating the hooks or watchdog on the mini (no sudo needed): copy `scripts/ci-runner/{hook-job-started,hook-job-completed,ci-watchdog}.sh` to `~/ci-runner-scripts/` and to each `~/ci-runners/crouter-N/hooks/`; the next job's hook starts the watchdog (or `pkill -f ci-watchdog` to restart it). Never touch the mini's `~/Code/cli/crouter` checkout.
+
 Installing and upgrading: get a registration token (`gh api -X POST repos/Northlight-Systems/crouter/actions/runners/registration-token --jq .token`), run `RUNNER_TOKEN=… scripts/ci-runner/install.sh 3` on the mini, then run the `sudo launchctl bootstrap` lines it prints. Prerequisites on the mini: `tmux`, `uv`, `git` (Homebrew); Node comes from `actions/setup-node`.
 
 ## No double run on `main`

package/docs/plugin/deploying.md

@@ -65,6 +65,113 @@ A definition with `version: N`, or a list of definitions with one per supported
 
 A new optional flag, a new leaf, a new optional output field and changed prose are additive.
 
+## Local plugins
+
+A plugin whose endpoint is `http://localhost`, `http://*.localhost` or another loopback host is a local plugin. crtr does not start it: run the service however you like (a terminal, launchd, a container). What crtr gives a local plugin is caller context on every call, a signature that proves the call came from crtr, and a credential for acting on the canvas.
+
+### Declaring object kinds and scopes
+
+`plugin.json` (and `bundle.json`) take two optional top-level blocks:
+
+```json
+{
+  "object_kinds": {
+    "search.page": {
+      "description": "A tracked web page",
+      "events": { "changed": { "level": 5, "supersedes": true } },
+      "read": { "command": ["page", "read"] }
+    }
+  },
+  "scopes": ["crtr:objects:link:node"]
+}
+```
+
+- A kind name's first segment is the plugin name. `events` holds at most 64 entries, each with a `level` from 1 to 10 and an optional boolean `supersedes`.
+- `read.command` is a leaf path below the plugin's root command. crtr calls it with `{ "id", "name" }` to read an instance and expects a string field `markdown`.
+- Each `scopes` entry has the form `crtr:objects:<read|watch|link|write>:<user|profile:<p>|app:<x>|node>`. A scope may not name the plugin's own space (`app:<plugin>`). A provider bundle may not declare `scopes`: a cloud app gets its scopes from directory consent.
+- Install and update refuse an invalid block and leave the installed version in place. A kind another plugin already owns is refused with `kind_owned`; the plugin's other kinds still apply.
+
+### The app token
+
+crtr gives each enabled local plugin that declares `object_kinds` or `scopes`, or uses an HTTP endpoint, one credential, `crtr_app_…`, carrying the manifest's `scopes`. The plugin uses it as `Authorization: Bearer <token>` against crtrd's `/v1` API, to register instances, link a caller, publish events and read.
+
+A service fetches the token once at startup over crtrd's unix socket, with no bearer: it asks as the person who runs it, so it must run as that user.
+
+```
+GET /v1/plugins/<name>/app-token      (over the daemon socket)
+→ { "token": "crtr_app_…", "socket": "/path/to/the/daemon.sock" }
+```
+
+The answer is `404 not_found` when the plugin is not installed, not enabled, invalid, or holds no token. Fetch it again after an update, which can change the scopes, and after a `401` (uninstall or disable revokes it).
+
+crtr never sends this token to the plugin's port: not as a bearer, a header or a body field. It reaches an exec plugin as `CRTR_APP_TOKEN` and `CRTR_DAEMON_SOCKET` in the environment. Keep it in memory or in a file with mode 0600, and never log it.
+
+### `Crtr-Caller`
+
+Every HTTP call to a plugin, local or hosted, carries who made it:
+
+```
+Crtr-Caller: node=<id>; machine=<id>; profile=<id>; run=<id>
+```
+
+The fields appear in that order. A field with no value is left out, and a call with none omits the header. A service uses `node` to link the calling node to an object it owns. The value comes from crtrd's view of the caller; a manifest cannot set `Crtr-Caller`, `Crtr-Signature` or `Crtr-Request-Id`.
+
+### `Crtr-Signature`
+
+crtrd signs a call to a local plugin when the plugin holds a token and the request goes to the origin of its installed endpoint. Any other URL gets `Crtr-Caller` and no signature.
+
+```
+Crtr-Signature: v1,t=<unix seconds>,h=<signed header names>,sig=<base64url HMAC-SHA256(token, canonical)>
+```
+
+- `h` lists, lowercase, sorted and joined with `;`, every header crtr sent except `crtr-caller` and `crtr-signature`. It always includes `crtr-request-id`, a fresh UUID per call and the signature's nonce. A retry after a connection error sends the same id and the same signature.
+- `canonical` is these lines joined with `\n`, no trailing newline:
+  1. `v1`
+  2. `t`
+  3. the HTTP method, uppercase
+  4. the request path with its query string, as received
+  5. the lowercase hex sha256 of the exact body bytes (of the empty string when there is no body)
+  6. the `Crtr-Caller` value, or an empty line
+  7. `h`
+  8. the lowercase hex sha256 of `<name>:<value>\n` for each name in `h`, in order, with each value as received: leading and trailing spaces and tabs removed, which is what Node and every other HTTP parser hands the service. crtr trims a mapped header value the same way before it signs and sends, so a padded value in a command argument is delivered without its padding
+
+A service verifies a call in this order, and answers `401` when any step fails:
+
+1. Parse the header. The version must be `v1`.
+2. `|now − t| ≤ 300` seconds.
+3. `h` must include `crtr-request-id`, be sorted, and name only headers present on the request.
+4. Recompute `canonical` from the request as received and compare the MAC with a constant-time comparison.
+5. Reject a `Crtr-Request-Id` seen in the last 600 seconds, and remember this one. Do this after step 4, so a forged request cannot fill the cache.
+6. Trust only the headers named in `h`, plus `Crtr-Caller`.
+
+```ts
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+
+const sha = (data: string | Buffer) => createHash('sha256').update(data).digest('hex');
+
+export function verify(token: string, req: { method: string; target: string; body: Buffer; headers: Record<string, string> },
+                       seen: Map<string, number>, now = Date.now()): boolean {
+  const [v, t, h, sig] = (req.headers['crtr-signature'] ?? '').split(',');
+  if (v !== 'v1' || !t?.startsWith('t=') || !h?.startsWith('h=') || !sig?.startsWith('sig=')) return false;
+  const seconds = Number(t.slice(2));
+  if (!Number.isInteger(seconds) || Math.abs(now / 1000 - seconds) > 300) return false;
+  const names = h.slice(2).split(';');
+  if (!names.includes('crtr-request-id') || names.some((n, i) => req.headers[n] === undefined || (i > 0 && names[i - 1]! >= n))) return false;
+  const canonical = ['v1', String(seconds), req.method.toUpperCase(), req.target, sha(req.body),
+    req.headers['crtr-caller'] ?? '', names.join(';'), sha(names.map((n) => `${n}:${req.headers[n]}\n`).join(''))].join('\n');
+  const expected = createHmac('sha256', token).update(canonical).digest();
+  const given = Buffer.from(sig.slice(4), 'base64url');
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return false;
+  for (const [id, at] of seen) if (now - at > 600_000) seen.delete(id);
+  const id = req.headers['crtr-request-id']!;
+  if (seen.has(id)) return false;
+  seen.set(id, now);
+  return true;
+}
+```
+
+`req.headers` is keyed by lowercase name (Node's `IncomingMessage` already does this) and `req.target` is `req.url`.
+
 ## Archive response
 
 The install response is an uncompressed tar with `Content-Type: application/x-tar`. Do not configure a proxy, CDN, or framework middleware to gzip or otherwise compress it. Crtr rejects compressed archive bytes. The handler sends an ETag and supports conditional `If-None-Match` requests automatically.

package/docs/sdk/release-notes.md

@@ -7,6 +7,75 @@ description: Behavior changes in @north-light/sdk that an app must act on, newes
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 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).
+
+### Plugin manifests declare `object_kinds` and `scopes` (additive)
+
+`plugin.json` and `bundle.json` take two optional top-level blocks. `object_kinds` maps a kind name (`<plugin>.<name>`, so the first segment is the plugin's own name) to `{ description, events, read? }`: `events` holds up to 64 entries `{ level: 1-10, supersedes?: boolean }`, and `read.command` is a leaf path below the plugin's root command. That leaf must answer once: a leaf declared `rest.streaming: true` is refused as a `read.command`. `scopes` lists the canvas scopes the plugin asks for. A provider bundle may not declare `scopes`: a cloud app's scopes come from directory consent. Install, update and enable refuse an invalid block and keep the installed version; a kind another owner already holds is reported as `kind_owned` and the plugin's other kinds still apply. `crtr pkg plugin install|update|enable` print these as `warnings`, plus `appScopes` (the scopes the plugin's token now carries). Plugin authors: see [Local plugins](https://crouter.docs.northlight.ai/docs/plugin/deploying#local-plugins).
+
+`ReconcilePackagesDTO` (the answer of `POST /v1/documents/reconcile-packages`) gains two optional fields: `kinds` (`applied` with `outcome` of `inserted`, `updated` or `unchanged`; `refused` with code `kind_owned`; `invalid` plugins with the reason) and `tokens` (`granted` plugins with their scopes, and `revoked` plugin names).
+
+### Canvas object scopes `crtr:objects:<verb>:<target>` (additive)
+
+`@north-light/identity` accepts `crtr:objects:<read|watch|link|write>:<user|node|profile:<id>|app:<x>>`. Each scope is its own grant: `covers` is exact equality, so `crtr:objects:write:user` does not imply `read`. The target is where the object lives:
+
+- `user`: objects in the person's space.
+- `profile:<id>`: objects below that profile.
+- `app:<x>`: nodes and custom objects of another app `x`. An app never needs a scope for its own objects, and a plugin may not declare its own `app:<plugin>` space.
+- `node`: any node, including the stub of a node on another of the account's machines.
+
+`read` lets the holder read objects of the target, `write` change them, and `link` (below) make a node watch an object the holder owns. `watch` lets a custom object that watches an object of the target read it. Holding a scope never lifts run confinement inside the owning app, and a revoked grant holds nothing. A public custom object is readable by any app that may use the owning app's tools, with no scope. The app listener now serves the canvas operations (`objects.*`, `custom-objects.*`, `docs.*`) to an app grant token under its resolved scopes; those rows answered `unknown operation` there before.
+
+### The `crtr_app_` credential and its socket fetch (additive)
+
+Each enabled local plugin that declares `object_kinds` or `scopes`, or serves over HTTP, holds one `crtr_app_…` token carrying its manifest's `scopes`. It is issued when the plugin is installed or enabled, reissued on update (the scopes can change), and revoked on uninstall or disable. crtrd accepts it as a bearer on its unix socket and TCP listener, looks it up on every request (a revoked token stops working on the next one), and treats the holder as app `app:<plugin>`.
+
+- `GET /v1/plugins/:name/app-token` (new operation `plugins.app-token`, person and broker callers) answers `{ token, socket }`, or `404 not_found` when the plugin is not installed, enabled, valid and holding a token. A service fetches it once at startup over the socket as the user who runs it. A node whose uid is not the daemon's gets `403 forbidden`.
+- An exec plugin receives the token as `CRTR_APP_TOKEN` and the socket as `CRTR_DAEMON_SOCKET` in its leaf's environment. crtr never sends the token to a plugin's HTTP port.
+- SDK: `CrtrClient.plugins.appToken(name)` and the DTO `PluginAppTokenDTO`; route helper `routes.pluginAppToken(name)`.
+
+### `Crtr-Caller` and `Crtr-Signature` on local HTTP calls (additive)
+
+Every HTTP call to a plugin carries `Crtr-Caller: node=<id>; machine=<id>; profile=<id>; run=<id>` (fields in that order, empty ones left out, header omitted when none). Calls to a local plugin's endpoint origin also carry `Crtr-Signature: v1,t=<unix seconds>,h=<signed header names>,sig=<base64url HMAC-SHA256 keyed by the plugin's token>` plus a fresh `Crtr-Request-Id`. A manifest cannot set these three header names. Provider calls carry `Crtr-Caller` too. Plugin authors: the canonical string and a reference verifier are in [Local plugins](https://crouter.docs.northlight.ai/docs/plugin/deploying#local-plugins).
+
+crtrd signs the call; the CLI never holds the token. `POST /v1/plugins/:name/call-headers` (new operation `plugins.call-headers`, person and broker callers) takes only digests, `{ method, url, body_sha256, header_names, headers_sha256 }`, and answers `{ headers }` (`Crtr-Caller`, and `Crtr-Signature` when the URL is on the installed endpoint's origin and that endpoint is loopback). Any other URL gets `Crtr-Caller` only. An unknown or disabled plugin and a provider plugin answer `404 not_found`; malformed digests answer `400 invalid_request`. SDK: `CrtrClient.plugins.callHeaders(name, request)`, `PluginCallHeadersRequestDTO`, `PluginCallHeadersDTO`, `routes.pluginCallHeaders(name)`.
+
+### Unknown bearers are refused
+
+A bearer that crtrd does not recognize is now `401` on the TCP listener as well. A runtime with no owner token used to treat a request with a bearer it did not know as the owner; now only a request with no bearer is, and a live `crtr_app_` token is that app. `crtr_pub_` and the owner token behave as before.
+
+### `custom-objects.register` takes `privacy`, and `events` is optional (additive)
+
+`RegisterCustomObjectRequestDTO.privacy?` is `public` (the default), `friends` or `private`; setting it on an existing instance changes it and publishes `configured` with `privacy` in `changed`. `events` is now optional: omit it to create or return an instance of a kind an installed plugin declares, which leaves the kind's catalog alone. Omitting it for any other kind is still `400 invalid_request`. `kind_owned` now guards only the kind catalog: registering an instance of a plugin's kind never conflicts with it.
+
+### Publishing a plugin-declared kind has new refusals
+
+`custom-objects.publish` on an instance of a kind that an installed plugin declares (or that crossed from another machine):
+
+- `404 not_here` when this machine holds only a stub of the object. Details are `{ id, home_machine }`; ask the home machine.
+- `409 kind_inert` when the kind's plugin is no longer installed and enabled.
+- `403 forbidden` unless the caller is the kind's owning app or holds the instance's publish token.
+
+Instances of kinds an app registered itself publish as before.
+
+### Watching with `link` and `watcher_machine` (additive)
+
+`POST /v1/objects/:ref/watch` and `DELETE …/watch` take an optional `watcher` ref naming a node or a custom object. A non-person app caller can name a node as the `watcher` when the object is one it owns and it holds `crtr:objects:link:<target of the watcher>`: the node then watches the object. Any miss, whatever the cause, is `404 not_found`. `watcher_machine` (body field; query parameter on DELETE) names the machine of an account's other node as the watcher; crtrd keeps a local stand-in for that node, and an event for a node that never watched the stand-in locally still reaches the node. A `watcher_machine` that is not one of the account's machines is `404`; an unreachable directory is `503 runtime_unreachable`. Custom-object watchers behave as before.
+
+A linked node receives the object's events even when it could not read the object by its own access. crtrd keeps the linking app on the watch and checks its scope and ownership again at each publish, so a revoked scope or token stops new deliveries. Across machines, both the object's home machine and the node's machine need this release.
+
+### Reading: `kind_decl`, privacy and plugin read text (additive)
+
+`ObjectDTO` gains an optional `kind_decl` (`{ name, description, events, owner }`). The runtime fills it on the object of an `objects.read` answer and of an `objects.watch` answer when the object is an instance of a custom kind, so another machine can hold a stub of it. It grants nothing. `ObjectListItemDTO` extends `ObjectDTO`, so its type carries the field, but list and search answers do not fill it. `privacy` is the field `ObjectDTO` already had: a read answered by another machine now carries the home object's `kind_decl` and `privacy` into the reader's stub, so a stub is never more readable than its home object.
+
+A read of an instance of a plugin kind whose manifest sets `read.command` runs that leaf on the home machine (15 s deadline for exec and provider plugins alike), outside the canvas transaction, and returns its `markdown` as `text`. The `read` event and the read watch are recorded once. Access is checked again after the leaf returns, and a reader who lost it gets `not_found`; an object deleted while the leaf ran answers `state: "deleted"`, and one that vanished answers `not_found`. If the leaf cannot answer (plugin not installed or disabled, timeout, no string `markdown`), `text` is the last announcement followed by `\ncontent unavailable: <reason>`. Such a read adds `data.content`: `"live"` or `"unavailable"`. A kind that is no longer declared by an installed plugin, a kind without `read.command`, and every other object read as before, with no `data.content`.
+
+### Migrations v89–v91
+
+The canvas database gains `object_kinds.read_json`, `object_kinds.source` (`register`, `manifest` or `peer`) and `object_kinds.declared` (v89), a `peer_ingested_destinations` table recording each event destination already ingested from another machine (v90), and `watches.link_app`, the app that made a watch through `link` (v91). No app action; an older runtime cannot open a database migrated by this release.
+
 ## 0.3.483
 
 ### `unavailable`, `step` and `setupLink` on `grant.get` dependencies (additive for the SDK; a type change for exhaustive switches)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.483",
+  "version": "0.3.485",
   "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.483",
+    "@north-light/identity": "0.3.485",
     "@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/dist/index.d.ts

@@ -22,7 +22,7 @@ export interface IdTokenClaims extends JWTPayload {
     family_name?: string;
     picture?: string;
 }
-export type Scope = 'crtr:llm' | 'crtr:act' | 'crtr:schedule' | `crtr:memory:${'read' | 'rw'}:user${'' | `:${string}`}` | 'crtr:memory:manage:user' | `crtr:memory:${'read' | 'rw'}:app:${string}` | `crtr:files:${'read' | 'rw'}:${'user' | `app:${string}`}:${string}` | 'crtr:files:share' | `crtr:${'conversations' | 'objects'}:read:app:${string}` | `crtr:objects:${'message' | 'spawn'}:app:${string}` | `crtr:peer:${string}` | `${string}:${string}`;
+export type Scope = 'crtr:llm' | 'crtr:act' | 'crtr:schedule' | `crtr:memory:${'read' | 'rw'}:user${'' | `:${string}`}` | 'crtr:memory:manage:user' | `crtr:memory:${'read' | 'rw'}:app:${string}` | `crtr:files:${'read' | 'rw'}:${'user' | `app:${string}`}:${string}` | 'crtr:files:share' | `crtr:${'conversations' | 'objects'}:read:app:${string}` | `crtr:objects:${'message' | 'spawn'}:app:${string}` | `crtr:objects:${'read' | 'watch' | 'link' | 'write'}:${'user' | 'node' | `profile:${string}` | `app:${string}`}` | `crtr:peer:${string}` | `${string}:${string}`;
 /** App-memory form keys omit the app id. */
 export declare const ENFORCED: ReadonlySet<string>;
 export declare function parseScope(value: string, grantee?: string): Scope;

package/packages/crouter-identity/dist/index.js

@@ -31,8 +31,12 @@ function selector(value) {
     match = /^crtr:files:(read|rw):(user|app:[A-Za-z0-9_-]{1,64}):(.+)$/.exec(value);
     if (match && validPath(match[3], true))
         return { kind: 'files', access: match[1], holder: match[2], path: match[3] };
-    // read, message and spawn are three unrelated scopes: `covers` is exact equality for them.
-    match = /^crtr:(?:(conversations):read|(objects):(?:read|message|spawn)):app:([A-Za-z0-9_-]{1,64})$/.exec(value);
+    // Canvas object scopes `crtr:objects:<read|watch|link|write>:<user|node|profile:<p>|app:<x>>`. They, and the
+    // message and spawn scopes below, are unrelated scopes: `covers` is exact equality for every one of them.
+    match = /^crtr:objects:(?:read|watch|link|write):(?:user|node|profile:[A-Za-z0-9_-]{1,64}|app:[A-Za-z0-9_-]{1,64})$/.exec(value);
+    if (match)
+        return { kind: 'objects', value };
+    match = /^crtr:(?:(conversations):read|(objects):(?:message|spawn)):app:([A-Za-z0-9_-]{1,64})$/.exec(value);
     if (match)
         return { kind: (match[1] ?? match[2]), value };
     match = /^crtr:peer:([A-Za-z0-9_-]{1,64})$/.exec(value);

package/packages/crouter-identity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/identity",
-  "version": "0.3.483",
+  "version": "0.3.485",
   "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.483",
+  "version": "0.3.485",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.483",
+      "version": "0.3.485",
       "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.483",
+        "@north-light/identity": "0.3.485",
         "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.483",
+      "version": "0.3.485",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.483",
+      "version": "0.3.485",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.483",
+      "version": "0.3.485",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12134,20 +12134,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.483",
+      "version": "0.3.485",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.483",
-        "@north-light/identity": "0.3.483"
+        "@north-light/api": "0.3.485",
+        "@north-light/identity": "0.3.485"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.483",
+      "version": "0.3.485",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.483",
-        "@north-light/identity": "0.3.483",
+        "@north-light/api": "0.3.485",
+        "@north-light/identity": "0.3.485",
         "jose": "^6.2.1"
       },
       "bin": {