@north-light/crouter 0.3.318 → 0.3.320

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

@@ -1,152 +1,3 @@
-// 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), the
-// `crtr surface attach` terminal client, and crtrd's attach 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/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 ARE pi's RPC types (decision §1.15) — imported
-// from the package root and re-exported here, so `broker-protocol` remains the
-// one import site for the wire union while the shapes stay pi's, versioned by
-// pi. pi names the correlation field `id` (design §5.2 wrote `request_id`); we
-// follow pi.
-import { StringDecoder } from 'node:string_decoder';
-// Client → broker frames
-/** Largest transcript window a client may request in its welcome snapshot. */
-export const SNAPSHOT_TAIL_MAX = 500;
-/** Invalid requests preserve the complete welcome; valid requests are capped. */
-export function normalizeSnapshotTail(value) {
-    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
-        return undefined;
-    return Math.min(value, SNAPSHOT_TAIL_MAX);
-}
-// 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 — the long-lived
- *  broker makes a big welcome a realistic, not pathological, trigger, but the
- *  fixed cap is accepted. */
-export const CLIENT_READ_CAPS = {
-    maxLineBytes: 256 * 1024 * 1024,
-    maxTotalBytes: 256 * 1024 * 1024,
-};
-/** Caps the BROKER uses reading CLIENT frames. Sized so an image-paste frame
- *  fits: a resizeImage-bounded PNG's base64 is a few MiB and would clip a
- *  tighter 4 MiB line cap, so these hold an image-bearing `prompt`/`steer`/
- *  `follow_up` frame. 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 surface 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;
-    }
-}
+var f=Object.defineProperty;var o=(t,e)=>f(t,"name",{value:e,configurable:!0});import{StringDecoder as y}from"node:string_decoder";const m=500;function x(t){if(!(typeof t!="number"||!Number.isSafeInteger(t)||t<1))return Math.min(t,m)}o(x,"normalizeSnapshotTail");function u(t){return JSON.stringify(t)+`
+`}o(u,"encodeFrame");class h extends Error{static{o(this,"FrameOverflowError")}kind;bytes;cap;constructor(e,s,i){super(`frame decoder overflow (${e}): ${s} bytes exceeds cap ${i}`),this.kind=e,this.bytes=s,this.cap=i,this.name="FrameOverflowError"}}const d={maxLineBytes:256*1024*1024,maxTotalBytes:256*1024*1024},w={maxLineBytes:24*1024*1024,maxTotalBytes:48*1024*1024};class g{static{o(this,"FrameDecoder")}caps;parts=[];partBytes=0;utf8=new y("utf8");constructor(e){this.caps=e}push(e){const s=typeof e=="string"?e:this.utf8.write(e),i=Buffer.byteLength(s);if(this.partBytes+i>this.caps.maxTotalBytes)throw new h("total",this.partBytes+i,this.caps.maxTotalBytes);const p=[];let r=0,a;for(;(a=s.indexOf(`
+`,r))>=0;){const n=s.slice(r,a),c=(this.parts.length>0?this.parts.join("")+n:n).trim();if(this.parts.length=0,this.partBytes=0,r=a+1,c!=="")try{p.push(JSON.parse(c))}catch{}}if(r<s.length){const n=r===0?s:s.slice(r);this.parts.push(n),this.partBytes+=r===0?i:Buffer.byteLength(n)}if(this.partBytes>this.caps.maxLineBytes)throw new h("line",this.partBytes,this.caps.maxLineBytes);return p}}export{w as BROKER_READ_CAPS,d as CLIENT_READ_CAPS,g as FrameDecoder,h as FrameOverflowError,m as SNAPSHOT_TAIL_MAX,u as encodeFrame,x as normalizeSnapshotTail};

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

@@ -1,85 +1 @@
-// broker-request.ts — the ONE one-shot writable round-trip against a LIVE
-// node broker over its view.sock: connect → `hello` as controller → send a
-// single frame → await its ack.
-//
-// Every host-side "tell a booted engine something" path rides this: the model
-// swap (model-swap.ts), interactive deliver/interrupt (interactive-deliver.ts),
-// and the warm-pool claim's live custom-message delivery (deliver-live.ts).
-// They differ only in the frame sent, the ack awaited, and what they read off
-// the ack — so the dance itself lives here once instead of being re-copied per
-// caller.
-import { randomUUID } from 'node:crypto';
-import { BrokerClient } from '../broker-client/index.js';
-/** How long to wait for the broker's ack. Every frame this carries is local
- *  engine work (a queue push, a model swap, an abort), so this is generous
- *  slack rather than a tuned budget. */
-const ACK_TIMEOUT_MS = 15_000;
-/** The request never ESTABLISHED the broker connection — the liveness
- *  heuristic said live (pid alive + socket file present) but the broker was
- *  mid-revive and refused/closed before any protocol frame. This is a transport
- *  race, NOT a broker-side rejection (which surfaces as a plain `Error` carrying
- *  the broker's own message). Callers distinguish it to fall back to a durable
- *  path rather than failing the operation. */
-export class BrokerUnreachableError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'BrokerUnreachableError';
-    }
-}
-/** Run one controller round-trip and resolve with `result(ack.detail)`.
- *
- *  Rejects with: the broker's message on an `error` frame or a `ok:false` ack;
- *  `BrokerUnreachableError` when the socket fails BEFORE `connect` fires (a
- *  mid-revive race the caller can fall back from); a plain `Error` when it fails
- *  after (a genuine broker fault) or on timeout. */
-export function oneShotControllerRequest(opts) {
-    return new Promise((resolve, reject) => {
-        const client = new BrokerClient(opts.nodeId);
-        const clientId = randomUUID();
-        const frameId = randomUUID();
-        let settled = false;
-        let connected = false;
-        const timer = setTimeout(() => finish(() => reject(new Error(`timed out after ${ACK_TIMEOUT_MS}ms waiting for the broker to ack ${opts.what}`))), ACK_TIMEOUT_MS);
-        if (typeof timer.unref === 'function')
-            timer.unref();
-        function finish(act) {
-            if (settled)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            try {
-                client.close();
-            }
-            catch {
-                /* best-effort */
-            }
-            act();
-        }
-        client.on('error', (err) => finish(() => reject(connected ? err : new BrokerUnreachableError(`broker connection refused mid-revive: ${err.message}`))));
-        client.on('close', () => finish(() => reject(connected
-            ? new Error(`broker connection closed before it acked ${opts.what}`)
-            : new BrokerUnreachableError('broker connection closed before it was established (mid-revive)'))));
-        client.on('connect', () => {
-            connected = true;
-            client.send({ type: 'hello', role: 'controller', client_id: clientId });
-            client.send(opts.frame(frameId));
-        });
-        client.on('frame', (frame) => {
-            if (frame.type === 'ack' && frame.for === opts.ackFor && (opts.correlated !== true || frame.id === frameId)) {
-                if (frame.ok)
-                    finish(() => resolve(opts.result(frame.detail)));
-                else
-                    finish(() => reject(new Error(frame.detail ?? `broker rejected ${opts.what}`)));
-            }
-            else if (frame.type === 'error') {
-                // This connection only ever sent hello + one payload frame, so any
-                // error frame here is a response to ours.
-                finish(() => reject(new Error(frame.message)));
-            }
-            else if (opts.observe !== undefined) {
-                opts.observe(frame);
-            }
-        });
-        client.connect();
-    });
-}
+var b=Object.defineProperty;var c=(r,t)=>b(r,"name",{value:t,configurable:!0});import{randomUUID as f}from"node:crypto";import{BrokerClient as h}from"../broker-client/index.js";const u=15e3;class k extends Error{static{c(this,"BrokerUnreachableError")}constructor(t){super(t),this.name="BrokerUnreachableError"}}function y(r){return new Promise((t,i)=>{const o=new h(r.nodeId),w=f(),d=f();let a=!1,l=!1;const s=setTimeout(()=>n(()=>i(new Error(`timed out after ${u}ms waiting for the broker to ack ${r.what}`))),u);typeof s.unref=="function"&&s.unref();function n(e){if(!a){a=!0,clearTimeout(s);try{o.close()}catch{}e()}}c(n,"finish"),o.on("error",e=>n(()=>i(l?e:new k(`broker connection refused mid-revive: ${e.message}`)))),o.on("close",()=>n(()=>i(l?new Error(`broker connection closed before it acked ${r.what}`):new k("broker connection closed before it was established (mid-revive)")))),o.on("connect",()=>{l=!0,o.send({type:"hello",role:"controller",client_id:w}),o.send(r.frame(d))}),o.on("frame",e=>{e.type==="ack"&&e.for===r.ackFor&&(r.correlated!==!0||e.id===d)?e.ok?n(()=>t(r.result(e.detail))):n(()=>i(new Error(e.detail??`broker rejected ${r.what}`))):e.type==="error"?n(()=>i(new Error(e.message))):r.observe!==void 0&&r.observe(e)}),o.connect()})}c(y,"oneShotControllerRequest");export{k as BrokerUnreachableError,y as oneShotControllerRequest};

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

