@north-light/crouter 0.3.331 → 0.3.333

package/docs/sdk/errors.md

@@ -1,3 +1,8 @@
+---
+title: Errors
+description: Handle API and connection errors separately from settled agent outcomes.
+---
+
 # Errors
 
 ## What throws and what does not
@@ -50,6 +55,13 @@ The subclasses add **no fields**. `status` and `code` on the base class already
 
 The SDK validates path-segment identifiers before it makes a request. Invalid node ids, cron ids, bash-job ids, human-request ids, inbox ticket ids, provider names, and profile names throw `TypeError` locally. Node ids apply to core node calls, lifecycle calls, and nested node resources. `nodes.events()` returns a `NodeStream` synchronously, so its invalid-id `TypeError` rejects `stream.node`, `stream.finalOutcome()`, and iteration instead. File paths are not identifiers; invalid or relative file paths reach the daemon and return its mapped API error. `nodes.outcome(id, { wait })` separately throws `RangeError` when `wait` is not an integer from 0 through 25.
 
+## Scoped tokens
+
+| Condition | Class, status, and code |
+|---|---|
+| The bearer token's ceiling lacks the scope a route needs, or `nodes.create` asks for `scopes` outside it (`details.scopes` lists them) | `PermissionDeniedError`, 403 `scope_denied` |
+| A scoped token reaches an owner-only route (daemon restart, attach, broker internals, canvas prune, profile pause/resume/delete, model credential install) | `PermissionDeniedError`, 403 `owner_only` |
+
 ## Memory requests
 
 | Condition | Class, status, and code |

package/docs/sdk/files.md

@@ -1,3 +1,8 @@
+---
+title: Files
+description: Read, write, and list host files through the daemon.
+---
+
 # `client.files`
 
 `client.files` reads, writes, and lists host files through the daemon.

package/docs/sdk/getting-started.md

@@ -1,3 +1,8 @@
+---
+title: Getting started
+description: Connect to a local or remote daemon and run your first agent with the SDK.
+---
+
 # Getting started
 
 Phase 1.
@@ -44,7 +49,7 @@ if (outcome.kind === 'result') console.log(outcome.final_report_path);
 
 ## 4. A browser or a remote application
 
-A process that is not on the daemon's machine — or a page in a browser, which has no unix sockets at all — reaches the daemon over TCP with a bearer token. The token is the owner credential: whoever holds it can drive the whole surface.
+A process that is not on the daemon's machine — or a page in a browser, which has no unix sockets at all — reaches the daemon over TCP with a bearer token. There are two kinds. The **owner token** is the owner credential: whoever holds it can drive the whole surface. A **scoped token** (`crtr sys connect --scopes`) carries a list of scopes that caps what its holder and every run it creates may do.
 
 ### Turn the listener on, once
 
@@ -63,6 +68,20 @@ $ crtr --json sys connect
 {"base_url":"http://127.0.0.1:8787","token":"<64-character bearer token>"}
 ```
 
+### A token that holds less than the owner
+
+```bash
+crtr sys connect --scopes ask,memory:read
+```
+
+This mints a new token 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 run needs `act`; creating a review or human request needs `ask`; arming or running a cron needs `schedule`; memory reads and writes need `memory:read` and `memory:write`. `bash` and `files` also need `act`: they run code and touch the host directly, which is more than any run does, and `files:<dir>` is recorded, not enforced, so it cannot narrow them.
+- `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.
+
+What a scope does **not** do on a developer's machine: there is no OS sandbox. Scopes gate the daemon and the CLI; a run's own bash tool is ungated, and the daemon identifies a calling node by a field the caller declares, so a scope check bounds a well-behaved agent, not a hostile one. `llm`, `files:<dir>`, `net`, and provider scopes are recorded on the run but not enforced. There is no list or revoke verb yet; to retire a scoped token, remove it from the 0600 user secrets store and restart the daemon.
+
 ### Check setup before generating
 
 Construct the client from the application's saved connection. On the first visit that value is absent, and `client.auth.status()` returns `'connect'` without a request. Once the user pastes the base URL and token printed by `crtr sys connect`, construct it again and call `status()` to check the selected provider.
@@ -153,6 +172,7 @@ An outcome is returned, never thrown — including a decline and a failure. Only
 
 ## Where to go next
 
