@aeondave/pi-persona 1.15.2

package/src/bridge.ts

@@ -0,0 +1,209 @@
+/**
+ * The CHILD side of the cross-process broker (spec B3): loaded INSTEAD of the full
+ * extension when `PI_PERSONA_BUS` is set (see `extension.ts`'s factory dispatch). Connects
+ * a `BrokerClient` (relay to the supervisor's `InProcessBus`), registers `contact_supervisor`
+ * + `contact_peer` bound to the wire, and surfaces inbound frames as `pi.sendMessage`
+ * follow-ups — the same mechanism comtac's `index.ts` uses for inbound bus traffic, and the
+ * same fencing rule the in-process delivery bridge (`engine/inproc.ts`) enforces: untrusted
+ * sub-agent/peer text goes through `fenceUntrusted`, with attribution OUTSIDE the fence so a
+ * malicious payload can never spoof its own sender.
+ *
+ * A `steer` frame is NOT fenced — it is the supervisor's own live voice (the same as
+ * `onSteerable` in the in-process engine, which injects steer text unfenced), just attributed.
+ *
+ * No personas, no delegate/council, no input hooks — bridge mode is deliberately a sealed,
+ * minimal surface (the fork-bomb guard `PI_PERSONA_DISABLE=1` already keeps the full
+ * extension out of a spawned child; this only adds the connected comm plane on top).
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { type BrokerClient, type DeliverEvent, makeBrokerClient, type MakeBrokerClientDeps } from "./bus/broker/client.ts";
+import { makeContactSupervisorTool } from "./bus/contact.ts";
+import { InProcessBus, type MsgKind } from "./bus/inproc.ts";
+import { makeContactPeerTool, type PeerInfo } from "./bus/peers.ts";
+import { attributeInbound } from "./core/fence.ts";
+
+type Env = Record<string, string | undefined>;
+
+/** The bus handle pi-persona's supervisor always registers under (mirrors `extension.ts`'s
+ *  `SUPERVISOR` constant — a child can never BE the supervisor, `host.ts` rejects that
+ *  handle on `register`, so the literal is safe to hardcode here too). */
+const SUPERVISOR_HANDLE = "supervisor";
+
+const BRIDGE_MESSAGE_TYPE = "pi_persona_bridge";
+
+export interface InstallBridgeDeps {
+	/** Override for `process.env` (tests). */
+	env?: Env;
+	/** Override for `makeBrokerClient` (tests inject a fake `BrokerClient`). */
+	makeClient?: (deps: MakeBrokerClientDeps) => BrokerClient;
+}
+
+/** True iff this process was spawned as a broker-connected child (spec B3/B5). Checked at the
+ *  very top of the extension factory — `PI_PERSONA_BUS` unset ⇒ zero behavior change. */
+export function isBridgeMode(env: Env = process.env): boolean {
+	return !!env.PI_PERSONA_BUS;
+}
+
+/** Routes `InProcessBus.send`/`ask` over a `BrokerClient` instead of a local mailbox — the
+ *  thin adapter the bus-bound `contact_supervisor`/`contact_peer` factories need to run
+ *  unmodified against a remote target. A real `InProcessBus` subclass (not a duck-typed
+ *  object) so it satisfies the factories' concrete parameter type without touching them.
+ *  `connected` gates both overrides so the tools' existing "no supervisor reachable" /
+ *  "dropped" wording stays honest before the handshake completes — the client's own
+ *  `send`/`ask` can't report that (a write to a not-yet-open socket silently no-ops, per
+ *  spec's "sends report undelivered"). */
+class BrokerBus extends InProcessBus {
+	private readonly client: BrokerClient;
+	connected = false;
+
+	constructor(client: BrokerClient) {
+		super();
+		this.client = client;
+	}
+
+	override send(_from: string, to: string, text: string, kind: MsgKind = "progress"): boolean {
+		if (!this.connected) return false;
+		this.client.send(to, kind, text);
+		return true;
+	}
+
+	override ask(
+		_from: string,
+		to: string,
+		text: string,
+		opts: { kind?: MsgKind; timeoutMs?: number; signal?: AbortSignal } = {},
+	): Promise<string> {
+		if (!this.connected) throw new Error("bridge: not connected to the supervisor");
+		return this.client.ask(to, opts.kind ?? "decision", text, opts.signal);
+	}
+}
+
+/** Wrap fenced, attributed follow-up text as a `pi.sendMessage` custom message (comtac's
+ *  inbound-surfacing mechanism — see `index.ts`'s `surface()`). */
+function sendFollowUp(pi: ExtensionAPI, content: string): void {
+	pi.sendMessage({ customType: BRIDGE_MESSAGE_TYPE, content, display: true }, { deliverAs: "followUp", triggerTurn: true });
+}
+
+/** Install child-mode bridge wiring on `pi` — called once, from `session_start`, when
+ *  `isBridgeMode()` is true. Connects the broker client (capped retries; a failed connect
+ *  degrades to a mute executor, never a crash — spec §4), registers the two wire-bound
+ *  comm-plane tools, surfaces inbound `deliver`/`steer` frames as follow-ups, and closes the
+ *  client on `session_shutdown`. */
+export function installBridge(pi: ExtensionAPI, ctx: ExtensionContext, deps: InstallBridgeDeps = {}): void {
+	const env = deps.env ?? process.env;
+	const endpoint = env.PI_PERSONA_BUS;
+	const handle = env.PI_PERSONA_HANDLE;
+	if (!endpoint || !handle) return; // isBridgeMode() gates the real caller; malformed env degrades to a no-op
+
+	const wantsPeers = env.PI_PERSONA_PEERS === "1";
+	const clientDeps: MakeBrokerClientDeps = { endpoint, handle, ...(wantsPeers ? { peers: true } : {}) };
+	const client = (deps.makeClient ?? makeBrokerClient)(clientDeps);
+
+	// Blocking asks are honoured only when the spawning run is async (`PI_PERSONA_ALLOW_BLOCKING`,
+	// set by adapter.ts from the strategy's `allowBlocking`) — a sync delegate/council/orchestrate
+	// turn holds the supervisor's turn, so a blocking `decision`/`interview` here would deadlock it
+	// (the same safety default the in-process engine applies; see contact.ts / spec §4.9).
+	const allowBlocking = env.PI_PERSONA_ALLOW_BLOCKING === "1";
+	const bus = new BrokerBus(client);
+	pi.registerTool(makeContactSupervisorTool(bus, handle, SUPERVISOR_HANDLE, { allowBlocking }));
+
+	// The engine-scoped peer roster (B7): fetched from the host's `list` frame and cached —
+	// `contact_peer` accepts an awaitable provider, so the first call can wait for the initial
+	// wire round-trip instead of reporting the empty pre-refresh cache. Refreshes are coalesced
+	// while one is in flight; a generation guard prevents a future overlapping transport change
+	// from applying an older response over a newer roster.
+	let peerCache: PeerInfo[] = [];
+	let bridgeReady: Promise<void> | undefined;
+	let peerRefresh: Promise<PeerInfo[]> | undefined;
+	let peerRefreshGeneration = 0;
+	const refreshPeers = (): Promise<PeerInfo[]> => {
+		if (!bus.connected) {
+			const registration = bridgeReady;
+			return registration ? registration.then(() => refreshPeers(), () => peerCache) : Promise.resolve(peerCache);
+		}
+		if (peerRefresh) return peerRefresh;
+		const generation = ++peerRefreshGeneration;
+		let request: Promise<PeerInfo[]>;
+		try {
+			request = Promise.resolve(client.list()).then(
+				(peers) => {
+					if (generation === peerRefreshGeneration) peerCache = peers;
+					return peers;
+				},
+				() => {
+					/* best-effort — keep the stale cache rather than clearing a known roster */
+					return peerCache;
+				},
+			);
+		} catch {
+			request = Promise.resolve(peerCache);
+		}
+		const shared = request.finally(() => {
+			if (peerRefresh === shared) peerRefresh = undefined;
+		});
+		peerRefresh = shared;
+		return shared;
+	};
+	pi.registerTool(
+		makeContactPeerTool(bus, handle, {
+			listPeers: () => refreshPeers(),
+		}),
+	);
+
+	// Inbound `deliver` — a supervisor `intercom send` or a sibling's `contact_peer` send.
+	// Fenced (untrusted text crossing a process boundary), attribution OUTSIDE the fence —
+	// exactly the in-process delivery bridge's rule (`engine/inproc.ts`).
+	client.onDeliver((evt: DeliverEvent) => {
+		const from = evt.from === SUPERVISOR_HANDLE ? "your supervisor" : `peer ${evt.fromLabel ?? evt.from}`;
+		sendFollowUp(pi, attributeInbound(from, evt.text));
+	});
+
+	// Inbound `steer` — the supervisor's own live redirect (`intercom steer` / f9 `s`), queued
+	// as a follow-up turn (cross-process steer is follow-up semantics, not mid-turn injection —
+	// spec B4). NOT fenced: this is the supervisor speaking, the same as the in-process
+	// engine's `onSteerable`, which injects steer text unfenced.
+	client.onSteer((text) => {
+		const trimmed = text.trim();
+		if (!trimmed) return;
+		sendFollowUp(pi, `[steer from your supervisor]\n${trimmed}`);
+	});
+
+	// A live connection that drops (host teardown/crash) must not keep reporting "delivered":
+	// flip the bus offline so progress says "dropped" and asks fail fast as "unavailable".
+	client.onClose(() => {
+		bus.connected = false;
+		try {
+			ctx.ui.setStatus("persona-bridge", "⇄ offline");
+		} catch {
+			/* cosmetic */
+		}
+	});
+
+	bridgeReady = client.register().then(
+		() => {
+			bus.connected = true;
+			refreshPeers();
+			try {
+				ctx.ui.setStatus("persona-bridge", `⇄ ${handle}`);
+			} catch {
+				/* cosmetic */
+			}
+		},
+		() => {
+			// Capped retries exhausted (host gone, or a race on a just-spawned child) — degrade to
+			// a mute executor and keep running; never crash, never hang (spec §4).
+			if (env.PI_PERSONA_DEBUG) process.stderr.write(`[pi-persona] bridge: could not connect to ${endpoint}\n`);
+			try {
+				ctx.ui.setStatus("persona-bridge", "⇄ offline");
+			} catch {
+				/* cosmetic */
+			}
+		},
+	);
+
+	pi.on("session_shutdown", () => {
+		client.close();
+	});
+}

