@iowarp/clio-coder 0.3.0 → 0.3.2

package/src/worker/stdin-demux.ts

@@ -0,0 +1,316 @@
+import {
+	type AgentLedgerEntry,
+	parseAgentLedgerEntry,
+	WORKER_STDIN_FRAME_MAX_BYTES,
+	withinFrameBudget,
+} from "./protocol.js";
+import { parseWorkerSpec, type WorkerSpec } from "./spec-contract.js";
+
+export interface WorkerStdinDemux {
+	feed(chunk: string): void;
+	eof(): void;
+	readSpec(): Promise<WorkerSpec>;
+	/**
+	 * Register the handler for post-spec steer lines
+	 * (`{"type":"steer","text":"...","sequence":1}`). The sequence is assigned by
+	 * the parent and is what lets `clio_steer_received` acknowledge one exact
+	 * receipt entry, so a line without a positive integer sequence is dropped
+	 * rather than delivered unattributed. Steers that arrive before registration
+	 * are buffered in order and flushed to the handler. Single handler; a second
+	 * registration replaces the first.
+	 */
+	onSteer(handler: (steer: WorkerSteerMessage) => void): void;
+	/**
+	 * Register the handler for post-spec permission-decision lines
+	 * (`{"type":"permission_decision","requestId":"...","decision":"approve"|"deny"}`).
+	 * Decisions that arrive before registration are buffered in order and
+	 * flushed. Single handler; a second registration replaces the first.
+	 */
+	onPermissionDecision(handler: (decision: { requestId: string; decision: "approve" | "deny" }) => void): void;
+	/**
+	 * Register the handler for agent-ledger delta lines
+	 * (`{"type":"ledger_delta","entries":[...]}`). The orchestrator replays the
+	 * full board on subscription, which can land before the runtime wires its
+	 * handler, so batches that arrive early are buffered in order and flushed.
+	 * Single handler; a second registration replaces the first.
+	 */
+	onLedgerDelta(handler: (entries: ReadonlyArray<AgentLedgerEntry>) => void): void;
+	/** Post-spec lines that were not valid steer or permission-decision messages. */
+	droppedLineCount(): number;
+	/**
+	 * Register the handler for the control channel closing after the spec was
+	 * received (parent exit, SSH channel drop). Fires at most once; if the
+	 * channel already closed the handler is invoked immediately. The pre-spec
+	 * close case stays a readSpec() rejection, not a channel-close event.
+	 */
+	onChannelClose(handler: () => void): void;
+}
+
+export interface WorkerSteerMessage {
+	text: string;
+	/** Parent-assigned receipt-provenance sequence for exact acknowledgement. */
+	sequence: number;
+}
+
+/**
+ * Preserve stdin order while a runtime accepts guidance asynchronously.
+ * `clio_steer_received` echoes the parent-assigned sequence, so an
+ * acknowledgement closes out one exact receipt entry. Ordering still matters
+ * for the runtime itself: a later steer must never reach it ahead of an earlier
+ * pending one, or the guidance arrives out of the order the operator sent it.
+ */
+export function createOrderedSteerHandler(
+	deliver: (text: string) => boolean | Promise<boolean>,
+	onAccepted: (steer: WorkerSteerMessage) => void,
+	onRejected: (reason: string) => void,
+): (steer: WorkerSteerMessage) => Promise<void> {
+	let tail = Promise.resolve();
+	return (steer: WorkerSteerMessage): Promise<void> => {
+		tail = tail.then(async () => {
+			let rejection: string | null = null;
+			try {
+				if (await deliver(steer.text)) onAccepted(steer);
+				else rejection = "runtime does not accept live guidance";
+			} catch (error) {
+				rejection = error instanceof Error ? error.message : String(error);
+			}
+			if (rejection !== null) {
+				try {
+					onRejected(rejection);
+				} catch {
+					// Diagnostics cannot be allowed to poison subsequent delivery.
+				}
+			}
+		});
+		return tail;
+	};
+}
+
+export function createWorkerStdinDemux(): WorkerStdinDemux {
+	let buffer = "";
+	let specResolve: ((spec: WorkerSpec) => void) | null = null;
+	let specReject: ((err: Error) => void) | null = null;
+	let specValue: WorkerSpec | null = null;
+	let specError: Error | null = null;
+	let specReceived = false;
+	let closed = false;
+	let steerHandler: ((steer: WorkerSteerMessage) => void) | null = null;
+	const pendingSteers: WorkerSteerMessage[] = [];
+	let permissionHandler: ((decision: { requestId: string; decision: "approve" | "deny" }) => void) | null = null;
+	const pendingPermissionDecisions: Array<{ requestId: string; decision: "approve" | "deny" }> = [];
+	let ledgerDeltaHandler: ((entries: ReadonlyArray<AgentLedgerEntry>) => void) | null = null;
+	const pendingLedgerDeltas: Array<ReadonlyArray<AgentLedgerEntry>> = [];
+	let droppedLines = 0;
+	let channelCloseHandler: (() => void) | null = null;
+	let channelCloseDelivered = false;
+	let channelClosedAfterSpec = false;
+
+	function deliverChannelClose(): void {
+		if (channelCloseDelivered || channelCloseHandler === null) return;
+		channelCloseDelivered = true;
+		channelCloseHandler();
+	}
+
+	function resolveSpec(spec: WorkerSpec): void {
+		specValue = spec;
+		specResolve?.(spec);
+	}
+
+	function rejectSpec(err: Error): void {
+		specError = err;
+		specReject?.(err);
+	}
+
+	function deliverSteer(steer: WorkerSteerMessage): void {
+		if (steerHandler) {
+			steerHandler(steer);
+			return;
+		}
+		pendingSteers.push(steer);
+	}
+
+	function deliverPermissionDecision(requestId: string, decision: "approve" | "deny"): void {
+		if (permissionHandler) {
+			permissionHandler({ requestId, decision });
+			return;
+		}
+		pendingPermissionDecisions.push({ requestId, decision });
+	}
+
+	function deliverLedgerDelta(entries: ReadonlyArray<AgentLedgerEntry>): void {
+		if (ledgerDeltaHandler) {
+			ledgerDeltaHandler(entries);
+			return;
+		}
+		pendingLedgerDeltas.push(entries);
+	}
+
+	function processPostSpecLine(line: string): void {
+		let value: unknown;
+		try {
+			value = JSON.parse(line);
+		} catch {
+			droppedLines += 1;
+			return;
+		}
+		if (
+			typeof value === "object" &&
+			value !== null &&
+			(value as { type?: unknown }).type === "steer" &&
+			typeof (value as { text?: unknown }).text === "string" &&
+			(value as { text: string }).text.trim().length > 0 &&
+			Number.isSafeInteger((value as { sequence?: unknown }).sequence) &&
+			Number((value as { sequence: number }).sequence) > 0
+		) {
+			deliverSteer({
+				text: (value as { text: string }).text,
+				sequence: (value as { sequence: number }).sequence,
+			});
+			return;
+		}
+		if (
+			typeof value === "object" &&
+			value !== null &&
+			(value as { type?: unknown }).type === "permission_decision" &&
+			typeof (value as { requestId?: unknown }).requestId === "string" &&
+			(value as { requestId: string }).requestId.length > 0 &&
+			((value as { decision?: unknown }).decision === "approve" || (value as { decision?: unknown }).decision === "deny")
+		) {
+			deliverPermissionDecision(
+				(value as { requestId: string }).requestId,
+				(value as { decision: "approve" | "deny" }).decision,
+			);
+			return;
+		}
+		if (typeof value === "object" && value !== null && (value as { type?: unknown }).type === "ledger_delta") {
+			const raw = (value as { entries?: unknown }).entries;
+			if (!Array.isArray(raw)) {
+				droppedLines += 1;
+				return;
+			}
+			const entries: AgentLedgerEntry[] = [];
+			for (const candidate of raw) {
+				const entry = parseAgentLedgerEntry(candidate);
+				if (entry !== null) entries.push(entry);
+			}
+			if (entries.length === 0) {
+				droppedLines += 1;
+				return;
+			}
+			deliverLedgerDelta(entries);
+			return;
+		}
+		droppedLines += 1;
+	}
+
+	function processLine(line: string): void {
+		if (line.length === 0) return;
+		// The byte ceiling is checked before JSON.parse so an oversized or
+		// adversarial line costs a length comparison, not a parse and an
+		// allocation proportional to its size.
+		if (!withinFrameBudget(line, WORKER_STDIN_FRAME_MAX_BYTES)) {
+			if (!specReceived) {
+				specReceived = true;
+				rejectSpec(new Error(`WorkerSpec line exceeds the ${WORKER_STDIN_FRAME_MAX_BYTES} byte stdin frame limit`));
+				return;
+			}
+			droppedLines += 1;
+			return;
+		}
+		if (!specReceived) {
+			specReceived = true;
+			try {
+				resolveSpec(parseWorkerSpec(JSON.parse(line)));
+			} catch (err) {
+				rejectSpec(err instanceof Error ? err : new Error(String(err)));
+			}
+			return;
+		}
+		processPostSpecLine(line);
+	}
+
+	/**
+	 * Discard an unterminated run that already exceeds the frame ceiling. A peer
+	 * that never sends a newline cannot grow this buffer without bound; the
+	 * oversized remainder is dropped up to the next newline.
+	 */
+	let discardingOversizedLine = false;
+
+	return {
+		feed(chunk: string): void {
+			if (closed) return;
+			buffer += chunk;
+			let idx = buffer.indexOf("\n");
+			while (idx >= 0) {
+				const line = buffer.slice(0, idx);
+				buffer = buffer.slice(idx + 1);
+				if (discardingOversizedLine) {
+					discardingOversizedLine = false;
+					droppedLines += 1;
+				} else {
+					processLine(line);
+				}
+				idx = buffer.indexOf("\n");
+			}
+			if (!withinFrameBudget(buffer, WORKER_STDIN_FRAME_MAX_BYTES)) {
+				if (!specReceived) {
+					specReceived = true;
+					rejectSpec(new Error(`WorkerSpec line exceeds the ${WORKER_STDIN_FRAME_MAX_BYTES} byte stdin frame limit`));
+				}
+				buffer = "";
+				discardingOversizedLine = true;
+			}
+		},
+		eof(): void {
+			if (closed) return;
+			closed = true;
+			if (buffer.length > 0) {
+				processLine(buffer);
+				buffer = "";
+			}
+			if (!specReceived) {
+				rejectSpec(new Error("worker stdin closed before spec received"));
+				return;
+			}
+			channelClosedAfterSpec = true;
+			deliverChannelClose();
+		},
+		readSpec(): Promise<WorkerSpec> {
+			if (specValue) return Promise.resolve(specValue);
+			if (specError) return Promise.reject(specError);
+			if (closed && !specReceived) return Promise.reject(new Error("worker stdin closed before spec received"));
+			return new Promise((resolve, reject) => {
+				specResolve = resolve;
+				specReject = reject;
+			});
+		},
+		onSteer(handler: (steer: WorkerSteerMessage) => void): void {
+			steerHandler = handler;
+			while (pendingSteers.length > 0) {
+				const steer = pendingSteers.shift();
+				if (steer !== undefined) handler(steer);
+			}
+		},
+		onPermissionDecision(handler: (decision: { requestId: string; decision: "approve" | "deny" }) => void): void {
+			permissionHandler = handler;
+			while (pendingPermissionDecisions.length > 0) {
+				const entry = pendingPermissionDecisions.shift();
+				if (entry !== undefined) handler(entry);
+			}
+		},
+		onLedgerDelta(handler: (entries: ReadonlyArray<AgentLedgerEntry>) => void): void {
+			ledgerDeltaHandler = handler;
+			while (pendingLedgerDeltas.length > 0) {
+				const batch = pendingLedgerDeltas.shift();
+				if (batch !== undefined) handler(batch);
+			}
+		},
+		droppedLineCount(): number {
+			return droppedLines;
+		},
+		onChannelClose(handler: () => void): void {
+			channelCloseHandler = handler;
+			if (channelClosedAfterSpec) deliverChannelClose();
+		},
+	};
+}

