@north-light/cli 0.3.491 → 0.3.493

package/docs/sdk/release-notes.md

@@ -7,6 +7,40 @@ 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.493
+
+An app can act on a person's hosted runtime with no sign-in of theirs, and `@north-light/plugin` can declare canvas object kinds. Everything below is additive: no request or response an existing app sends or reads changes.
+
+### `oauth.appClient(userId)`: the app acts on a person's hosted runtime (additive)
+
+`await oauth.appClient('user:<id>')` returns a client on that person's hosted runtime without a stored connection or refresh token. The SDK signs a `client_credentials` request with the `OAuth2Client`'s key (`private_key_jwt`) for `sub=user:<id>`, and the directory answers a token and the person's `runtimeUrl`. The app must be registered with the `app_token_for_user` operation, and the person must hold an active grant for it. Tokens are cached per person until a minute before they expire, and one mint is in flight per person however many callers ask. The client mints again on expiry and once after a `401`. A `userId` that is not `user:<id>` throws `CrouterError`.
+
+- `NoHostedRuntimeError` (`no_hosted_runtime`, status 409, not retryable): the person has no hosted runtime to act on.
+- `NotGrantedError` (`not_granted`, status 409, not retryable): the person has no active grant for the app, so they have not signed in to it.
+- A runtime still provisioning (503), a directory 5xx and a 429 throw an error with `retryable: true`. `invalid_client` is a `401` `unauthorized` that names the signing key.
+
+`no_hosted_runtime` and `not_granted` are appended to `sdkErrorCodes`, so the codes already in the list keep their positions. `NoHostedRuntimeError` and `NotGrantedError` are exported from `@north-light/sdk`. See [Errors](/docs/errors) and [Connections](/docs/concepts/connections#acting-without-a-sign-in).
+
+### `customObjects` and `canvas` on `AppClient` (additive, type change)
+
+`AppClient` (the type of `oauth.client(userId)` and `oauth.appClient(userId)`) now offers two namespaces the app listener already served to an app grant token:
+
+- `customObjects.register`, `publish` and `unregister` act on the custom objects your app owns. `receive` and `ack` stay owner-daemon only.
+- `canvas.watch` and `canvas.unwatch` link a node to an object your app owns, under `crtr:objects:link:node`. Pass `watcher` (a node id) and, for a node of another of the account's machines, `watcher_machine`. `unwatch` takes the same `watcher` and `watcher_machine` to remove that node's watch; without `watcher` it removes the app's own watch.
+
+Every other `canvas` method and `customObjects.receive`/`ack` remain absent from the type and throw `CrouterError` if reached. `Crouter` is still assignable to `AppClient`.
+
+### `@north-light/plugin`: `objectKinds` and `LeafCaller.crtr` (additive)
+
+- `definePlugin({objectKinds})` declares canvas object kinds by name relative to the plugin (`repo`), each `{ description, events: { <name>: { level: 1-10, supersedes? } }, read?: { command: [...] } }`. The bundle the kit serves carries them in `bundle.json` `object_kinds`, keyed `<providerId>.<name>`: `providerId` is the `auth.providerId` the handler was given, else the plugin name. `definePlugin` throws `PluginDefinitionError` for a relative name that is not lowercase letters, digits and `-`, a blank description, more than 64 events, a level outside 1-10, and a `read.command` that is not a non-streaming leaf of the plugin. Building the bundle throws if the prefixed kind is not one crouter accepts (a provider id with capitals or `_`, or one of crouter's reserved roots such as `repo` or `report`).
+- `ctx.caller.crtr` carries the calling node: `{ node?, machine?, profile?, run? }`, parsed by the exported `parseCrtrCaller(header)` from the request's `Crtr-Caller`. It is absent when the header names no field. The runtime asserts that header and the bearer token does not cover it, so use it to tell which of the verified `sub`'s nodes called, never to authorize; authorize on `sub`.
+
+See [Local plugins](https://crouter.docs.northlight.ai/docs/plugin/deploying#local-plugins) and [Object kinds and the calling node](https://crouter.docs.northlight.ai/docs/plugin/deploying#object-kinds-and-the-calling-node).
+
+### `nodes.revive` reports `ready` (additive)
+
+`ReviveResultDTO` gains an optional `ready`. The daemon checks, in its own namespace, whether the revived node's `view.sock` accepts a connection (up to 10 s, ending early if the launched broker exits) and returns the answer. `true` means the node is attachable; it does not show the task was delivered or the model is making progress. `false` means no connection yet, including `outcome: 'frozen'`. A daemon that predates the field sends none, so treat an absent `ready` as unknown.
+
 ## 0.3.488
 
 ### Developer CLI: `--help` exits 0, `login` is safe to re-run (CLI only, no app change)
@@ -58,7 +92,7 @@ Plugins can now declare canvas object kinds and act on the canvas, and an app to
 - `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.
+`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. A `friends` or `private` instance is readable, with no read scope, only by a run (a node, or a node of another machine) that holds one of the owning app's provider-group scopes `<app>:<group>`, the scopes a call to that app's provider commands needs; another app's server reads it only through a held `crtr:objects:read:app:<app>` 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)
 

package/docs/sdk/resources.md

@@ -38,13 +38,13 @@ Every namespace exported by the client. Namespaces are camelCase. Verbs are `cre
 | `grant` | `get` (`wait`, `since`: hold until `version` changes) | `GET /v1/grant` |
 | `health` | `get` | `GET /v1/health` |
 
-`runs`, `uploads`, `attachments`, `shares`, `questions`, `docs` and the app side of `grant` and `providers` are the application-facing API an app reaches through the app listener; `oauth.client(userId)` returns a client typed to exactly that set (`AppClient`); `nodes`, `bash`, `canvas`, `crons`, `human`, `models`, `customObjects`, `structuredRequests`, `system`, `auth`, `files.read/write/list` and `profiles.ensure/retrieve` are the owner's own daemon and are not served to an app. An app schedules work with its own timer calling `runs.start`, or a run's agent runs `crtr cron add` under `crtr:schedule`. See [Apps on Northlight](./guides/apps-on-northlight.md) and [Apps with many users](./guides/apps-with-many-users.md). `memory` is the person's `public` documents ([Memory](./memory.md)). `docs` writes, reads and edits documents the calling app owns: `docs.write({name, body, preview, kind?, rules?})` returns the canonical `name`; `docs.get(name)` returns `body`, `revision`, `rules` and the edit `base`; `docs.edit(name, {body, rationale, base?})` changes it in place and refuses a stale `base` with `ConflictError` (`stale_revision`). To keep one document current, `get` it (catch `NotFoundError` on first run to `write`), compare `body` to your text, and `edit` only when they differ. `system.health` (`/healthz`) is the daemon's liveness check; `health.get` is the app listener's.
+`runs`, `uploads`, `attachments`, `shares`, `questions`, `docs` and the app side of `grant` and `providers` are the application-facing API an app reaches through the app listener; `oauth.client(userId)` returns a client typed to exactly that set (`AppClient`); `customObjects` (`register`, `publish`, `unregister`) and `canvas` (`watch`, `unwatch`) are served too, for the custom objects your app owns; `oauth.appClient(userId)` returns the same `AppClient` type without a stored sign-in ([Connections](../apps/concepts/connections.md#acting-without-a-sign-in)). `nodes`, `bash`, `crons`, `human`, `models`, `structuredRequests`, `system`, `auth`, the rest of `canvas` and `customObjects` (`receive`, `ack`), `files.read/write/list` and `profiles.ensure/retrieve` are the owner's own daemon and are not served to an app. An app schedules work with its own timer calling `runs.start`, or a run's agent runs `crtr cron add` under `crtr:schedule`. See [Apps on Northlight](./guides/apps-on-northlight.md) and [Apps with many users](./guides/apps-with-many-users.md). `memory` is the person's `public` documents ([Memory](./memory.md)). `docs` writes, reads and edits documents the calling app owns: `docs.write({name, body, preview, kind?, rules?})` returns the canonical `name`; `docs.get(name)` returns `body`, `revision`, `rules` and the edit `base`; `docs.edit(name, {body, rationale, base?})` changes it in place and refuses a stale `base` with `ConflictError` (`stale_revision`). To keep one document current, `get` it (catch `NotFoundError` on first run to `write`), compare `body` to your text, and `edit` only when they differ. `system.health` (`/healthz`) is the daemon's liveness check; `health.get` is the app listener's.
 
 Action methods keep the product's literal name (`fork`, `revive`, `promote`, `yield`) rather than being renamed into a generic verb. Every request-capable method takes `RequestOptions` as its final argument after its path, body, or query arguments. `RequestOptions` is `{ headers?, signal?, timeout?, maxRetries? }`; stream event options exclude `timeout` and add `after`.
 
 ## Custom objects
 
-`client.customObjects` registers an external service or script as an object on the canvas, with a declared event catalog and a queue, URL or argv receiver, and publishes its events to the objects watching it. `register(body)` returns the object and, once, its publish token; `publish(ref, body)` sends one declared event (a custom object may publish with that token alone); `receive(ref, { after?, signal? })` is an async iterator over a queue receiver's deliveries and replays every unacknowledged delivery on each connect; `ack(ref, deliveryIds)` acknowledges them; `unregister(ref)` deletes the object. The same objects are managed from a terminal with `crtr custom-object` and watched with `crtr canvas watch`.
+`client.customObjects` registers an external service or script as an object on the canvas, with a declared event catalog and a queue, URL or argv receiver, and publishes its events to the objects watching it. `register(body)` returns the object and, once, its publish token; `publish(ref, body)` sends one declared event (a custom object may publish with that token alone); `receive(ref, { after?, signal? })` is an async iterator over a queue receiver's deliveries and replays every unacknowledged delivery on each connect; `ack(ref, deliveryIds)` acknowledges them; `unregister(ref)` deletes the object. An app reaches `register`, `publish` and `unregister` on its own objects through `oauth.client(userId)` or `oauth.appClient(userId)`, and links a node to one with `client.canvas.watch(ref, { watcher, watcher_machine? })` and `client.canvas.unwatch(ref, { watcher, watcher_machine? })` under `crtr:objects:link:node` (without `watcher`, `unwatch` removes the app's own watch). The same objects are managed from a terminal with `crtr custom-object` and watched with `crtr canvas watch`.
 
 ## Files and bash
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/cli",
-  "version": "0.3.491",
+  "version": "0.3.493",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -138,7 +138,7 @@
   },
   "license": "UNLICENSED",
   "dependencies": {
-    "@north-light/identity": "0.3.491",
+    "@north-light/identity": "0.3.493",
     "@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.491",
+  "version": "0.3.493",
   "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.491",
+  "version": "0.3.493",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/cli",
-      "version": "0.3.491",
+      "version": "0.3.493",
       "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.491",
+        "@north-light/identity": "0.3.493",
         "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.491",
+      "version": "0.3.493",
       "license": "UNLICENSED"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/env-docker",
-      "version": "0.3.491",
+      "version": "0.3.493",
       "license": "UNLICENSED"
     },
     "packages/crouter-identity": {
       "name": "@north-light/identity",
-      "version": "0.3.491",
+      "version": "0.3.493",
       "license": "UNLICENSED",
       "dependencies": {
         "jose": "^6.2.1"
@@ -12134,20 +12134,20 @@
     },
     "packages/crouter-plugin": {
       "name": "@north-light/plugin",
-      "version": "0.3.491",
+      "version": "0.3.493",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.491",
-        "@north-light/identity": "0.3.491"
+        "@north-light/api": "0.3.493",
+        "@north-light/identity": "0.3.493"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/sdk",
-      "version": "0.3.491",
+      "version": "0.3.493",
       "license": "UNLICENSED",
       "dependencies": {
-        "@north-light/api": "0.3.491",
-        "@north-light/identity": "0.3.491",
+        "@north-light/api": "0.3.493",
+        "@north-light/identity": "0.3.493",
         "jose": "^6.2.1"
       },
       "bin": {