@crouton-kit/crouter 0.3.18 → 0.3.20

package/dist/core/runtime/broker-protocol.js

@@ -0,0 +1,153 @@
+// broker-protocol.ts — the client↔broker wire protocol for the headless node
+// Surface (design §5.2). Pure types + a newline-delimited JSON codec; no I/O, no
+// SDK construction. Consumed by the broker (src/core/runtime/broker.ts) and, in
+// Phase 4, by the `crtr attach` terminal client and the `crtr web` bridge.
+//
+// The transport is one unix socket per node (`nodeDir(id)/view.sock`) speaking
+// newline-delimited JSON frames. Live engine events are relayed VERBATIM — the
+// broker is a transparent multiplexer, so a broker→client frame is either one of
+// the broker's own control frames (welcome/control_changed/error) or a raw pi
+// `AgentSessionEvent` / `extension_ui_request`. The `type` namespaces never
+// collide, so the union below stays a clean discriminated union.
+//
+// The extension-dialog frames mirror pi's RPC types (decision §1.15). pi names
+// the correlation field `id` (design §5.2 wrote `request_id`); we follow pi.
+//
+// NOTE (version-skew, 2026-06-08): §1.15 says to IMPORT pi's now-public
+// `RpcExtensionUIRequest`/`RpcExtensionUIResponse`. The newer pi build re-exports
+// them from the package root, but the npm-published `0.78.1` currently in
+// crouter's node_modules defines them in `dist/modes/rpc/rpc-types.d.ts` WITHOUT
+// re-exporting them (the `exports` map gates off deep subpaths, so even a
+// type-only deep import is unresolvable). They are therefore mirrored locally
+// below — byte-for-byte from pi's `rpc-types.d.ts`. When the published build
+// catches up, delete these two declarations and import them from the package
+// root; nothing else changes (same names, same shapes).
+import { StringDecoder } from 'node:string_decoder';
+// ---------------------------------------------------------------------------
+// Newline-delimited JSON codec (the framing pi solves with `jsonl`, reproduced
+// locally so the protocol module owns no transport dependency)
+// ---------------------------------------------------------------------------
+/** Encode one frame as a single newline-terminated JSON line. */
+export function encodeFrame(frame) {
+    return JSON.stringify(frame) + '\n';
+}
+/** Thrown by {@link FrameDecoder.push} when a peer's buffered bytes exceed a cap
+ *  (C5). The caller catches it, best-effort sends `error{code:'frame_overflow'}`,
+ *  and DESTROYS that socket — cap-and-drop the peer, never grow-to-OOM. `kind`
+ *  says which bound tripped: a single oversized frame (`line`) or total backlog
+ *  (`total`). */
+export class FrameOverflowError extends Error {
+    kind;
+    bytes;
+    cap;
+    constructor(kind, bytes, cap) {
+        super(`frame decoder overflow (${kind}): ${bytes} bytes exceeds cap ${cap}`);
+        this.kind = kind;
+        this.bytes = bytes;
+        this.cap = cap;
+        this.name = 'FrameOverflowError';
+    }
+}
+/** Caps the CLIENT uses reading BROKER frames. The `welcome.snapshot` carries the
+ *  full message history and can be many MiB, so these are generous. Covers
+ *  realistic long sessions; snapshot CHUNKING is deferred (plan §1.1 known
+ *  limitation, review m3 — the long-lived broker makes a big welcome a realistic,
+ *  not pathological, trigger, but the fixed cap is accepted for Phase 4). */
+export const CLIENT_READ_CAPS = {
+    maxLineBytes: 256 * 1024 * 1024,
+    maxTotalBytes: 256 * 1024 * 1024,
+};
+/** Caps the BROKER uses reading CLIENT frames. Plan §1.1 specified a tight
+ *  4/16 MiB, but review M1 requires image-paste frames to fit: a resizeImage-
+ *  bounded PNG's base64 is a few MiB and would clip a 4 MiB line cap. So these are
+ *  RAISED above the plan's 4/16 to hold an image-bearing `prompt`/`steer`/
+ *  `follow_up` frame (M1). Still bounded, so a malicious/buggy client→broker frame
+ *  is cap-and-dropped, never grow-to-OOM (C5). */
+export const BROKER_READ_CAPS = {
+    maxLineBytes: 24 * 1024 * 1024,
+    maxTotalBytes: 48 * 1024 * 1024,
+};
+/** Incremental newline-delimited JSON reader: feed raw socket chunks, get back
+ *  the complete frames decoded so far. Buffers a partial trailing line across
+ *  pushes; silently drops a malformed (unparseable) line (a viewer must never
+ *  crash the broker on bad JSON). The caller narrows the `unknown` against the
+ *  frame unions.
+ *
+ *  BOUNDED (C5): an oversized buffer is the THROW case. If a single push peaks the
+ *  internal buffer above `maxTotalBytes`, or the surviving (unterminated) partial
+ *  line exceeds `maxLineBytes`, {@link push} throws {@link FrameOverflowError}
+ *  instead of returning frames — the caller drops that peer rather than letting a
+ *  malicious/buggy stream grow the buffer to OOM. Bytes are measured with
+ *  `Buffer.byteLength`, never string length; a running counter makes each push's
+ *  size CHECK O(1) (no re-scan of the whole buffer to measure it).
+ *
+ *  AMORTIZED O(total bytes) (perf regression fix, 2026-06-09): the partial line
+ *  carried across pushes is held as an ARRAY of chunk strings (`parts`), joined
+ *  only when its terminating `\n` arrives. The `\n` scan looks at each incoming
+ *  chunk ONCE — never re-scanning the accumulated carry — so a multi-MiB frame
+ *  arriving in ~64 KiB socket chunks costs O(frame) total instead of O(frame ×
+ *  chunks). The old `buf += chunk; buf.indexOf('\n')` shape flattened + re-walked
+ *  the whole carry per chunk: a 16 MiB welcome snapshot cost ~250 ms of
+ *  event-loop stall in `crtr attach` (typing lag) and the same again in the
+ *  broker; this shape decodes it in ~13 ms.
+ *
+ *  A `StringDecoder` decodes incoming Buffer chunks: an incomplete trailing
+ *  multibyte sequence is held back across pushes instead of being mangled to
+ *  U+FFFD, so a char split at a `node:net` chunk boundary is never corrupted, and
+ *  `partBytes` counts decoded-string bytes (a raw `chunk.length` would desync
+ *  and weaken the C5 cap on multibyte/invalid input). */
+export class FrameDecoder {
+    caps;
+    /** The unterminated partial line carried across pushes, as unjoined chunks
+     *  (never contains a '\n'). Joined lazily when its newline arrives. */
+    parts = [];
+    /** Byte length (Buffer.byteLength) of `parts` joined — kept in exact lockstep. */
+    partBytes = 0;
+    utf8 = new StringDecoder('utf8');
+    constructor(caps) {
+        this.caps = caps;
+    }
+    push(chunk) {
+        // A string input is already complete text; a Buffer goes through the
+        // StringDecoder so a boundary-split multibyte char is buffered, not corrupted.
+        const str = typeof chunk === 'string' ? chunk : this.utf8.write(chunk);
+        const strBytes = Buffer.byteLength(str);
+        // Peak-buffer bound: caps the most we ever hold in one push (carry + this
+        // entire chunk, before draining complete frames) — identical accounting to
+        // the old whole-buffer check.
+        if (this.partBytes + strBytes > this.caps.maxTotalBytes) {
+            throw new FrameOverflowError('total', this.partBytes + strBytes, this.caps.maxTotalBytes);
+        }
+        const out = [];
+        let from = 0; // scan offset into `str` — each chunk is scanned exactly once
+        let nl;
+        while ((nl = str.indexOf('\n', from)) >= 0) {
+            const tail = str.slice(from, nl);
+            // First line of the push completes the carried partial; later lines live
+            // entirely inside `str` (parts is empty after the first join).
+            const line = (this.parts.length > 0 ? this.parts.join('') + tail : tail).trim();
+            this.parts.length = 0;
+            this.partBytes = 0;
+            from = nl + 1;
+            if (line === '')
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                /* drop a malformed frame — never throw out of the reader for bad JSON */
+            }
+        }
+        if (from < str.length) {
+            const rest = from === 0 ? str : str.slice(from);
+            this.parts.push(rest);
+            this.partBytes += from === 0 ? strBytes : Buffer.byteLength(rest);
+        }
+        // Single-frame bound: a partial line that has grown past one frame's cap is a
+        // peer streaming bytes with no newline — drop it rather than buffer forever.
+        if (this.partBytes > this.caps.maxLineBytes) {
+            throw new FrameOverflowError('line', this.partBytes, this.caps.maxLineBytes);
+        }
+        return out;
+    }
+}