package/dist/acp-UMLFVA3F.js

@@ -1,92 +0,0 @@
-import {
-  restoreStdout,
-  runClioCommand,
-  takeOverStdout,
-  writeRawStdout
-} from "./chunk-PS4PFJQP.js";
-import "./chunk-AMFR5YA3.js";
-import "./chunk-O4EJEDHO.js";
-import "./chunk-4UQA7NCT.js";
-import "./chunk-3DANZDGR.js";
-import "./chunk-JPOWPFCU.js";
-import "./chunk-NI4DEJMC.js";
-import "./chunk-7RBKDI66.js";
-import "./chunk-527KG6XR.js";
-import "./chunk-UU3R62TT.js";
-import "./chunk-6CWDTGUC.js";
-import "./chunk-BYEU76JP.js";
-import "./chunk-HMYNFFY4.js";
-import "./chunk-UWIJNAOB.js";
-import "./chunk-X3BR7HWV.js";
-import "./chunk-VOO7NYPP.js";
-import "./chunk-GNGDQYDU.js";
-import "./chunk-2J63S4SF.js";
-import "./chunk-RQDWMVRB.js";
-import "./chunk-7BHLZB3A.js";
-import "./chunk-TPOCL34A.js";
-import "./chunk-E3NYWENM.js";
-import "./chunk-XV4ZJ6ZM.js";
-import "./chunk-26BZQOAD.js";
-import "./chunk-WD6AJM35.js";
-import "./chunk-QV47YRF4.js";
-import "./chunk-CLJ5HLUD.js";
-import "./chunk-BBUH4VAA.js";
-import "./chunk-GOTUR54M.js";
-import "./chunk-KBR4MZZR.js";
-import "./chunk-XNISANGE.js";
-import "./chunk-KKKPTZLM.js";
-import "./chunk-ME6DNWIU.js";
-import "./chunk-262G75JS.js";
-import "./chunk-TFSSEXL6.js";
-import "./chunk-PIDUD6M2.js";
-import {
-  printError
-} from "./chunk-67MTHP2E.js";
-import "./chunk-TKHQ4DGZ.js";
-import "./chunk-D5YD55AR.js";
-import "./chunk-JWHCJDCI.js";
-import "./chunk-UHTSULZS.js";
-import "./chunk-5LDRNKX2.js";
-import "./chunk-UGYAX5YI.js";
-import "./chunk-5N2FG33Q.js";
-import "./chunk-VPAWTYLY.js";
-import "./chunk-X3NE4WVW.js";
-import "./chunk-DXQNI4PC.js";
-
-// src/cli/acp.ts
-var HELP = `clio-coder acp
-
-Serve Clio Coder as an Agent Client Protocol v1 agent over stdio.
-
-This command is intended for ACP frontends to spawn. Interactive delegation remains
-available through /agents, /delegate, the dispatch board, and receipts.
-`;
-async function runAcpCommand(args, options = {}) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(HELP);
-    return 0;
-  }
-  if (args.length > 0) {
-    printError(`unknown clio-coder acp option: ${args[0] ?? ""}`);
-    process.stdout.write(HELP);
-    return 2;
-  }
-  takeOverStdout();
-  try {
-    return await runClioCommand({
-      ...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
-      ...options.noContextFiles ? { noContextFiles: true } : {},
-      ...options.noSkills ? { noSkills: true } : {},
-      ...options.skillPaths && options.skillPaths.length > 0 ? { skillPaths: options.skillPaths } : {},
-      acp: {
-        transportOptions: { write: writeRawStdout }
-      }
-    });
-  } finally {
-    restoreStdout();
-  }
-}
-export {
-  runAcpCommand
-};
-//# sourceMappingURL=acp-UMLFVA3F.js.map