+- A complete local page that demonstrates streaming, structured output, and a plugin: [localhost SDK demo](../../examples/localhost-demo)
 - Every constructor option and environment-variable fallback: [Client construction](./client.md)
 - Checking the daemon connection and selected provider before a run: `client.auth.status()` above
 - The full create-parameter table and the outcome union: [Nodes](./nodes.md)

package/docs/sdk/memory.md

@@ -1,3 +1,8 @@
+---
+title: Memory
+description: Read and write memory documents with an explicit target for every request.
+---
+
 # `client.memory`
 
 Phase 3. `client.memory` reads and writes the memory documents that shape an agent run. Every call names its target; the daemon never uses its own working directory or environment to select memory.

package/docs/sdk/migration.md

@@ -1,3 +1,8 @@
+---
+title: Migration
+description: Replace the removed generate and local APIs with the Crouter client.
+---
+
 # Migration from `generate()` and `local()`
 
 Phase 1.

package/docs/sdk/nodes.md

@@ -1,3 +1,8 @@
+---
+title: Nodes
+description: Create agent runs, wait for outcomes, and parse structured results.
+---
+
 # `client.nodes`
 
 Shipped, except where a row says otherwise.
@@ -58,7 +63,7 @@ Wire fields are `snake_case`. Every `NodeCreateParams` property is optional; `pa
 | `description` | `string` | Display description. |
 | `parent` | node id | Graph placement. An external caller leaves this unset. |
 | `creator` | node id | Graph placement. An external caller leaves this unset. |
-| `scopes` | `string[]` | Per-run allow-list. Omit it to inherit every scope. In beta, `ask`, `act`, `schedule`, `memory:read`, and `memory:write` are enforced; `llm`, `files:<dir>`, `net`, provider groups, and peers are recorded because their performers are not available. |
+| `scopes` | `string[]` | Per-run allow-list. Omit it to inherit every scope, or under a scoped token to receive that token's ceiling; a list outside the ceiling answers `403 scope_denied` with the offending scopes in `details.scopes`. In beta, `ask`, `act`, `schedule`, `memory:read`, and `memory:write` are enforced; `llm`, `files:<dir>`, `net`, provider groups, and peers are recorded because their performers are not available. See [scoped tokens](./getting-started.md#a-token-that-holds-less-than-the-owner). |
 | `worktree` | `string \| boolean` | Create a managed git worktree for the run. |
 | `fork_from` | `string` | Start from an existing conversation. |
 | `no_kickoff` | `boolean` | Create the node without sending the first message. |

package/docs/sdk/resources.md

@@ -1,3 +1,8 @@
+---
+title: Resource map
+description: Find client namespaces, their daemon routes, and the raw request escape hatch.
+---
+
 # Resource map
 
 Every namespace exported by the client. Namespaces are camelCase. Verbs are `create`, `retrieve`, `list`, `update`, `delete`, and `cancel`, except where the product already has a literal name for the action (`fork`, `revive`, `promote`, `pause`, `poke`) — in which case the SDK uses that name.

package/docs/sdk/streaming.md

@@ -1,3 +1,8 @@
+---
+title: Streaming
+description: Follow assistant text, tool activity, reports, and outcomes as an agent runs.
+---
+
 # Streaming
 
 Watch a run as it works: assistant text as it is produced, tool calls as they start and finish, reports as they are pushed, and the settled outcome.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.331",
+  "version": "0.3.333",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "workspaces": [
-    "packages/*"
+    "packages/*",
+    "apps/*"
   ],
   "bin": {
     "crtr": "bin/crtr",
@@ -101,9 +102,9 @@
     "test:all": "npm test && npm run test:integration && npm run test:seam"
   },
   "overrides": {
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-agent-core": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0"
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-agent-core": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1"
   },
   "repository": {
     "type": "git",
@@ -114,10 +115,10 @@
   },
   "license": "GPL-3.0-only",
   "dependencies": {
-    "@earendil-works/pi-agent-core": "0.87.0",
-    "@earendil-works/pi-ai": "0.87.0",
-    "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0",
+    "@earendil-works/pi-agent-core": "0.87.1",
+    "@earendil-works/pi-ai": "0.87.1",
+    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-tui": "0.87.1",
     "cron-parser": "^5.6.0",
     "esbuild": "^0.27.7",
     "proper-lockfile": "4.1.2",