@north-light/crouter 0.3.154

package/docs/compat/hearth-crtr-v5.md

@@ -0,0 +1,175 @@
+# Hearth ↔ crtr runtime compatibility — v5
+
+A versioned contract for any external product (originally: `@crouton-kit/hearth`) that runs alongside a crtr install as a separate process/repo and needs a stable surface to pin a crtr package version against. "v5" names the shape described here; a future breaking change to any part of this contract gets a new compatibility document rather than silently rewriting this one.
+
+## Status and migration from v4
+
+v5 is a breaking hard cut of broker singleton control. A client's role is fixed by its `hello`: `observer` is read-only and `controller` is writable. Multiple controller-role clients are independently writable; no client owns a singleton controller slot, and opening, focusing, backgrounding, or disconnecting another client does not change an existing client's role. `request_control`, `release_control`, and `control_changed` do not exist in the current broker protocol.
+
+The observer `hello` remains valid for the `reload_auth` subset. Its `welcome` frame omits `controller_id`; `role` is the complete per-client authority statement. Sections 1–4 and 6 are unchanged from v4 and are reproduced below so this document remains a complete compatibility snapshot. Section 5 records the current broker handshake and `reload_auth` contract. The historical v4 document remains unchanged.
+
+## 1. Import contract
+
+See `docs/public-api.md` for the full picture. The subset this note assumes:
+`general`, `nowIso`, and `BROKER_READ_CAPS`, all imported from the package
+root (`@north-light/crouter`). No subpath beyond `.`, `./cli`, `./web` exists
+or is supported.
+
+## 2. `crtr --json sys version`
+
+Read-only. Returns an object with at minimum:
+
+```json
+{ "version": "0.3.40" }
+```
+
+`version` is a required string, a semver matching `package.json#version` of
+the installed crtr. A consumer asserting a running crtr's version (e.g. after
+a guest image roll) should exec this command in-guest and compare the
+returned `version` against the expected target — do not parse `--help` output
+or read `package.json` directly, since the installed layout is not a public
+contract.
+
+## 3. `crtr --json node message send` — immediate delivery
+
+This leaf delivers an inbox message immediately. Future delivery, deadline waits (`node wait deadline`), and fresh revivals (`node lifecycle revive` for the immediate case) all have separate command paths and are outside this compatibility contract; deferred future delivery and deferred revival are arranged through `crtr cron add` rather than a dedicated leaf (see "Status and migration from v3" above). Typed-output requests (`node message request`) are likewise outside this contract.
+
+**Invocation:**
+
+```
+<body on stdin> | crtr --json node message send --to <node-id> [--tier critical|urgent|normal|deferred]
+```
+
+- `body` — the message text, passed on stdin (or positional).
+- `--to <node-id>` — required target (a real node id; `--self` is not
+  applicable to an external caller).
+- `--tier` — optional, one of `critical | urgent | normal | deferred`.
+  Defaults to `normal` when omitted. Governs how the message is presented at
+  the target's next turn, not delivery timing.
+
+**Output** (JSON object, `outputKind: object`):
+
+| field | type | when present |
+|---|---|---|
+| `target` | string | always — the target node id |
+| `delivered` | boolean | always — `true` once the inbox entry is appended |
+| `revived` | boolean | always — whether delivery revived a dormant target |
+| `guidance` | string | always — human/agent-readable confirmation text |
+
+**Delivery semantics — read carefully:** this appends an entry to the
+target's `inbox.jsonl` and, if the target is dormant, makes a **best-effort**
+attempt to revive it so the message is acted on. Revival is asynchronous —
+the command returning `delivered: true` means the inbox write succeeded, not
+that the target has processed the message or is now running. A caller must
+not block synchronously waiting for a revive to complete as part of this
+call; if a caller needs to know the target acted on the message, that is a
+separate, out-of-band observation (e.g. polling node status or waiting for
+the target to message back), not a guarantee `node message send` makes.
+
+## 4. In-guest web port
+
+`crtr surface web serve --host 127.0.0.1 --port <PRIVATE>` starts crtr's
+unified web server (shell SPA, source/command bridge, SSE change lane, and
+the browser⇄broker relay) bound to loopback on a private port chosen by the
+guest. This is a **private, unauthenticated-by-default loopback surface** —
+binding a non-loopback host requires `--token`; a consumer that fronts this
+port (reverse-proxying non-model-auth or non-product traffic to it) is
+responsible for whatever auth gate sits in front of the public listener. crtr
+itself makes no claim about what proxies to this port or how; it only
+guarantees the port serves the crtr web UI when bound.
+
+## 5. Broker `view.sock` — the `reload_auth` subset
+
+A minimal, dependency-free client can nudge a live broker to re-read credentials after an external auth flow completes (e.g. a login page that just wrote fresh OAuth tokens to disk) without importing crtr's `ViewSocketClient` or any frame type. This is a v5-stable subset of the full broker wire protocol (`src/core/runtime/broker-protocol.ts`).
+
+### 5.1 Socket path resolution
+
+- Always `<CRTR_HOME>/nodes/<nodeId>/view.sock` (`CRTR_HOME` defaults to
+  `~/.crouter/canvas`). `CRTR_SOCK_DIR` is not read.
+
+### 5.2 Framing
+
+Newline-delimited JSON. Each frame is one JSON object serialized on a single
+line, terminated by `\n`. Write frames to the socket in this form; read
+replies the same way (buffer until a `\n`, then `JSON.parse` the line).
+
+### 5.3 Handshake — `hello`
+
+On connect, send:
+
+```json
+{"type":"hello","role":"observer","client_id":"<any string>"}
+```
+
+`role: "observer"` remains sufficient for this subset — `reload_auth` is open to an observer because it is an idempotent local credential re-read that does not steer the conversation. The broker replies with a `welcome` frame:
+
+```json
+{"type":"welcome","snapshot":{...},"role":"observer",...}
+```
+
+The `welcome` frame omits `controller_id`. The role is fixed by the role sent in `hello`: an observer is read-only and a controller is writable. Multiple controller-role clients may write independently; there is no singleton controller owner or handoff.
+
+**The `welcome.snapshot` can carry the full message/session history and may
+be many megabytes** — the read side is capped generously (`CLIENT_READ_CAPS`:
+256 MiB per frame and per total buffer), not tightly. A `reload_auth`-only
+client must tolerate this frame arriving and either parse-and-discard it or
+skip it structurally (it is still one JSON line — read and drop it) rather
+than assuming the first frame is small.
+
+### 5.4 The nudge — `reload_auth`
+
+Send:
+
+```json
+{"type":"reload_auth"}
+```
+
+No other fields. The broker re-reads on-disk auth storage and refreshes its
+model registry in response.
+
+### 5.5 The reply — `ack`
+
+```json
+{"type":"ack","for":"reload_auth","ok":true}
+```
+
+- `for` echoes the frame type that was acted on.
+- `ok: true` on success. On failure the broker may instead send an `error`
+  frame (`{"type":"error","code":"...","message":"..."}`). A minimal client
+  must read frames until it receives either `{"type":"ack","for":"reload_auth",...}` or `{"type":"error",...}` and IGNORE any non-terminal frames sent in between (notably: `model_changed` broadcasts after the ack). Only the explicit ack or error frame determines the result.
+
+### 5.6 What this subset intentionally omits
+
+No other frame type in this protocol (prompt/steer, session control, model selection, read-op pickers, bash execution, etc.) is part of this v5 note. In particular, `request_control`, `release_control`, and `control_changed` do not exist. A consumer that needs more than the `reload_auth` nudge should import `ViewSocketClient` from the package root rather than hand-rolling a larger client against this doc.
+
+## 6. `canvas.db` byte-shape — version 1
+
+**Read/compat constraint only — never a write contract.** crtr's CLI and
+runtime primitives (`spawnChild`, `reviveNode`, `node message send`, etc.) are the only
+sanctioned way to mutate canvas state. Documenting the byte-shape below is
+for a consumer that needs to *read* or *reason about* the database (e.g.
+recovering a home's identity after a guest recreate), not for direct SQL
+writes.
+
+- Opened with Node's built-in `node:sqlite` `DatabaseSync`.
+- WAL mode enabled by `openDb()`.
+- Forward-only migrations gated by `PRAGMA user_version`, currently through
+  **v12**. A consumer pinning this contract should treat `user_version` as
+  the schema version to check, not assume a fixed column set never changes
+  going forward — this note describes the shape AS OF v12 and will need a later compatibility document if the schema changes in a way external readers depend on.
+- **`nodes` table** — identity columns (`id`, and the fields mirrored from
+  each node's `meta.json`) are derived from `nodes/<id>/meta.json` on disk;
+  runtime columns (status, lifecycle, etc.) are row-authoritative *while the
+  local canvas.db exists*, but are **not recoverable from a wiped local DB**
+  — a rebuild re-derives identity from meta.json but cannot resurrect
+  transient runtime state that only ever lived in the row.
+- **`subscribes_to`** — DB-authoritative edge table (the push/subscription
+  spine). Not derived from any on-disk file; a wiped DB loses these edges.
+- **`spawned_by`** — provenance/audit edges, **re-derived from each node's
+  `meta.json` during a rebuild** (unlike `subscribes_to`, this one survives a
+  DB wipe as long as the node directories/meta.json files survive).
+- **Auxiliary tables**: `focuses`, `crons`, `cron_runs`, `canvas_meta`.
+
+A consumer pinning this contract should re-verify §6 against a live crtr
+install (`PRAGMA user_version`, `.schema`) whenever bumping its pinned crtr
+version, rather than assuming this note tracks every schema change.

package/docs/public-api.md

@@ -0,0 +1,77 @@
+# `@north-light/crouter` public API
+
+This is a pointer document, not a second source of truth. The canonical
+surface is `package.json#exports` plus the two source barrels it points at —
+read this file to know WHERE to look, not to get a duplicated symbol list that
+can drift.
+
+## Supported import surfaces
+
+`package.json#exports` gates the package to exactly three subpaths. Nothing
+else resolves — deep imports into `dist/` or `src/` are unsupported and will
+break without notice across versions.
+
+| Import specifier | Source barrel | Purpose |
+|---|---|---|
+| `@north-light/crouter` | `src/index.ts` → `dist/index.js` | The one sanctioned library surface: runtime control (`spawnChild`, `reviveNode`, `closeNode`, `appendInbox`), canvas reads (`getNode`, `listNodes`, `nodeDir`, `asksForNodes`, `readTelemetry`, …), the broker socket client (`ViewSocketClient`), the broker wire protocol (frame types + codec), and a small set of side-effect-free utilities (see below). |
+| `@north-light/crouter/cli` | `src/cli.ts` → `dist/cli.js` | The `crtr` CLI entrypoint. Not a library API — invoked as a program, not imported for its exports. |
+| `@north-light/crouter/web` | `src/web/index.ts` → `dist/web/index.js` | The dual-target view framework (`ViewPane`, `useViewCore`, `createViewStore`, `ViewChrome`, the four-state vocabulary) that a crtr *view* (`web.jsx`) imports to compose into the web shell. Unrelated to consuming crtr as a runtime library. |
+
+Both barrels declare no load-time side effects and no circular imports —
+importing either is safe to do speculatively.
+
+## Root-barrel surface, by area
+
+Read `src/index.ts` for the exact current export list (it is short and
+comment-organized); this table is the map, not the inventory:
+
+- **Runtime control** — `spawnChild`, `reviveNode`, `closeNode`,
+  `appendInbox`, `appendSituationalContext` (+ their result/opts types).
+  `reviveNode` is the only sanctioned launcher of a node's broker engine; do
+  not construct a broker process out-of-band. `appendSituationalContext`
+  upserts a node's hidden ambient "current situation" text without exposing
+  the underlying storage file.
+- **Canvas reads** — `getNode`, `listNodes`, `nodeDir`, `asksForNodes`,
+  `asksAcrossCanvas`, `readTelemetry`, `readContextTokens` (+ their types).
+  Read-only queries against the canvas.db-backed node graph.
+- **Broker client** — `ViewSocketClient`, `BrokerUnavailableError`. A typed
+  client for a node's `view.sock` (see `docs/compat/hearth-crtr-v5.md` for
+  the socket path resolution and a minimal-subset alternative that avoids
+  depending on this class).
+- **Broker wire protocol** — `encodeFrame`, `FrameDecoder`,
+  `FrameOverflowError`, `CLIENT_READ_CAPS`, `BROKER_READ_CAPS`, and every
+  frame/protocol type (`WelcomeFrame`, `AckFrame`, `HelloFrame`,
+  `ReloadAuthFrame` is intentionally NOT re-exported by name here but is
+  covered as a documented wire contract — see the compat note).
+- **Utility exports** — `general` (an error constructor from
+  `core/errors.js`; the type `CrtrError` is exported type-only) and `nowIso`
+  (an ISO-timestamp helper from `core/fs-utils.js`). Both are plain,
+  side-effect-free functions over Node builtins. No other error helper
+  (`notFound`, `usage`, `ambiguous`, `network`, `notImplemented`) is exported
+  — construct a `general(message, details)` error instead if you need one
+  from outside the package.
+
+## What is NOT public
+
+- `startWebServer` / `RunningWebServer` (`src/clients/web/server.ts`) are
+  **not exported** and are not part of the public API. A consumer that needs
+  an HTTP front for guest/remote use cases builds its own process; it does
+  not import crtr's web server.
+- Anything under `src/commands/`, `src/daemon/`, `src/core/canvas/*` (writer
+  paths), or any file not reachable from one of the three barrels above.
+- Deep imports (`@north-light/crouter/dist/...`, `@north-light/crouter/src/...`)
+  — the `exports` map blocks these at resolution time for ESM/Node16
+  consumers; treat any working deep import as an accident, not a contract.
+
+## External runtime contracts (not library imports)
+
+A consumer that runs alongside crtr (a separate process, a separate repo)
+also has a CLI/socket/schema surface to depend on instead of an import.
+That contract — `crtr sys version`, `crtr node message send`, the in-guest web port,
+the broker `view.sock` `reload_auth` subset, and the canvas.db byte-shape —
+is documented separately and versioned: see `docs/compat/hearth-crtr-v5.md`.
+
+## Packaging
+
+`docs/` is listed in `package.json#files`, so this note and the compat note
+ship inside the published npm package, not only in the GitHub repo.

package/package.json

@@ -0,0 +1,156 @@
+{
+  "name": "@north-light/crouter",
+  "version": "0.3.154",
+  "description": "crtr — agent runtime with memory, plugins, and marketplaces",
+  "type": "module",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "crtr": "bin/crtr",
+    "crouter": "bin/crouter",
+    "crtrd": "bin/crtrd"
+  },
+  "imports": {
+    "#api/*": {
+      "crtr-src": "./src/api/*.ts",
+      "default": "./dist/api/*.js"
+    },
+    "#clients/*": {
+      "crtr-src": "./src/clients/*.ts",
+      "default": "./dist/clients/*.js"
+    },
+    "#commands/*": {
+      "crtr-src": "./src/commands/*.ts",
+      "default": "./dist/commands/*.js"
+    },
+    "#core/*": {
+      "crtr-src": "./src/core/*.ts",
+      "default": "./dist/core/*.js"
+    },
+    "#daemon/*": {
+      "crtr-src": "./src/daemon/*.ts",
+      "default": "./dist/daemon/*.js"
+    },
+    "#pi-extensions/*": {
+      "crtr-src": "./src/pi-extensions/*.ts",
+      "default": "./dist/pi-extensions/*.js"
+    },
+    "#prompts/*": {
+      "crtr-src": "./src/prompts/*.ts",
+      "default": "./dist/prompts/*.js"
+    },
+    "#types": {
+      "crtr-src": "./src/types.ts",
+      "default": "./dist/types.js"
+    }
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./cli": {
+      "import": "./dist/cli.js"
+    },
+    "./web": {
+      "import": "./dist/web/index.js",
+      "types": "./dist/web/index.d.ts"
+    },
+    "./api": {
+      "import": "./dist/api/index.js",
+      "types": "./dist/api/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "bin",
+    "!bin/__tests__",
+    "docs",
+    "scripts/postinstall.mjs",
+    "scripts/patch-pi-tree-root-ordering.mjs",
+    "scripts/install-runtime.mjs",
+    "scripts/runtime-lock.mjs",
+    "runtime.lock.json"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "build:api": "tsc -p packages/crouter-api/tsconfig.json",
+    "typecheck:pi-packages": "npx tsc -p src/builtin-pi-packages/pi-crtr-extensions/tsconfig.json && npx tsc -p src/builtin-pi-packages/pi-mode-switch/tsconfig.json",
+    "test:build-output": "node scripts/test-runner.mjs build-output",
+    "lint:web-px": "node scripts/lint-web-px.mjs",
+    "check:cli-no-canvas": "node scripts/check-cli-no-canvas.mjs",
+    "postinstall": "node scripts/postinstall.mjs",
+    "install-runtime": "node scripts/install-runtime.mjs",
+    "prepack": "node scripts/runtime-lock.mjs prepack",
+    "postpack": "node scripts/runtime-lock.mjs postpack",
+    "dev": "tsx --conditions=crtr-src src/cli.ts",
+    "link": "npm link",
+    "prepublishOnly": "npm run build",
+    "test": "node scripts/test-runner.mjs fast",
+    "test:full": "node scripts/test-runner.mjs full",
+    "test:full:cheap": "node scripts/test-runner.mjs cheap",
+    "test:full:process": "node scripts/test-runner.mjs process",
+    "test:full:live": "node scripts/test-runner.mjs live",
+    "test:full:heavy": "node scripts/test-runner.mjs heavy"
+  },
+  "overrides": {
+    "@earendil-works/pi-ai": "0.82.1",
+    "@earendil-works/pi-agent-core": "0.82.1",
+    "@earendil-works/pi-tui": "0.82.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vallum-security/crouter.git"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@crouton-kit/humanloop": "0.4.19",
+    "@earendil-works/pi-agent-core": "0.82.1",
+    "@earendil-works/pi-ai": "0.82.1",
+    "@earendil-works/pi-coding-agent": "0.82.1",
+    "@earendil-works/pi-tui": "0.82.1",
+    "@fontsource-variable/fraunces": "^5.2.9",
+    "@fontsource-variable/instrument-sans": "^5.2.8",
+    "@fontsource-variable/martian-mono": "^5.2.7",
+    "@fontsource/fragment-mono": "^5.2.8",
+    "@tailwindcss/vite": "^4.3.0",
+    "@tanstack/react-virtual": "^3.13.0",
+    "@types/markdown-it": "^14.1.2",
+    "@vitejs/plugin-react": "^6.0.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cron-parser": "^5.6.0",
+    "dompurify": "^3.2.3",
+    "highlight.js": "^11.11.1",
+    "lucide-react": "^0.469.0",
+    "markdown-it": "^14.1.0",
+    "proper-lockfile": "4.1.2",
+    "radix-ui": "^1.5.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-router-dom": "^7.1.1",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss": "^4.3.0",
+    "tw-animate-css": "^1.0.0",
+    "vite": "^8.0.16",
+    "web-push": "^3.6.7",
+    "ws": "^8.21.0",
+    "yaml": "^2.9.0",
+    "zustand": "^5.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@types/web-push": "^3.6.4",
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.27.7",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vite-plugin-pwa": "^1.3.0"
+  }
+}