@@ -1,129 +1 @@
-// broker-sdk.ts — the single import-and-version-assert shim between the headless
-// broker and the pi SDK (`@earendil-works/pi-coding-agent`).
-//
-// The broker imports the SDK in-process, and the bundled pi CLI is used only for
-// incidental headless helper commands and the version tripwire. 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.
-import { execFileSync } from 'node:child_process';
-import { readFileSync, statSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { envBrokerEngine } from '../../shared/env.js';
-import { createAgentSessionServices, createAgentSessionFromServices, createAgentSessionRuntime, SessionManager, VERSION, } from '@earendil-works/pi-coding-agent';
-import { crtrHome } from '../canvas/paths.js';
-import { emitEvent } from '../events/emit.js';
-import { resolveBundledPiCliPath } from './pi-cli.js';
-// 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 = envBrokerEngine();
-    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',
-    };
-}
-const PI_VERSION_CACHE = () => join(crtrHome(), 'pi-version.json');
-/** Cached `pi --version`, keyed on the CLI's path+mtime+size so a pi upgrade
- *  re-probes but the steady state never spawns. Returns undefined when the cache
- *  misses — the caller then spawns once and back-fills via {@link writePiVersionCache}. */
-function readPiVersionCache(binPath, mtimeMs, size) {
-    try {
-        const c = JSON.parse(readFileSync(PI_VERSION_CACHE(), 'utf8'));
-        if (c.path === binPath && c.mtimeMs === mtimeMs && c.size === size && typeof c.version === 'string') {
-            return c.version;
-        }
-    }
-    catch {
-        /* missing/corrupt cache — treat as a miss */
-    }
-    return undefined;
-}
-function writePiVersionCache(entry) {
-    try {
-        writeFileSync(PI_VERSION_CACHE(), JSON.stringify(entry), 'utf8');
-    }
-    catch {
-        /* best-effort: a missing cache just means the next boot re-probes */
-    }
-}
-export function assertEngineVersion(engineVersion = VERSION) {
-    // Resolve + stat the bundled CLI (no spawn). When its path+mtime+size matches
-    // the cache, reuse the stored version and skip the ~0.4s `pi --version` boot —
-    // the common path on every broker start. A pi upgrade changes the stat and re-probes.
-    let binPath;
-    let stat;
-    try {
-        binPath = resolveBundledPiCliPath();
-        const s = statSync(binPath);
-        stat = { mtimeMs: s.mtimeMs, size: s.size };
-    }
-    catch (err) {
-        try {
-            emitEvent({
-                level: 'warn',
-                event: 'broker.startup.warning',
-                error: err,
-                fields: { stage: 'resolve_bundled_cli', engine_version: engineVersion, cli_version: null, cli_path: null },
-            });
-        }
-        catch {
-            /* Canonical warning append failure must not change the parity probe. */
-        }
-        return;
-    }
-    let binaryVersion = readPiVersionCache(binPath, stat.mtimeMs, stat.size);
-    if (binaryVersion === undefined) {
-        try {
-            binaryVersion = execFileSync(process.execPath, [binPath, '--version'], { encoding: 'utf8' }).trim();
-        }
-        catch (err) {
-            try {
-                emitEvent({
-                    level: 'warn',
-                    event: 'broker.startup.warning',
-                    error: err,
-                    fields: { stage: 'probe_bundled_cli', engine_version: engineVersion, cli_version: null, cli_path: binPath },
-                });
-            }
-            catch {
-                /* Canonical warning append failure must not change the parity probe. */
-            }
-            return;
-        }
-        writePiVersionCache({ path: binPath, mtimeMs: stat.mtimeMs, size: stat.size, version: binaryVersion });
-    }
-    if (binaryVersion !== engineVersion) {
-        try {
-            emitEvent({
-                level: 'warn',
-                event: 'broker.startup.warning',
-                fields: { stage: 'version_mismatch', engine_version: engineVersion, cli_version: binaryVersion, cli_path: binPath },
-            });
-        }
-        catch {
-            /* Canonical warning append failure must not change the parity probe. */
-        }
-    }
-}
+var m=Object.defineProperty;var s=(n,e)=>m(n,"name",{value:e,configurable:!0});import{execFileSync as S}from"node:child_process";import{readFileSync as l,statSync as f,writeFileSync as g}from"node:fs";import{join as p}from"node:path";import{envBrokerEngine as u}from"../../shared/env.js";import{createAgentSessionServices as v,createAgentSessionFromServices as d,createAgentSessionRuntime as y,SessionManager as h,VERSION as c}from"@earendil-works/pi-coding-agent";import{crtrHome as _}from"../canvas/paths.js";import{emitEvent as o}from"../events/emit.js";import{resolveBundledPiCliPath as A}from"./pi-cli.js";async function z(){const n=u(),e=await import(n);if(typeof e.createAgentSessionServices!="function"||typeof e.createAgentSessionFromServices!="function"||typeof e.SessionManager!="function")throw new Error(`[broker] engine '${n}' does not export createAgentSessionServices/createAgentSessionFromServices/SessionManager \u2014 not a valid pi-SDK-compatible engine`);return{createAgentSessionServices:e.createAgentSessionServices,createAgentSessionFromServices:e.createAgentSessionFromServices,createAgentSessionRuntime:typeof e.createAgentSessionRuntime=="function"?e.createAgentSessionRuntime:void 0,SessionManager:e.SessionManager,VERSION:typeof e.VERSION=="string"?e.VERSION:"unknown"}}s(z,"loadBrokerEngine");const a=s(()=>p(_(),"pi-version.json"),"PI_VERSION_CACHE");function w(n,e,t){try{const r=JSON.parse(l(a(),"utf8"));if(r.path===n&&r.mtimeMs===e&&r.size===t&&typeof r.version=="string")return r.version}catch{}}s(w,"readPiVersionCache");function E(n){try{g(a(),JSON.stringify(n),"utf8")}catch{}}s(E,"writePiVersionCache");function I(n=c){let e,t;try{e=A();const i=f(e);t={mtimeMs:i.mtimeMs,size:i.size}}catch(i){try{o({level:"warn",event:"broker.startup.warning",error:i,fields:{stage:"resolve_bundled_cli",engine_version:n,cli_version:null,cli_path:null}})}catch{}return}let r=w(e,t.mtimeMs,t.size);if(r===void 0){try{r=S(process.execPath,[e,"--version"],{encoding:"utf8"}).trim()}catch(i){try{o({level:"warn",event:"broker.startup.warning",error:i,fields:{stage:"probe_bundled_cli",engine_version:n,cli_version:null,cli_path:e}})}catch{}return}E({path:e,mtimeMs:t.mtimeMs,size:t.size,version:r})}if(r!==n)try{o({level:"warn",event:"broker.startup.warning",fields:{stage:"version_mismatch",engine_version:n,cli_version:r,cli_path:e}})}catch{}}s(I,"assertEngineVersion");export{h as SessionManager,c as VERSION,I as assertEngineVersion,d as createAgentSessionFromServices,y as createAgentSessionRuntime,v as createAgentSessionServices,z as loadBrokerEngine};