package/dist/chunk-262G75JS.js

@@ -1,35 +0,0 @@
-// src/domains/providers/probe/fingerprint.ts
-async function fetchWithTimeout(url, timeoutMs) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, { signal: controller.signal });
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-async function fingerprintNativeRuntime(baseUrl) {
-  const trimmed = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
-  const lmStudioV1 = await fetchWithTimeout(`${trimmed}/api/v1/models`, 750);
-  if (lmStudioV1?.ok) return { runtimeId: "lmstudio-native", displayName: "LM Studio" };
-  const lmStudioV0 = await fetchWithTimeout(`${trimmed}/api/v0/models`, 750);
-  if (lmStudioV0?.ok) return { runtimeId: "lmstudio-native", displayName: "LM Studio" };
-  const ollama = await fetchWithTimeout(`${trimmed}/api/version`, 750);
-  if (ollama?.ok) {
-    try {
-      const data = await ollama.json();
-      if (typeof data.version === "string") {
-        return { runtimeId: "ollama-native", displayName: "Ollama" };
-      }
-    } catch {
-    }
-  }
-  return null;
-}
-
-export {
-  fingerprintNativeRuntime
-};
-//# sourceMappingURL=chunk-262G75JS.js.map

package/dist/chunk-6CWDTGUC.js

@@ -1,20 +0,0 @@
-// src/core/boot-trace.ts
-var BOOT_TRACE_ENV = "CLIO_CODER_TRACE_BOOT";
-function isBootTraceEnabled() {
-  return process.env[BOOT_TRACE_ENV] === "1";
-}
-function traceBoot(phase, detail) {
-  if (!isBootTraceEnabled()) return;
-  try {
-    const elapsedMs = performance.now();
-    const suffix = detail !== void 0 && detail.length > 0 ? ` (${detail})` : "";
-    process.stderr.write(`[clio:boot] +${elapsedMs.toFixed(1)}ms ${phase}${suffix}
-`);
-  } catch {
-  }
-}
-
-export {
-  traceBoot
-};
-//# sourceMappingURL=chunk-6CWDTGUC.js.map