open-multi-agent-kit 0.99.0 → 1.0.0

package/examples/extensions/subagent/managed-process.ts

@@ -6,11 +6,12 @@ import {
 	spawn,
 } from "node:child_process";
 import type { Readable } from "node:stream";
+import { processGroupState, signalProcessTree } from "./managed-process-tree.ts";
 
 type ManagedChild = ChildProcessByStdio<null, Readable, Readable>;
 type ManagedSpawnOptions = SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>;
 
-export type ManagedProcessReason = "completed" | "cutoff" | "aborted" | "spawn-error";
+export type ManagedProcessReason = "completed" | "cutoff" | "aborted" | "spawn-error" | "signal" | "callback-error";
 
 export interface ManagedProcessCleanup {
 	readonly termSent: boolean;
@@ -25,6 +26,10 @@ export interface ManagedProcessResult {
 	readonly reason: ManagedProcessReason;
 	readonly elapsedMs: number;
 	readonly cleanup: ManagedProcessCleanup;
+	/** Snapshot at response time. False means the owner must retain its reservation. */
+	readonly terminationObserved: boolean;
+	/** Resolves only on confirmed termination or confirmed failure to start, never on a timeout. */
+	readonly settlement: Promise<void>;
 	readonly errorMessage?: string;
 }
 
@@ -41,17 +46,13 @@ export interface RunManagedProcessOptions {
 	readonly spawnProcess?: (command: string, args: readonly string[], options: ManagedSpawnOptions) => ManagedChild;
 }
 
-const DEFAULT_TERMINATION_GRACE_MS = 1_500;
-const DEFAULT_FORCE_SETTLE_MS = 2_000;
-
 export async function runManagedProcess(options: RunManagedProcessOptions): Promise<ManagedProcessResult> {
-	const startedAtMs = Date.now();
+	const startedAtMs = performance.now();
 	const processGroup = process.platform !== "win32";
 	if (options.signal?.aborted) return withoutChild("aborted", startedAtMs, processGroup);
-	const spawnProcess = options.spawnProcess ?? defaultSpawn;
 	let child: ManagedChild;
 	try {
-		child = spawnProcess(options.command, options.args, {
+		child = (options.spawnProcess ?? defaultSpawn)(options.command, options.args, {
 			cwd: options.cwd,
 			shell: false,
 			stdio: ["ignore", "pipe", "pipe"],
@@ -67,99 +68,114 @@ export async function runManagedProcess(options: RunManagedProcessOptions): Prom
 		);
 	}
 	const pid = child.pid ?? -1;
+	let confirmSettlement: () => void = () => {};
+	const settlement = new Promise<void>((resolve) => {
+		confirmSettlement = resolve;
+	});
 
 	return await new Promise<ManagedProcessResult>((resolve) => {
-		let settled = false;
+		let responded = false;
+		let terminated = false;
+		let closeObserved = false;
+		let exitCode: number | null = null;
+		let processSignal: NodeJS.Signals | null = null;
 		let reason: ManagedProcessReason = "completed";
 		let errorMessage: string | undefined;
 		let termSent = false;
 		let killSent = false;
 		let cutoffTimer: NodeJS.Timeout | undefined;
 		let escalationTimer: NodeJS.Timeout | undefined;
-		let forceSettleTimer: NodeJS.Timeout | undefined;
-
-		const cleanup = (): void => {
-			if (cutoffTimer !== undefined) clearTimeout(cutoffTimer);
-			if (escalationTimer !== undefined) clearTimeout(escalationTimer);
-			if (forceSettleTimer !== undefined) clearTimeout(forceSettleTimer);
+		let responseTimer: NodeJS.Timeout | undefined;
+		let observationTimer: NodeJS.Timeout | undefined;
+
+		const respond = (): void => {
+			if (responded) return;
+			responded = true;
+			if (cutoffTimer) clearTimeout(cutoffTimer);
+			if (responseTimer) clearTimeout(responseTimer);
 			options.signal?.removeEventListener("abort", onAbort);
-		};
-
-		const settle = (exitCode: number | null, processSignal: NodeJS.Signals | null): void => {
-			if (settled) return;
-			settled = true;
-			cleanup();
 			child.stdout.destroy();
 			child.stderr.destroy();
 			resolve({
 				pid,
-				exitCode: normalizeExitCode(exitCode, reason),
+				exitCode: normalizeExitCode(exitCode, reason, processSignal, terminated),
 				signal: processSignal,
 				reason,
-				elapsedMs: Date.now() - startedAtMs,
+				elapsedMs: performance.now() - startedAtMs,
 				cleanup: { termSent, killSent, processGroup },
+				terminationObserved: terminated,
+				settlement,
 				...(errorMessage === undefined ? {} : { errorMessage }),
 			});
 		};
-
-		const requestTermination = (nextReason: "cutoff" | "aborted"): void => {
-			if (settled || reason !== "completed") return;
-			reason = nextReason;
+		const confirm = (): void => {
+			if (terminated) return;
+			terminated = true;
+			if (escalationTimer) clearTimeout(escalationTimer);
+			if (observationTimer) clearTimeout(observationTimer);
+			confirmSettlement();
+			respond();
+		};
+		const observe = (): void => {
+			if (terminated || !closeObserved) return;
+			if (processGroupState(pid) === "gone") {
+				confirm();
+				return;
+			}
+			// After the cleanup deadline only observe: never send late signals to a reused PID.
+			observationTimer = setTimeout(observe, 25);
+			observationTimer.unref();
+		};
+		const startCleanup = (): void => {
+			if (terminated || termSent) return;
 			termSent = true;
 			signalProcessTree(child, "SIGTERM", processGroup);
-			const graceMs = Math.max(0, options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS);
+			const graceMs = Math.max(0, options.terminationGraceMs ?? 1_500);
 			escalationTimer = setTimeout(() => {
-				if (settled) return;
+				if (terminated) return;
 				killSent = true;
 				signalProcessTree(child, "SIGKILL", processGroup);
 			}, graceMs);
-			forceSettleTimer = setTimeout(
-				() => settle(null, null),
-				graceMs + Math.max(1, options.forceSettleMs ?? DEFAULT_FORCE_SETTLE_MS),
-			);
+			responseTimer = setTimeout(respond, graceMs + Math.max(1, options.forceSettleMs ?? 2_000));
+		};
+		const requestTermination = (nextReason: ManagedProcessReason): void => {
+			if (responded || terminated) return;
+			if (reason === "completed") reason = nextReason;
+			startCleanup();
 		};
-
 		function onAbort(): void {
 			requestTermination("aborted");
 		}
-
+		const deliver = (callback: ((chunk: string) => void) | undefined, chunk: string): void => {
+			if (responded || reason === "callback-error") return;
+			try {
+				callback?.(chunk);
+			} catch {
+				errorMessage = "process.output_callback_failed";
+				requestTermination("callback-error");
+			}
+		};
 		child.stdout.setEncoding("utf8");
 		child.stderr.setEncoding("utf8");
-		child.stdout.on("data", (chunk: string) => options.onStdout?.(chunk));
-		child.stderr.on("data", (chunk: string) => options.onStderr?.(chunk));
-		child.once("error", (error: Error) => {
-			if (reason === "completed") reason = "spawn-error";
+		child.stdout.on("data", (chunk: string) => deliver(options.onStdout, chunk));
+		child.stderr.on("data", (chunk: string) => deliver(options.onStderr, chunk));
+		child.on("error", (error: Error) => {
+			if (terminated) return;
 			errorMessage = error.message;
-			settle(1, null);
+			if (pid < 1) {
+				reason = "spawn-error";
+				confirm();
+			} else requestTermination("spawn-error");
 		});
-		child.once("close", (code: number | null, processSignal: NodeJS.Signals | null) => {
-			if ((reason === "cutoff" || reason === "aborted") && termSent && !killSent) {
-				killSent = true;
-				signalProcessTree(child, "SIGKILL", processGroup);
-				settle(code, processSignal);
-				return;
-			}
-			if (reason === "completed" && processGroupExists(pid)) {
-				if (cutoffTimer !== undefined) clearTimeout(cutoffTimer);
-				options.signal?.removeEventListener("abort", onAbort);
-				termSent = true;
-				signalProcessTree(child, "SIGTERM", processGroup);
-				const graceMs = Math.max(0, options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS);
-				escalationTimer = setTimeout(() => {
-					if (processGroupExists(pid)) {
-						killSent = true;
-						signalProcessTree(child, "SIGKILL", processGroup);
-					}
-					settle(code, processSignal);
-				}, graceMs);
-				return;
-			}
-			settle(code, processSignal);
+		child.once("close", (code: number | null, signal: NodeJS.Signals | null) => {
+			closeObserved = true;
+			exitCode = code;
+			processSignal = signal;
+			if (reason === "completed" && signal !== null) reason = "signal";
+			if (processGroupState(pid) !== "gone" && !responded) startCleanup();
+			observe();
 		});
-
-		if (options.cutoffMs > 0) {
-			cutoffTimer = setTimeout(() => requestTermination("cutoff"), options.cutoffMs);
-		}
+		if (options.cutoffMs > 0) cutoffTimer = setTimeout(() => requestTermination("cutoff"), options.cutoffMs);
 		if (options.signal?.aborted) onAbort();
 		else options.signal?.addEventListener("abort", onAbort, { once: true });
 	});
@@ -176,8 +192,10 @@ function withoutChild(
 		exitCode: reason === "aborted" ? 130 : 1,
 		signal: null,
 		reason,
-		elapsedMs: Date.now() - startedAtMs,
+		elapsedMs: performance.now() - startedAtMs,
 		cleanup: { termSent: false, killSent: false, processGroup },
+		terminationObserved: true,
+		settlement: Promise.resolve(),
 		...(errorMessage === undefined ? {} : { errorMessage }),
 	};
 }
@@ -186,51 +204,14 @@ function defaultSpawn(command: string, args: readonly string[], options: Managed
 	return spawn(command, [...args], options);
 }
 
-function processGroupExists(pid: number): boolean {
-	if (process.platform === "win32" || pid < 1) return false;
-	try {
-		process.kill(-pid, 0);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-function signalProcessTree(child: ManagedChild, signal: "SIGTERM" | "SIGKILL", processGroup: boolean): void {
-	const pid = child.pid;
-	if (pid === undefined) return;
-	if (process.platform === "win32") {
-		if (signal === "SIGKILL") {
-			try {
-				spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
-					detached: true,
-					stdio: "ignore",
-					windowsHide: true,
-				}).unref();
-				return;
-			} catch {
-				child.kill(signal);
-				return;
-			}
-		}
-		child.kill(signal);
-		return;
-	}
-	try {
-		process.kill(processGroup ? -pid : pid, signal);
-	} catch {
-		try {
-			child.kill(signal);
-		} catch {
-			return;
-		}
-	}
-}
-
-function normalizeExitCode(exitCode: number | null, reason: ManagedProcessReason): number {
-	if (exitCode !== null) return exitCode;
-	if (reason === "completed") return 0;
+function normalizeExitCode(
+	exitCode: number | null,
+	reason: ManagedProcessReason,
+	signal: NodeJS.Signals | null,
+	terminated: boolean,
+): number {
 	if (reason === "cutoff") return 124;
 	if (reason === "aborted") return 130;
-	return 1;
+	if (!terminated || signal !== null || reason !== "completed") return exitCode || 1;
+	return exitCode ?? 1;
 }

package/examples/extensions/subagent/subagent-runtime-types.ts

@@ -1,6 +1,6 @@
 import type { Message } from "omk-ai";
 import type { AgentCheckpoint } from "./checkpoint-runtime.ts";
-import type { ManagedProcessCleanup, ManagedProcessReason } from "./managed-process.ts";
+import type { ManagedProcessCleanup, ManagedProcessReason, ManagedProcessResult } from "./managed-process.ts";
 
 export interface UsageStats {
 	input: number;
@@ -47,6 +47,20 @@ export interface AgentDeadlineMetadata {
 }
 
 export interface SingleResult {
+	nodeId?: string;
+	attemptId?: string;
+	dependencyDigests?: Readonly<Record<string, string>>;
+	process?: ManagedProcessResult;
+	stream?: {
+		stdoutBytes: number;
+		stderrBytes: number;
+		events: number;
+		messages: number;
+		stdoutDigest: string;
+		stderrDigest: string;
+		usageUnknown: boolean;
+		failure?: string;
+	};
 	agent: string;
 	agentSource: "user" | "project" | "unknown";
 	task: string;
@@ -68,6 +82,8 @@ export interface SubagentAttemptResult {
 		readonly reason: ManagedProcessReason;
 		readonly elapsedMs: number;
 		readonly cleanup: ManagedProcessCleanup;
+		readonly terminationObserved?: boolean;
+		readonly settlement?: Promise<void>;
 	};
 }
 

package/examples/extensions/subagent/subagent-stream.ts

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import type { Message } from "omk-ai";
+import type { SingleResult } from "./subagent-runtime-types.ts";
+
+export const SUBAGENT_OUTPUT_LIMITS = {
+	stdoutBytes: 8 * 1024 * 1024,
+	stderrBytes: 256 * 1024,
+	lineBytes: 1024 * 1024,
+	events: 20_000,
+	messages: 1024,
+} as const;
+
+function record(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonnegative(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+/** Bounds are per process attempt, including ignored events and incomplete lines. */
+export function createSubagentStream(result: SingleResult, onMessage: () => void) {
+	let pending = "";
+	let terminal = false;
+	let assistantSeen = false;
+	const stdoutHash = createHash("sha256");
+	const stderrHash = createHash("sha256");
+	const stats = { stdoutBytes: 0, stderrBytes: 0, events: 0, messages: 0, usageUnknown: false };
+	let failure: string | undefined;
+	const fail = (reason: string): never => {
+		failure ??= reason;
+		throw new Error(failure);
+	};
+	const processLine = (line: string) => {
+		if (!line.trim()) return;
+		if (++stats.events > SUBAGENT_OUTPUT_LIMITS.events) fail("subagent.output.events_limit");
+		let event: unknown;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			fail("subagent.stream.invalid_json");
+		}
+		if (!record(event) || typeof event.type !== "string") return fail("subagent.stream.invalid_event");
+		if (event.type === "prompt_settled") {
+			if (terminal) fail("subagent.stream.duplicate_terminal");
+			terminal = true;
+			if (event.outcome !== "completed") fail("subagent.stream.prompt_not_completed");
+			return;
+		}
+		if (event.type !== "message_end" && event.type !== "tool_result_end") return;
+		if (terminal) fail("subagent.stream.message_after_terminal");
+		const message = event.message;
+		if (!record(message) || typeof message.role !== "string") return fail("subagent.stream.invalid_message");
+		// The CLI also emits custom session and user messages, which are not assistant receipts.
+		if (message.role !== "assistant" && message.role !== "toolResult") return;
+		if (!Array.isArray(message.content)) return fail("subagent.stream.invalid_content");
+		for (const part of message.content) {
+			if (!record(part)) return fail("subagent.stream.invalid_content");
+			if (part.type === "text" || part.type === "thinking") {
+				if (typeof part[part.type] !== "string") fail("subagent.stream.invalid_content");
+			} else if (part.type === "toolCall") {
+				if (typeof part.name !== "string" || typeof part.id !== "string" || !record(part.arguments))
+					fail("subagent.stream.invalid_tool_call");
+			} else if (part.type === "image") {
+				if (typeof part.data !== "string" || typeof part.mimeType !== "string")
+					fail("subagent.stream.invalid_image");
+			} else fail("subagent.stream.invalid_content");
+		}
+		if (stats.messages >= SUBAGENT_OUTPUT_LIMITS.messages) fail("subagent.output.messages_limit");
+		if (message.role === "assistant") {
+			if (message.model !== undefined && typeof message.model !== "string") fail("subagent.stream.invalid_model");
+			if (message.errorMessage !== undefined && typeof message.errorMessage !== "string")
+				fail("subagent.stream.invalid_error");
+			if (
+				message.stopReason !== undefined &&
+				!["stop", "length", "toolUse", "error", "aborted"].includes(String(message.stopReason))
+			)
+				fail("subagent.stream.invalid_stop_reason");
+			const usage = message.usage;
+			if (usage === undefined) stats.usageUnknown = true;
+			else {
+				if (!record(usage) || !record(usage.cost)) return fail("subagent.stream.invalid_usage");
+				for (const key of ["input", "output", "cacheRead", "cacheWrite", "totalTokens"] as const) {
+					if (!nonnegative(usage[key])) fail("subagent.stream.invalid_usage");
+				}
+				for (const key of ["input", "output", "cacheRead", "cacheWrite", "total"] as const) {
+					if (!nonnegative(usage.cost[key])) fail("subagent.stream.invalid_usage");
+				}
+			}
+			assistantSeen = true;
+		}
+		const msg = message as unknown as Message;
+		result.messages.push(msg);
+		stats.messages++;
+		if (msg.role === "assistant") {
+			result.usage.turns++;
+			if (msg.usage) {
+				result.usage.input += msg.usage.input;
+				result.usage.output += msg.usage.output;
+				result.usage.cacheRead += msg.usage.cacheRead;
+				result.usage.cacheWrite += msg.usage.cacheWrite;
+				result.usage.cost += msg.usage.cost.total;
+				result.usage.contextTokens = Math.max(result.usage.contextTokens, msg.usage.totalTokens);
+				if (Object.values(result.usage).some((value) => !nonnegative(value)))
+					fail("subagent.stream.usage_overflow");
+			}
+			result.model ??= msg.model;
+			if (msg.stopReason) result.stopReason = msg.stopReason;
+			if (msg.errorMessage) result.errorMessage = msg.errorMessage;
+		}
+		onMessage();
+	};
+	return {
+		stdout(chunk: string) {
+			if (failure) throw new Error(failure);
+			stats.stdoutBytes += Buffer.byteLength(chunk, "utf8");
+			stdoutHash.update(chunk);
+			if (stats.stdoutBytes > SUBAGENT_OUTPUT_LIMITS.stdoutBytes) fail("subagent.output.stdout_limit");
+			let start = 0;
+			while (start < chunk.length) {
+				const newline = chunk.indexOf("\n", start);
+				const fragment = chunk.slice(start, newline < 0 ? undefined : newline);
+				if (
+					Buffer.byteLength(pending, "utf8") + Buffer.byteLength(fragment, "utf8") >
+					SUBAGENT_OUTPUT_LIMITS.lineBytes
+				)
+					fail("subagent.output.line_limit");
+				pending += fragment;
+				if (newline < 0) break;
+				const line = pending;
+				pending = "";
+				processLine(line);
+				start = newline + 1;
+			}
+		},
+		stderr(chunk: string) {
+			if (failure) throw new Error(failure);
+			stats.stderrBytes += Buffer.byteLength(chunk, "utf8");
+			stderrHash.update(chunk);
+			if (stats.stderrBytes > SUBAGENT_OUTPUT_LIMITS.stderrBytes) fail("subagent.output.stderr_limit");
+			result.stderr += chunk;
+		},
+		finish(requireReceipt: boolean) {
+			try {
+				if (!failure && pending.trim()) processLine(pending);
+				if (!failure && requireReceipt && !assistantSeen) fail("subagent.stream.missing_terminal_message");
+			} catch {
+				failure ??= "subagent.stream.callback_error";
+			} finally {
+				pending = "";
+				result.stream = {
+					...stats,
+					stdoutDigest: stdoutHash.digest("hex"),
+					stderrDigest: stderrHash.digest("hex"),
+					...(failure ? { failure } : {}),
+				};
+			}
+			return failure;
+		},
+	};
+}

package/examples/extensions/terminal-browser/README.md

@@ -0,0 +1,54 @@
+# terminal-browser extension
+
+Run a real browser inside the OMK terminal UI.
+
+Port of the [terminal-browser Claude Code plugin](https://github.com/zenbu-labs/terminal-browser/tree/main/claude-code-plugin)
+(MIT, zenbu-labs). OMK has no function-hooks/Pane API, so the pane is a
+`ctx.ui.custom` overlay that renders kitty unicode placeholders; the
+`terminal-browser claude-bridge` HTTP API is reused unchanged.
+
+## Requirements
+
+- `terminal-browser` CLI — `curl -fsSL https://terminal-browser.sh/install | bash` or `brew install terminal-browser`
+- A terminal with kitty graphics protocol **and unicode placeholders**: ghostty, kitty, cmux, supacode, other libghostty terminals
+- Interactive TUI mode (`omk`), not `-p`/RPC/JSON
+- Not tmux/screen (multiplexers rewrite graphics escapes)
+
+## Usage
+
+```sh
+omk --extension ./examples/extensions/terminal-browser
+# or copy this directory to ~/.omk/agent/extensions/terminal-browser for auto-load
+```
+
+| Command | Action |
+| --- | --- |
+| `/browser example.com` | open pane at URL (https assumed) |
+| `/browser http://localhost:3000` | open pane at local dev server |
+| `/browser` | toggle close when open; open start page otherwise |
+| `/browser close` | close pane |
+| `ctrl+q` (in pane) | close pane |
+
+LLM tools: `terminal_browser_open { url? }`, `terminal_browser_close`.
+In-page control: `terminal-browser action ...` (agent-browser-compatible CLI).
+"Send to agent" (ctrl+g in the browser) inserts selected text into the OMK editor.
+
+## How it works
+
+1. `terminal-browser claude-bridge launch` spawns a detached bridge child that
+   reports `{ port, token }` and serves HTTP on `127.0.0.1` (`bridge.ts`).
+2. The bridge runs `terminal-browser open` with `PIXEL_EMBED`/`PIXEL_TTY`,
+   receives pixel frames, and writes kitty graphics to the TTY.
+3. The overlay component (`browser-surface.ts`) prints unicode placeholder cells;
+   the terminal composites the browser pixels over them.
+4. Input: SGR mouse + keys are translated to bridge `/input` events
+   (cell coordinates — the bridge scales to pixels).
+5. Polling `/state` at 250ms while open (1.2s idle) refreshes title/URL/placed
+   and drains the agent-text inbox into the editor.
+
+## Caveats
+
+Upstream plugin caveats apply: 50fps cap, occasional redraw glitches (select
+text to force repaint), mouse coordinates are cell-granular, and the bridge
+makes loopback HTTP requests (OS may prompt for local-network access).
+Override the binary with `TERMINAL_BROWSER_COMMAND`.

package/examples/extensions/terminal-browser/bridge-protocol.ts

@@ -0,0 +1,29 @@
+/**
+ * Wire types for the terminal-browser claude-bridge HTTP API.
+ * Ported from https://github.com/zenbu-labs/terminal-browser (MIT, zenbu-labs).
+ * Kept dependency-free: extensions cannot assume node_modules availability.
+ */
+
+export type Placed = { imageId: number; cols: number; rows: number };
+
+export type BridgeState = {
+	placed: Placed | null;
+	title: string;
+	url: string | null;
+	alive: boolean;
+	error: string | null;
+	inbox: number;
+};
+
+export type LaunchReport = { port: number; token: string } | { error: string; code: "tty" | "start" };
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
+
+export const isBridgeState = (value: unknown): value is BridgeState =>
+	isRecord(value) && typeof value.alive === "boolean" && "placed" in value;
+
+export const isLaunchReport = (value: unknown): value is LaunchReport =>
+	isRecord(value) && (typeof value.port === "number" || typeof value.error === "string");
+
+export const takenTexts = (value: unknown): string[] =>
+	isRecord(value) && Array.isArray(value.texts) ? value.texts.filter((t): t is string => typeof t === "string") : [];