@north-light/crouter 0.3.329 → 0.3.331

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.329",
+  "version": "0.3.331",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.329",
+  "version": "0.3.331",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.329",
+      "version": "0.3.331",
       "hasInstallScript": true,
       "license": "GPL-3.0-only",
       "workspaces": [
@@ -4795,28 +4795,28 @@
     },
     "packages/crouter-api": {
       "name": "@north-light/crouter-api",
-      "version": "0.3.329",
+      "version": "0.3.331",
       "license": "GPL-3.0-only"
     },
     "packages/crouter-env-docker": {
       "name": "@north-light/crouter-env-docker",
-      "version": "0.3.329",
+      "version": "0.3.331",
       "license": "GPL-3.0-only"
     },
     "packages/crouter-plugin": {
       "name": "@north-light/crouter-plugin",
-      "version": "0.3.329",
+      "version": "0.3.331",
       "license": "GPL-3.0-only",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.329"
+        "@north-light/crouter-api": "^0.3.331"
       }
     },
     "packages/crouter-sdk": {
       "name": "@north-light/crouter-sdk",
-      "version": "0.3.329",
+      "version": "0.3.331",
       "license": "GPL-3.0-only",
       "dependencies": {
-        "@north-light/crouter-api": "^0.3.322"
+        "@north-light/crouter-api": "^0.3.331"
       }
     }
   }

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

@@ -1,16 +0,0 @@
----
-kind: knowledge
-when-and-why-to-read: When an application needs to expose operations as crtr commands over HTTP, this knowledge should be read because one typed command definition can provide the handler and install archive without a hand-written manifest drifting from the app.
-short-form: Use @north-light/crouter-plugin to expose an application's typed HTTP operations as crtr commands from one TypeScript command tree.
-surfaces:
-  - on: boot
-    at: preview
----
-
-# `@north-light/crouter-plugin`
-
-Use `@north-light/crouter-plugin` when an application should provide crtr commands through an HTTP endpoint. It generates `commands.json` and the endpoint install archive from the same typed command tree that its Fetch handler runs, so an application does not write a manifest, route table, or `plugin.json`.
-
-Read `node_modules/@north-light/crouter-plugin/README.md` after installing the package for the shortest working plugin, and https://github.com/vallum-security/crouter/tree/main/docs/plugin for parameters, outputs, errors, streaming, deployment, bundles, and memory docs. Confirm the installed package exports before writing against it; the authoring surface is `definePlugin`, `defineBranch`, `defineLeaf`, `defineStreamingLeaf`, `param`, `field`, `createFetchHandler`, `buildCommandManifest`, `buildBundle`, `LeafError`, `ManifestInvalidError`, `PluginDefinitionError`, and `kebab`.
-
-Install a deployed handler with `crtr pkg plugin install --endpoint <public-handler-url> --name <plugin-name>`. The generated REST paths include the handler's public mount path, so install the URL the handler actually serves. Crouter synthesizes `.crouter-plugin/plugin.json` for this install; the application does not author it.

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