package/dist/core/runtime/broker-sdk.d.ts

@@ -0,0 +1,48 @@
+import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION } from '@earendil-works/pi-coding-agent';
+export { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, };
+/**
+ * The minimal slice of the pi SDK the broker needs. Both the real package and the
+ * T11 `fake-engine` fixture satisfy this shape, so the broker can be driven by
+ * either via the `CRTR_BROKER_ENGINE` seam below.
+ *
+ * C3 (viewer-reuse scout `mq5thyli`): the broker drives the SERVICES path
+ * (`createAgentSessionServices` → `createAgentSessionFromServices`), NOT plain
+ * `createAgentSession`. Only the services path runs `registerProvider` (extension
+ * model-providers) + `applyExtensionFlagValues`, so a node whose model comes from
+ * a custom-provider extension actually gets a model. Mirrors pi `main.js`.
+ */
+export interface BrokerEngine {
+    createAgentSessionServices: typeof createAgentSessionServices;
+    createAgentSessionFromServices: typeof createAgentSessionFromServices;
+    /**
+     * The session-replacement runtime factory (T3 new_session/switch_session/fork).
+     * OPTIONAL: the real SDK (0.78.1) exposes it, so production gets full session
+     * replacement; the `fake-engine` test fixture does NOT provide it, so the
+     * broker degrades those three ops to an `error{engine_error}` reply rather than
+     * failing engine validation. Everything else works on both.
+     */
+    createAgentSessionRuntime?: typeof createAgentSessionRuntime;
+    SessionManager: typeof SessionManager;
+    VERSION: string;
+}
+/**
+ * Resolve the broker's engine module. Defaults to the real SDK; honors the
+ * `CRTR_BROKER_ENGINE` env var (T11 test seam) so a lifecycle test can point the
+ * broker at `fixtures/fake-engine.ts` without touching production code. This is the
+ * sole dynamic-import indirection point — keep all engine resolution flowing
+ * through here so the seam stays a single, auditable swap.
+ */
+export declare function loadBrokerEngine(): Promise<BrokerEngine>;
+/**
+ * Boot-time tripwire: compare the imported SDK `VERSION` against the `pi` binary
+ * crouter forks elsewhere (`pi --version`). On mismatch (or if the binary can't be
+ * probed) it logs a LOUD warning to stderr and proceeds — it NEVER throws. The v3
+ * session format auto-migrates on load, so minor skew round-trips; a hard fail here
+ * would risk a grace-revive crash loop. Phase 5 may harden this to fail-fast once
+ * the broker is the only host.
+ *
+ * @param engineVersion the version actually loaded (defaults to the statically
+ *   imported `VERSION`; pass `engine.VERSION` from `loadBrokerEngine` to assert the
+ *   version the broker is really driving).
+ */
+export declare function assertEngineVersion(engineVersion?: string): void;