package/src/bus/broker/client.ts

@@ -0,0 +1,379 @@
+/**
+ * Broker client — the child-side half of the relay (spec B3/B6): connects to the
+ * session-scoped endpoint (`paths.ts`), performs the `register`/`registered` handshake,
+ * and exposes the same shape a local `contact_supervisor`/`contact_peer` binding needs —
+ * `send` (fire-and-forget), `ask` (a blocking `send{expectsReply}` correlated to a
+ * `replied{askId}`, 10-minute cap, mirrors `bus.ask`, and sends `cancel{msgId}` when
+ * aborted), `reply` (answers a host-issued
+ * blocking `deliver`), `list` (the engine-scoped peer roster, B7), and `onDeliver`/`onSteer`
+ * for inbound frames. A future bridge (`src/bridge.ts`) wires these onto Pi tools; this
+ * module has no Pi imports.
+ *
+ * Ported from comtac `broker/client.ts`, slimmed to the B6 frame set and to what a
+ * per-session child — which lives strictly less than the run — actually needs: capped
+ * exponential backoff (250ms–5s) on the INITIAL connect only (comtac's presence tracking,
+ * roster cache, and endless reconnect-after-disconnect "storm" are dropped — YAGNI here,
+ * see spec B6/Task 4 brief). An unexpected disconnect (host died
+ * mid-run) is NOT auto-reconnected: sends silently go nowhere, while in-flight asks/lists
+ * reject promptly and clean up their timers — the child keeps executing, mute, never crashing.
+ *
+ * Pure over an injected socket factory (`net`), mirroring `host.ts`'s `net` param — same
+ * transport-injection seam, opposite side of the same fake in tests.
+ */
+
+import { randomUUID } from "node:crypto";
+import nodeNet from "node:net";
+import type net from "node:net";
+
+import { createFrameReader, encodeFrame } from "./framing.ts";
+import { type Frame, isFrame } from "./messages.ts";
+import type { MsgKind } from "../inproc.ts";
+
+export interface DeliverEvent {
+	from: string;
+	fromLabel?: string;
+	kind: MsgKind;
+	text: string;
+	msgId: string;
+	expectsReply: boolean;
+}
+
+export interface BrokerClient {
+	/** Connect (capped backoff) and complete the register handshake. */
+	register(): Promise<void>;
+	/** Fire-and-forget; a dead connection silently drops it (spec: "sends report undelivered"). */
+	send(to: string, kind: MsgKind, text: string): void;
+	/** Blocking request; resolves on a matching `replied`, rejects on `signal` abort or the
+	 *  10-minute cap (mirrors `bus.ask`'s default). */
+	ask(to: string, kind: MsgKind, text: string, signal?: AbortSignal): Promise<string>;
+	/** Answers a host-issued blocking `deliver` (the supervisor asked THIS child). */
+	reply(askId: string, text: string): void;
+	list(): Promise<Array<{ handle: string; label: string }>>;
+	onDeliver(cb: (evt: DeliverEvent) => void): void;
+	onSteer(cb: (text: string) => void): void;
+	/** Fired once when a live connection drops (peer-initiated); not fired by close(). */
+	onClose(cb: () => void): void;
+	/** Sends `bye` (best-effort) and disposes the socket; idempotent. */
+	close(): void;
+}
+
+export interface MakeBrokerClientDeps {
+	endpoint: string;
+	handle: string;
+	label?: string;
+	group?: string;
+	peers?: boolean;
+	/** Injected transport (tests use a paired in-memory fake); defaults to real `node:net`. */
+	net?: typeof import("node:net");
+}
+
+const RECONNECT_BASE_MS = 250;
+const RECONNECT_MAX_MS = 5000;
+const CONNECT_MAX_ATTEMPTS = 6;
+const ASK_TIMEOUT_MS = 600_000;
+// A roster lookup is one local socket/pipe round-trip, unlike a blocking supervisor ask. Do not
+// let a half-open broker pin `contact_peer list/send` until the child idle watchdog fires.
+const LIST_TIMEOUT_MS = 10_000;
+
+function delay(ms: number): Promise<void> {
+	return new Promise((resolve) => {
+		const t = setTimeout(resolve, ms);
+		t.unref?.();
+	});
+}
+
+export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
+	const netImpl = deps.net ?? nodeNet;
+
+	let socket: net.Socket | undefined;
+	let closed = false;
+	let disconnected = false;
+	let registerSettle: { resolve: () => void; reject: (err: Error) => void } | undefined;
+
+	const deliverListeners = new Set<(evt: DeliverEvent) => void>();
+	const steerListeners = new Set<(text: string) => void>();
+	const closeListeners = new Set<() => void>();
+	const pendingAsks = new Map<string, { resolve: (text: string) => void; reject: (err: Error) => void }>();
+	const pendingLists = new Map<string, { resolve: (peers: Array<{ handle: string; label: string }>) => void; reject: (err: Error) => void }>();
+
+	/** Best-effort write: a frame sent while disconnected is silently dropped — matches
+	 *  the design's "sends report undelivered" (no throw the caller could even act on,
+	 *  `send`/`reply` are `void`). */
+	function write(frame: Frame): void {
+		if (!socket) return;
+		try {
+			socket.write(encodeFrame(frame));
+		} catch {
+			/* peer went away mid-write */
+		}
+	}
+
+	/** An application listener's throw must never reach the frame reader: the reader would
+	 *  poison itself and destroy the socket, muting the child for the rest of the run (the
+	 *  host hardens its own dispatch the same way). */
+	function safely(fn: () => void): void {
+		try {
+			fn();
+		} catch {
+			/* a faulty listener is the listener's problem, not the connection's */
+		}
+	}
+
+	function handleFrame(frame: Frame): void {
+		switch (frame.t) {
+			case "registered":
+				registerSettle?.resolve();
+				registerSettle = undefined;
+				return;
+			case "error":
+				// A correlated error belongs to one request on this connection. Do not let an
+				// unknown/stale correlation id affect the register handshake or another ask.
+				if (frame.msgId !== undefined) {
+					pendingAsks.get(frame.msgId)?.reject(new Error(frame.reason));
+					return;
+				}
+				// A bare error is reserved for the register handshake. Older hosts emit this
+				// shape, so keep accepting it for protocol compatibility.
+				registerSettle?.reject(new Error(frame.reason));
+				registerSettle = undefined;
+				return;
+			case "deliver": {
+				const evt: DeliverEvent = {
+					from: frame.from,
+					kind: frame.kind,
+					text: frame.text,
+					msgId: frame.msgId,
+					expectsReply: frame.expectsReply,
+					...(frame.fromLabel !== undefined ? { fromLabel: frame.fromLabel } : {}),
+				};
+				for (const cb of deliverListeners) safely(() => cb(evt));
+				return;
+			}
+			case "steer":
+				for (const cb of steerListeners) safely(() => cb(frame.text));
+				return;
+			case "replied": {
+				const pending = pendingAsks.get(frame.askId);
+				if (pending) pending.resolve(frame.text);
+				return;
+			}
+			case "peers": {
+				const pending = pendingLists.get(frame.reqId);
+				if (pending) pending.resolve(frame.peers);
+				return;
+			}
+			default:
+				return; // register/send/reply/list/bye are client→host-only; ignore if echoed
+		}
+	}
+
+	function connectOnce(): Promise<net.Socket> {
+		return new Promise((resolve, reject) => {
+			const s = netImpl.connect(deps.endpoint);
+			let settled = false;
+			const onConnect = (): void => {
+				if (settled) return;
+				settled = true;
+				s.removeListener("error", onError);
+				resolve(s);
+			};
+			const onError = (err: Error): void => {
+				if (settled) return;
+				settled = true;
+				s.removeListener("connect", onConnect);
+				s.destroy();
+				reject(err);
+			};
+			s.once("connect", onConnect);
+			s.once("error", onError);
+		});
+	}
+
+	/** Capped exponential backoff (250ms → 5s) on the INITIAL connect only — comtac's
+	 *  endless reconnect-after-disconnect loop is deliberately not ported (see header). */
+	async function connectWithBackoff(): Promise<net.Socket> {
+		let lastErr: unknown;
+		for (let attempt = 0; attempt < CONNECT_MAX_ATTEMPTS; attempt += 1) {
+			if (closed) throw new Error("broker client closed");
+			try {
+				return await connectOnce();
+			} catch (err) {
+				lastErr = err;
+				if (attempt < CONNECT_MAX_ATTEMPTS - 1) {
+					await delay(Math.min(RECONNECT_BASE_MS * 2 ** attempt, RECONNECT_MAX_MS));
+				}
+			}
+		}
+		throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+	}
+
+	function rejectAllPending(reason: string): void {
+		for (const p of pendingAsks.values()) p.reject(new Error(reason));
+		pendingAsks.clear();
+		for (const p of pendingLists.values()) p.reject(new Error(reason));
+		pendingLists.clear();
+	}
+
+	async function register(): Promise<void> {
+		const s = await connectWithBackoff();
+		if (closed) {
+			s.destroy();
+			throw new Error("broker client closed");
+		}
+		socket = s;
+		s.on(
+			"data",
+			createFrameReader(
+				(raw) => {
+					if (isFrame(raw)) handleFrame(raw);
+				},
+				() => s.destroy(),
+			),
+		);
+		s.on("error", () => {
+			/* The close event rejects in-flight requests; this listener only prevents an
+			 * unhandled socket error from taking down the child. */
+		});
+		s.once("close", () => {
+			socket = undefined;
+			// A peer-initiated drop (host teardown/crash) between connect and the handshake
+			// reply would otherwise leave register() pending for the child's whole life.
+			registerSettle?.reject(new Error("connection closed during register"));
+			registerSettle = undefined;
+			if (!closed) {
+				rejectAllPending("broker connection closed");
+				disconnected = true;
+				for (const cb of closeListeners) safely(cb);
+			}
+		});
+
+		return new Promise<void>((resolve, reject) => {
+			registerSettle = { resolve, reject };
+			write({
+				t: "register",
+				handle: deps.handle,
+				...(deps.label !== undefined ? { label: deps.label } : {}),
+				...(deps.group !== undefined ? { group: deps.group } : {}),
+				...(deps.peers !== undefined ? { peers: deps.peers } : {}),
+			});
+		});
+	}
+
+	function send(to: string, kind: MsgKind, text: string): void {
+		write({ t: "send", to, kind, text, msgId: randomUUID(), expectsReply: false });
+	}
+
+	/** Why `ask`/`list` refuse to send right now — distinguishes a disposed client from one that
+	 *  merely lost its connection (an unexpected disconnect is never auto-reconnected; see header). */
+	function unavailableReason(): string {
+		return closed ? "broker client closed" : "broker connection closed";
+	}
+
+	function ask(to: string, kind: MsgKind, text: string, signal?: AbortSignal): Promise<string> {
+		if (closed || disconnected) return Promise.reject(new Error(unavailableReason()));
+		const msgId = randomUUID();
+		return new Promise<string>((resolve, reject) => {
+			let timer: ReturnType<typeof setTimeout>;
+			const onAbort = (): void => {
+				const wasPending = pendingAsks.has(msgId);
+				finish();
+				if (wasPending) write({ t: "cancel", msgId });
+				reject(new Error("ask aborted"));
+			};
+			// Always drop the pending entry + timer + abort listener, so a settled ask never
+			// leaks a 10-minute timer or a stale resolver (mirrors `bus.ask`'s `finish`).
+			const finish = (): void => {
+				clearTimeout(timer);
+				pendingAsks.delete(msgId);
+				signal?.removeEventListener("abort", onAbort);
+			};
+			timer = setTimeout(() => {
+				const wasPending = pendingAsks.has(msgId);
+				finish();
+				if (wasPending) write({ t: "cancel", msgId });
+				reject(new Error(`ask timeout after ${ASK_TIMEOUT_MS}ms`));
+			}, ASK_TIMEOUT_MS);
+			timer.unref?.();
+			if (signal) {
+				if (signal.aborted) {
+					finish();
+					reject(new Error("ask aborted"));
+					return;
+				}
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+			pendingAsks.set(msgId, {
+				resolve: (text: string) => {
+					finish();
+					resolve(text);
+				},
+				reject: (err: Error) => {
+					finish();
+					reject(err);
+				},
+			});
+			write({ t: "send", to, kind, text, msgId, expectsReply: true });
+		});
+	}
+
+	function reply(askId: string, text: string): void {
+		write({ t: "reply", askId, text });
+	}
+
+	function list(): Promise<Array<{ handle: string; label: string }>> {
+		if (closed || disconnected) return Promise.reject(new Error(unavailableReason()));
+		const reqId = randomUUID();
+		return new Promise((resolve, reject) => {
+			let timer: ReturnType<typeof setTimeout>;
+			const finish = (): void => {
+				clearTimeout(timer);
+				pendingLists.delete(reqId);
+			};
+			pendingLists.set(reqId, {
+				resolve: (peers) => { finish(); resolve(peers); },
+				reject: (err) => { finish(); reject(err); },
+			});
+			timer = setTimeout(() => {
+				finish();
+				reject(new Error(`list timeout after ${LIST_TIMEOUT_MS}ms`));
+			}, LIST_TIMEOUT_MS);
+			timer.unref?.();
+			write({ t: "list", reqId });
+		});
+	}
+
+	function onDeliver(cb: (evt: DeliverEvent) => void): void {
+		deliverListeners.add(cb);
+	}
+
+	function onSteer(cb: (text: string) => void): void {
+		steerListeners.add(cb);
+	}
+
+	function onClose(cb: () => void): void {
+		closeListeners.add(cb);
+	}
+
+	function close(): void {
+		if (closed) return;
+		closed = true;
+		const s = socket;
+		if (s) {
+			write({ t: "bye" });
+			// Capture + clear before end()/destroy(): a `close` event can fire
+			// SYNCHRONOUSLY (real sockets are async, but a fake — or a socket that is
+			// already half-closed — is not), which would otherwise null `socket` via the
+			// `once("close", …)` listener mid-call.
+			socket = undefined;
+			s.end();
+			s.destroy();
+		}
+		// A `register()` still mid-flight (connecting, or connected but awaiting
+		// `registered`/`error`) would otherwise hang forever — settle it too.
+		registerSettle?.reject(new Error("broker client closed"));
+		registerSettle = undefined;
+		rejectAllPending("broker client closed");
+	}
+
+	return { register, send, ask, reply, list, onDeliver, onSteer, onClose, close };
+}

