@north-light/crouter 0.3.331 → 0.3.332

package/dist/builtin-memory/crouter-plugin/README.md

@@ -1,11 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need Authoring crtr HTTP plugins, this knowledge
-  should be read because `@north-light/crouter-plugin` turns one TypeScript
-  command tree into both a Fetch handler and the archive accepted by `crtr pkg
-  plugin install --endpoint`. Use it when an application should expose typed
-  operations as native `crtr` commands without maintaining `commands.json` or a
-  separate HTTP route definition.
+when-and-why-to-read: When you need Plugin overview, this knowledge should be
+  read because Expose application operations as native crtr commands with a
+  typed HTTP plugin.
 ---
 
 # Authoring crtr HTTP plugins

package/dist/builtin-memory/crouter-plugin/bundles-and-memory.md

@@ -1,10 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Bundles and memory docs, this knowledge
-  should be read because `createFetchHandler` builds and serves the install
-  archive automatically. Use `buildBundle` when you need to inspect or save the
-  generated bytes during an application build. Pass the same mount path where
-  the handler is served.
+  should be read because Generate install archives and include agent-facing
+  memory documents in a plugin.
 ---
 
 # Bundles and memory docs

package/dist/builtin-memory/crouter-plugin/commands.md

@@ -1,11 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: "When you need Commands, this knowledge should be read
-  because `definePlugin` declares the top-level crtr command. `name` must be
-  lowercase kebab case. `description`, `whenToUse`, and `summary` are required
-  text for the plugin, every branch, and every leaf. Write them for an agent
-  choosing a command: describe the concrete object or action, state when the
-  command applies, and state the short outcome."
+when-and-why-to-read: When you need Commands, this knowledge should be read
+  because Define plugin command trees, branches, leaves, and agent-facing
+  descriptions.
 ---
 
 # Commands

package/dist/builtin-memory/crouter-plugin/deploying.md

@@ -1,11 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: "When you need Deployment, this knowledge should be read
-  because `createFetchHandler(plugin, options)` returns `(request: Request) =>
-  Promise<Response>`. Use it directly in Cloudflare Workers, Bun, Deno, and any
-  framework route that accepts Fetch `Request` and `Response` objects. A
-  framework with different request types needs only an adapter at its boundary;
-  the package itself has no framework dependency."
+when-and-why-to-read: When you need Deployment, this knowledge should be read
+  because Serve plugin Fetch handlers with authentication, mount paths, and
+  archive compression.
 ---
 
 # Deployment

package/dist/builtin-memory/crouter-plugin/errors.md

@@ -1,11 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Errors and streaming, this knowledge should
-  be read because Throw `LeafError` when an expected application error should be
-  reported to crtr. Its `code` must be lowercase snake case and cannot be
-  `internal`, `unknown_path`, `command_collision`, or `cli_protocol_error`.
-  `status` defaults to `400` and must be an integer from `400` through `599`.
-  Use `field`, `next`, and `received` when they make the fix clearer.
+  be read because Report expected application errors and return NDJSON streams
+  from command leaves.
 ---
 
 # Errors and streaming

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

@@ -1,11 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Getting started, this knowledge should be
-  read because Install `@north-light/crouter-plugin`, copy the complete
-  TypeScript file in the `node_modules/@north-light/crouter-plugin/README.md`,
-  and deploy its default export at the URL crtr will reach. The application must
-  provide `ACME_CRTR_TOKEN` to its handler and the machine running crtr must
-  provide the same value.
+  read because Install the plugin package, deploy a Fetch handler, and install
+  its commands in crtr.
 ---
 
 # Getting started

package/dist/builtin-memory/crouter-plugin/output.md

@@ -1,9 +1,7 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Output fields, this knowledge should be read
-  because Each leaf declares an `output` object. Field object keys are returned
-  verbatim in the result object, so `appId` stays `appId`; unlike command and
-  parameter keys, output keys are not converted to kebab case.
+  because Declare typed output fields and validate handler results.
 ---
 
 # Output fields

package/dist/builtin-memory/crouter-plugin/parameters.md

@@ -1,9 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: "When you need Parameters and handler input, this
-  knowledge should be read because Parameter object keys become handler input
-  keys. The generated manifest uses their kebab-case form: `appId` becomes
-  `app-id`, while the handler receives `input.appId`."
+when-and-why-to-read: When you need Parameters and handler input, this knowledge
+  should be read because Declare command parameters and infer their handler
+  input types.
 ---
 
 # Parameters and handler input

package/dist/builtin-memory/crouter-sdk/README.md

@@ -1,9 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: "When you need `@north-light/crouter-sdk`, this knowledge
-  should be read because The ESM-only client an application installs to drive a
-  crouter daemon: create agent runs, watch streamed events, wait for typed
-  results, read and write memory, and reach the rest of the daemon's `/v1` API."
+when-and-why-to-read: When you need SDK overview, this knowledge should be read
+  because Drive a crouter daemon from a Node or browser application with the
+  typed SDK.
 ---
 
 # `@north-light/crouter-sdk`

package/dist/builtin-memory/crouter-sdk/bash.md

@@ -1,8 +1,7 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need `client.bash`, this knowledge should be read
-  because `client.bash.run` executes one bounded `bash -c` command through the
-  daemon.
+when-and-why-to-read: When you need Bash, this knowledge should be read because
+  Execute bounded shell commands through the daemon.
 ---
 
 # `client.bash`

package/dist/builtin-memory/crouter-sdk/client.md

@@ -1,9 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Client construction, this knowledge should
-  be read because `Crouter` is the default export and the only class an
-  application constructs. `CrtrClient` from `@north-light/crouter-api` is an
-  implementation detail and is not re-exported.
+  be read because Configure local socket and remote HTTP connections,
+  authentication, and request options.
 ---
 
 # Client construction