package/dist/core/runtime/broker-sdk.js

@@ -0,0 +1,72 @@
+// broker-sdk.ts — the single import-and-version-assert shim between the headless
+// broker and the pi SDK (`@earendil-works/pi-coding-agent`).
+//
+// crouter has never imported the SDK before — it only ever forked the `pi` binary
+// (see `launch.ts buildPiArgv`). The broker (T4) is the first consumer. This shim
+// is the one place the dependency is named, so:
+//   - the version tripwire (`assertEngineVersion`) lives here, and
+//   - the `CRTR_BROKER_ENGINE` test seam (T11) has a single dynamic-import
+//     indirection point (`loadBrokerEngine`) to swap in the fake engine.
+//
+// Nothing else in the tree imports this yet; it compiles but stays inert so the
+// lifecycle suite stays green until the broker is wired up.
+import { execFileSync } from 'node:child_process';
+import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, } from '@earendil-works/pi-coding-agent';
+// Static re-exports — the real SDK surface the broker drives in production.
+export { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, };
+/**
+ * Resolve the broker's engine module. Defaults to the real SDK; honors the
+ * `CRTR_BROKER_ENGINE` env var (T11 test seam) so a lifecycle test can point the
+ * broker at `fixtures/fake-engine.ts` without touching production code. This is the
+ * sole dynamic-import indirection point — keep all engine resolution flowing
+ * through here so the seam stays a single, auditable swap.
+ */
+export async function loadBrokerEngine() {
+    const spec = process.env.CRTR_BROKER_ENGINE ?? '@earendil-works/pi-coding-agent';
+    const mod = (await import(spec));
+    if (typeof mod.createAgentSessionServices !== 'function' ||
+        typeof mod.createAgentSessionFromServices !== 'function' ||
+        typeof mod.SessionManager !== 'function') {
+        throw new Error(`[broker] engine '${spec}' does not export createAgentSessionServices/` +
+            `createAgentSessionFromServices/SessionManager — not a valid pi-SDK-compatible engine`);
+    }
+    return {
+        createAgentSessionServices: mod.createAgentSessionServices,
+        createAgentSessionFromServices: mod.createAgentSessionFromServices,
+        // Optional — passed through only when the engine exposes it (real SDK yes,
+        // fake-engine no). The broker checks for its presence before the three
+        // session-replacing ops.
+        createAgentSessionRuntime: typeof mod.createAgentSessionRuntime === 'function' ? mod.createAgentSessionRuntime : undefined,
+        SessionManager: mod.SessionManager,
+        VERSION: typeof mod.VERSION === 'string' ? mod.VERSION : 'unknown',
+    };
+}
+/**
+ * Boot-time tripwire: compare the imported SDK `VERSION` against the `pi` binary
+ * crouter forks elsewhere (`pi --version`). On mismatch (or if the binary can't be
+ * probed) it logs a LOUD warning to stderr and proceeds — it NEVER throws. The v3
+ * session format auto-migrates on load, so minor skew round-trips; a hard fail here
+ * would risk a grace-revive crash loop. Phase 5 may harden this to fail-fast once
+ * the broker is the only host.
+ *
+ * @param engineVersion the version actually loaded (defaults to the statically
+ *   imported `VERSION`; pass `engine.VERSION` from `loadBrokerEngine` to assert the
+ *   version the broker is really driving).
+ */
+export function assertEngineVersion(engineVersion = VERSION) {
+    let binaryVersion;
+    try {
+        binaryVersion = execFileSync('pi', ['--version'], { encoding: 'utf8' }).trim();
+    }
+    catch (err) {
+        process.stderr.write(`[broker] WARNING: could not run 'pi --version' to verify engine parity ` +
+            `(SDK ${engineVersion}): ${err.message}\n`);
+        return;
+    }
+    if (binaryVersion !== engineVersion) {
+        process.stderr.write(`[broker] WARNING: pi SDK version mismatch — imported SDK is ${engineVersion} but ` +
+            `the 'pi' binary is ${binaryVersion}. The v3 session format auto-migrates on load so ` +
+            `minor skew round-trips, but pin '@earendil-works/pi-coding-agent' to the binary version ` +
+            `to keep the in-process engine and the forked binary in lockstep.\n`);
+    }
+}