@@ -1,90 +0,0 @@
----
-kind: knowledge
-description: Driving a crouter daemon from an application with @north-light/crouter-sdk
-when-and-why-to-read: When you are writing or reviewing application code that runs a crtr agent — installing @north-light/crouter-sdk, constructing a client, creating a node, watching its event stream, reading its result, reading or writing memory, or connecting a browser to a daemon — this reference should be read because `generate()` and `local()` were deleted, while the typed client keeps daemon transport and agent outcomes distinct.
-short-form: The ESM-only application-facing client for a crtrd daemon. Construction and transports, `client.nodes` create/wait/parse/stream, activity snapshots, phase-2 resources including files and bash, `client.memory`, the returned-not-thrown outcome union, and error classes.
-surfaces:
-  - on: boot
-    at: name
----
-
-# `@north-light/crouter-sdk`
-
-One ESM-only client an application installs to drive a crouter daemon over its `/v1` API: create agent runs, watch their event streams, wait for typed results, and reach the rest of the daemon. Resource methods issue `/v1` requests; `createAndWait`, `parse`, `stream`, and `auth.status` compose requests. crtrd stays the sole owner of canvas state. The runtime model behind the objects — nodes, the canvas, lifecycle, reports — is `internal/nodes-and-canvas`.
-
-## Check what has shipped before you write against it
-
-Streaming is shipped: `client.nodes.stream`, `client.nodes.events`, and `GET /v1/nodes/{id}/events`. Memory is shipped: `client.memory` exposes `list`, `retrieve`, `create`, `update`, `delete`, `move`, `search`, `history`, and `resolve`.
-
-The client also ships construction and transports, `client.nodes` create / retrieve / list / outcome / waitForOutcome / createAndWait / parse / message / cancel / interrupt, `nodes.reports.list`, `profiles`, `system.status`, `files.read` / `write` / `list`, the error hierarchy, and per-request options. Phase 2 also ships node lifecycle, job, worktree, and result resources; canvas and canvas history; crons; human requests and inbox; models; and `client.bash.run`.
-
-Confirm against the installed package's types rather than against any document, including this one.
-
-## The published README is stale
-
-`generate()`, `local()`, and the `Environment` interface were **deleted**, not deprecated — a hard cut with no shim. Code written from the npm README or from training data will call `generate({ prompt, schema, env: local() })` and will not compile. The replacement is `new Crouter()` plus `client.nodes.parse({ prompt, output_schema })`.
-
-## A run, end to end
-
-An agent run needs a daemon. `npm i -g @north-light/crouter` installs `crtr` and `crtrd`; `new Crouter()` starts the daemon itself on a cold socket, so nothing has to be running first.
-
-```ts
-import Crouter from '@north-light/crouter-sdk';
-import { z } from 'zod';
-
-const client = new Crouter();
-
-const run = await client.nodes.parse({
-  prompt: 'Read package.json here and report its name and version.',
-  cwd: '/path/to/repo',
-  output_schema: z.object({ name: z.string(), version: z.string() }),
-  root: true,
-  root_lifecycle: 'terminal',
-});
-```
-
-`root: true` means the run has no parent node and reports to nobody, which is what an application's run is. `root_lifecycle: 'terminal'` finishes and reaps; `'resident'` keeps the node for a person to open. Wire fields are `snake_case` and the SDK does not camelize them.
-
-## The agent's own outcome is returned, never thrown
-
-A run that refused the schema, hit its deadline, or crashed comes back as a value. Wrapping the call in `try`/`catch` and treating the catch as the failure path silently drops every agent-side outcome, because none of them throw.
-
-```ts
-if (run.kind === 'result') use(run.output_parsed);
-else if (run.reason === 'declined') handleRefusal(run.declined?.reason, run.declined?.retryable);
-else handleFailure(run.reason, run.detail);
-```
-
-A decline is `kind: 'failure'` with `reason: 'declined'` — narrow on `reason`, not on `kind`. `output_parsed` is non-null exactly when `kind === 'result'`. A Zod schema supplies its inferred output type; a Standard Schema supplies `~standard.types.output`; a JSON-Schema literal or any other `{ toJSONSchema() }` object makes it `unknown`. The SDK does not re-validate the result because the daemon already enforced the schema when the agent submitted.
-
-Exceptions are for the layer underneath: `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError`, `InternalServerError`, `APIConnectionError`, `APIConnectionTimeoutError`, `APIUserAbortError`, all extending `APIError` with `status`, `code`, `message`, `details`, `headers`. Branch on `code` — it is the stable machine-readable identity (`node_id_exists`, `daemon_unavailable`, `node_dormant`).
-
-## A retried create spawns a second agent unless you pass `node_id`
-
-`maxRetries` (default 2) covers connection errors and 429/5xx on `GET`, `HEAD`, and `DELETE`. **`POST` and `PATCH` are never retried**, because a mutation whose response was interrupted may already have been applied. A caller that wants a retry-safe create passes `node_id`: the duplicate then fails with `409 node_id_exists`, which the caller catches and turns into a `waitForOutcome` on the run that already exists.
-
-## `waitForOutcome` has no time bound
-
-It polls until the node settles, however long that takes. Bound it from one side or the other: a `deadline` on `create` makes the daemon cancel the run, a `signal` makes your client stop waiting. Aborting the signal stops the client, not the agent — `client.nodes.cancel(id)` stops the agent, `client.nodes.interrupt(id)` stops only the current turn.
-
-## Watch a run
-
-`const stream = client.nodes.stream(params, options?)` returns synchronously. `stream.node` resolves to the created node; `for await (const event of stream)` and `stream.on(type, listener)` receive the same typed events; `await stream.finalOutcome()` resolves from `node.settled`; and `stream.abort()` disconnects the observer without stopping the node. `client.nodes.events(id, options?)` watches an existing node; its options add `after` and omit request `timeout`. A `stream_gap` error event is followed by continuation; `stream_dropped` and `stream_error` reject `finalOutcome()`.
-
-`followActivity(stream, { describe? })` converts tool-call events into immutable `ActivityStep[]` snapshots. `describeToolDefault` names common tools. A custom `describe(tool, summary)` returns a label or `null` to hide the call; `summary` states only the argument shape, never values, raw arguments, or tool output.
-
-## Reaching a daemon that is not on this machine
-
-`new Crouter()` uses the owner's unix socket, which authenticates by filesystem permission. A browser has no unix sockets and a remote process has no access to that one, so both use the TCP listener with a bearer token: `new Crouter({ baseURL, token })`.
-
-The listener is off until someone runs `crtr sys connect` on the daemon's machine, which stores the address and token and hands the daemon over to a successor that boots with it on, then prints both to paste into the application. The token is the owner credential — whoever holds it reaches the whole surface. Cross-origin calls work only when a token is set; an unauthenticated listener stays same-origin so that no page the user happens to visit can drive their daemon. A page served over HTTPS calling `http://localhost:<port>` also needs Chrome's Local Network Access permission, which the browser prompts for once per site and which requires no response header.
-
-`baseURL` and `socketPath` are mutually exclusive — passing both throws `TypeError` at construction. Options fall back to `CRTR_BASE_URL`, `CRTR_SOCKET`, `CRTR_HOME`, and `CRTRD_TOKEN`, read once at construction.
-
-## Reaching a route the SDK does not wrap
-
-`client.request(method, path, body?, options?)` carries the same authentication, retry policy, and error mapping as every generated method. Some routes are deliberately outside the typed surface — tmux focuses, a node's own inbox mail claim, local attach, and the broker's control plane — because an external caller invoking them either cannot use the result or becomes a second writer to state the broker and daemon coordinate between themselves.
-
-## The full reference
-
-Page-per-topic detail — the complete create-parameter table, streaming event table, memory scope object, resource map, and migration table — lives in the crouter repository under `docs/sdk/`, published at <https://github.com/vallum-security/crouter/tree/main/docs/sdk>.