package/src/bus/broker/framing.ts

@@ -0,0 +1,43 @@
+/**
+ * Length-prefixed JSON framing (ported from pi-subagents-comtac): a 4-byte big-endian
+ * length header + a UTF-8 JSON payload. A reader accumulates chunks, emits complete frames
+ * greedily, caps a single frame at 16 MiB (DoS guard), and POISONS itself on the first
+ * error (oversize / bad JSON) — the caller destroys the socket. Pure, identical on all OSes.
+ */
+
+const MAX_FRAME_BYTES = 16 * 1024 * 1024;
+
+export function encodeFrame(obj: unknown): Buffer {
+	const body = Buffer.from(JSON.stringify(obj), "utf8");
+	const head = Buffer.alloc(4);
+	head.writeUInt32BE(body.length, 0);
+	return Buffer.concat([head, body]);
+}
+
+export function createFrameReader(onFrame: (obj: unknown) => void, onError: (e: Error) => void): (chunk: Buffer) => void {
+	let buf: Buffer = Buffer.alloc(0);
+	let poisoned = false;
+	return (chunk: Buffer): void => {
+		if (poisoned) return;
+		buf = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
+		for (;;) {
+			if (buf.length < 4) return;
+			const len = buf.readUInt32BE(0);
+			if (len > MAX_FRAME_BYTES) {
+				poisoned = true;
+				onError(new Error(`broker frame too large (${len} bytes)`));
+				return;
+			}
+			if (buf.length < 4 + len) return;
+			const body = buf.subarray(4, 4 + len);
+			buf = buf.subarray(4 + len);
+			try {
+				onFrame(JSON.parse(body.toString("utf8")));
+			} catch (e) {
+				poisoned = true;
+				onError(e instanceof Error ? e : new Error(String(e)));
+				return;
+			}
+		}
+	};
+}