@@ -24,7 +23,7 @@ const customSocketClient = new Crouter({ socketPath: '/custom/path/crtrd.sock' }
 |---|---|---|---|
 | `baseURL` | `string` | `CRTR_BASE_URL`, else unset | `http(s)://host:port` of a daemon TCP listener. |
 | `socketPath` | `string` | `CRTR_SOCKET`, else `${CRTR_HOME}/crtrd.sock`, else `~/.crouter/canvas/crtrd.sock` | Unix socket. Node only; throws in a browser. |
-| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
+| `token` | `string` | `CRTRD_TOKEN` | Sent as `Authorization: Bearer <token>`. The owner token or a scoped token from `crtr sys connect`; a scoped token's ceiling is enforced per request (see [[crouter-sdk/getting-started]]). Ignored by a unix-socket daemon, which authenticates by filesystem permission. |
 | `timeout` | `number` (ms) | `30_000` | Per-request wall clock. Does not apply to a stream. |
 | `maxRetries` | `number` | `2` | Transient-failure retries. Never applied to `POST` or `PATCH` — see [[crouter-sdk/errors]]. |
 | `defaultHeaders` | `Record<string, string>` | `{}` | Merged into every request. |

package/dist/builtin-memory/crouter-sdk/docker.md

@@ -1,10 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Docker environment, this knowledge should be
-  read because `@north-light/crouter-env-docker` runs a crouter daemon in a
-  container and tells you how to reach it. It is a separate package because
-  container lifecycle is real work the SDK does not otherwise do — and it **has
-  no dependencies**, including on the SDK itself.
+  read because Run a crouter daemon in a container with the separate Docker
+  environment package.
 ---
 
 # Docker environment

package/dist/builtin-memory/crouter-sdk/errors.md

@@ -1,10 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Errors, this knowledge should be read
-  because **An agent's own outcome is returned, never thrown.** A run that
-  declined the schema, hit its deadline, or crashed comes back as a settled
-  `NodeOutcome` from `waitForOutcome`, `createAndWait`, or `parse`. Narrow on it
-  — see [[crouter-sdk/nodes]].
+  because Handle API and connection errors separately from settled agent
+  outcomes.
 ---
 
 # Errors
@@ -59,6 +57,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/dist/builtin-memory/crouter-sdk/files.md

@@ -1,8 +1,7 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need `client.files`, this knowledge should be
-  read because `client.files` reads, writes, and lists host files through the
-  daemon.
+when-and-why-to-read: When you need Files, this knowledge should be read because
+  Read, write, and list host files through the daemon.
 ---
 
 # `client.files`

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

@@ -1,10 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: "When you need Getting started, this knowledge should be
-  read because An agent run needs a crouter daemon (`crtrd`) to run it. The SDK
-  is a client for that daemon — it never runs an agent itself. There are two
-  ways to reach one: the unix socket on the machine you are running on, or a TCP
-  listener with a bearer token."
+when-and-why-to-read: When you need Getting started, this knowledge should be
+  read because Connect to a local or remote daemon and run your first agent with
+  the SDK.
 ---
 
 # Getting started
@@ -53,7 +51,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
 
@@ -72,6 +70,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.
@@ -162,6 +174,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: [[crouter-sdk/client]]
 - Checking the daemon connection and selected provider before a run: `client.auth.status()` above
 - The full create-parameter table and the outcome union: [[crouter-sdk/nodes]]

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

@@ -1,9 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need `client.memory`, this knowledge should be
-  read because 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.
+when-and-why-to-read: When you need Memory, this knowledge should be read
+  because Read and write memory documents with an explicit target for every
+  request.
 ---
 
 # `client.memory`

package/dist/builtin-memory/crouter-sdk/migration.md

@@ -1,11 +1,7 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need Migration from `generate()` and `local()`,
-  this knowledge should be read because **This is a hard cut.** `generate()`,
-  `local()`, and the `Environment` interface are deleted in the same release
-  that adds `Crouter`. There is no coexistence period, no deprecated re-export,
-  and no compatibility shim. Both packages are pre-1.0 and the callers are
-  countable.
+when-and-why-to-read: When you need Migration, this knowledge should be read
+  because Replace the removed generate and local APIs with the Crouter client.
 ---
 
 # Migration from `generate()` and `local()`

package/dist/builtin-memory/crouter-sdk/nodes.md

@@ -1,7 +1,7 @@
 ---
 kind: knowledge
-when-and-why-to-read: When you need `client.nodes`, this knowledge should be
-  read because Shipped, except where a row says otherwise.
+when-and-why-to-read: When you need Nodes, this knowledge should be read because
+  Create agent runs, wait for outcomes, and parse structured results.
 ---
 
 # `client.nodes`
@@ -64,7 +64,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 [[crouter-sdk/getting-started]]. |
 | `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/dist/builtin-memory/crouter-sdk/resources.md

@@ -1,10 +1,8 @@
 ---
 kind: knowledge
 when-and-why-to-read: When you need Resource map, this knowledge should be read
-  because 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.
+  because Find client namespaces, their daemon routes, and the raw request
+  escape hatch.
 ---
 
 # Resource map

package/dist/builtin-memory/crouter-sdk/streaming.md

@@ -1,9 +1,8 @@
 ---
 kind: knowledge
-when-and-why-to-read: "When you need Streaming, this knowledge should be read
-  because 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."
+when-and-why-to-read: When you need Streaming, this knowledge should be read
+  because Follow assistant text, tool activity, reports, and outcomes as an
+  agent runs.
 ---
 
 # Streaming