package/dist/core/runtime/broker.d.ts

@@ -0,0 +1,55 @@
+import { type Socket } from 'node:net';
+import { type AgentSessionRuntime, type AgentSessionServices, type CreateAgentSessionResult, type ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import { type BrokerSdkConfig } from './launch.js';
+import { type BrokerEngine } from './broker-sdk.js';
+import { FrameDecoder, type ClientRole, type RpcExtensionUIRequest, type RpcExtensionUIResponse } from './broker-protocol.js';
+interface BrokerClient {
+    id: string;
+    role: ClientRole;
+    socket: Socket;
+    decoder: FrameDecoder;
+    helloed: boolean;
+    /** Unflushed outbound bytes handed to `socket.write` but not yet flushed to the
+     *  OS (M1 backpressure accounting). Incremented before each write, decremented
+     *  in that write's completion callback. */
+    pendingBytes: number;
+    /** Outbound frames written but not yet flushed (the queue-depth half of the
+     *  high-water mark). */
+    queuedFrames: number;
+}
+/** A blocking dialog awaiting the controller's response, the broker-side default
+ *  timeout, or the engine's abort. */
+interface PendingDialog {
+    /** The original request (T4) — retained so `welcome.pending_dialog` and the
+     *  re-route-on-become-controller path can re-deliver a still-pending dialog to
+     *  a (new) controller. The Wave-0 shape stored only the resolver. */
+    request: RpcExtensionUIRequest;
+    /** The controller answered — resolve with its parsed response (also clears the
+     *  broker-side timeout and removes the entry from the registry). */
+    resolve: (response: RpcExtensionUIResponse) => void;
+}
+/** Dispose the live engine session if one exists (idempotent). Called by
+ *  broker-cli's fatal handlers before exit so a crash never orphans detached
+ *  bash children. No-op before the session is built or after a clean dispose. */
+export declare function disposeActiveSession(): void;
+export declare function runBroker(nodeId: string): Promise<void>;
+export declare function buildBrokerSession(engine: BrokerEngine, cfg: BrokerSdkConfig): Promise<{
+    session: CreateAgentSessionResult['session'];
+    services: AgentSessionServices;
+    resuming: boolean;
+    /** The session-replacement runtime, present iff the engine exposes
+     *  createAgentSessionRuntime (real SDK yes, fake-engine no). The broker wires
+     *  its new_session/switch_session/fork ops + rebind through it. */
+    runtime?: AgentSessionRuntime;
+}>;
+/** Broker-side hooks the UI context needs to route (or noOp) extension dialogs. */
+export interface BrokerDialogDeps {
+    /** The controller client, or null when ZERO viewers are attached. */
+    controller: () => BrokerClient | null;
+    /** Forward a dialog request to the (non-null) controller. */
+    forward: (client: BrokerClient, request: RpcExtensionUIRequest) => void;
+    /** Pending-dialog registry, keyed by request id (answered via extension_ui_response). */
+    pending: Map<string, PendingDialog>;
+}
+export declare function makeBrokerUiContext(deps: BrokerDialogDeps): ExtensionUIContext;
+export {};