open-multi-agent-kit 0.91.0 → 0.93.0

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

@@ -0,0 +1,178 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import { runManagedProcess } from "./managed-process.ts";
+
+const fixturePath = path.join(path.dirname(fileURLToPath(import.meta.url)), "fixtures", "hanging-process-tree.mjs");
+
+async function processExists(pid: number): Promise<boolean> {
+	for (let attempt = 0; attempt < 20; attempt++) {
+		try {
+			process.kill(pid, 0);
+			await new Promise((resolve) => setTimeout(resolve, 25));
+		} catch {
+			return false;
+		}
+	}
+	return true;
+}
+
+describe("managed subagent process lifecycle", () => {
+	it("escalates a cutoff from SIGTERM to SIGKILL and reaps the process tree", async () => {
+		let stdout = "";
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: [fixturePath],
+			cwd: process.cwd(),
+			// Generous cutoff: the fixture is a fresh `node` process that needs
+			// ~50-100ms+ (more under parallel load) to start and write its stdout
+			// handshake before the cutoff may fire, otherwise stdout is empty.
+			cutoffMs: 2_500,
+			terminationGraceMs: 40,
+			forceSettleMs: 1_000,
+			onStdout: (chunk) => {
+				stdout += chunk;
+			},
+		});
+		const event = JSON.parse(stdout.trim()) as { grandchildPid: number };
+
+		expect(result.reason).toBe("cutoff");
+		expect(result.cleanup.termSent).toBe(true);
+		expect(result.cleanup.killSent).toBe(true);
+		expect(result.elapsedMs).toBeLessThan(8_000);
+		expect(await processExists(result.pid)).toBe(false);
+		if (process.platform !== "win32") {
+			expect(await processExists(event.grandchildPid)).toBe(false);
+		}
+	});
+
+	it("kills resistant descendants even when the direct child exits on SIGTERM", async () => {
+		let stdout = "";
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: [fixturePath, "--parent-exits"],
+			cwd: process.cwd(),
+			// Generous cutoff so the fixture's stdout handshake lands before the
+			// cutoff fires (see note above).
+			cutoffMs: 2_500,
+			terminationGraceMs: 500,
+			forceSettleMs: 1_000,
+			onStdout: (chunk) => {
+				stdout += chunk;
+			},
+		});
+		const event = JSON.parse(stdout.trim()) as { grandchildPid: number };
+
+		expect(result.reason).toBe("cutoff");
+		expect(result.cleanup).toMatchObject({ termSent: true, killSent: true });
+		if (process.platform !== "win32") {
+			expect(await processExists(event.grandchildPid)).toBe(false);
+		}
+	});
+
+	it.skipIf(process.platform === "win32")("reaps resistant descendants left by a normally exiting child", async () => {
+		let stdout = "";
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: [fixturePath, "--normal-orphan"],
+			cwd: process.cwd(),
+			cutoffMs: 4_000,
+			// Wider grace gives the orphaned, SIGTERM-resistant grandchild a stable
+			// window so the process-group existence check (and SIGKILL escalation)
+			// is deterministic under parallel load.
+			terminationGraceMs: 300,
+			forceSettleMs: 500,
+			onStdout: (chunk) => {
+				stdout += chunk;
+			},
+		});
+		const event = JSON.parse(stdout.trim()) as { grandchildPid: number };
+		try {
+			expect(result).toMatchObject({
+				exitCode: 0,
+				reason: "completed",
+				cleanup: { termSent: true, killSent: true, processGroup: true },
+			});
+			expect(await processExists(event.grandchildPid)).toBe(false);
+		} finally {
+			try {
+				process.kill(event.grandchildPid, "SIGKILL");
+			} catch {
+				// Expected when managed cleanup reaped the descendant.
+			}
+		}
+	});
+
+	it("distinguishes parent cancellation from an internal cutoff", async () => {
+		const controller = new AbortController();
+		setTimeout(() => controller.abort(new Error("caller canceled")), 40);
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: [fixturePath],
+			cwd: process.cwd(),
+			cutoffMs: 5_000,
+			terminationGraceMs: 20,
+			forceSettleMs: 1_000,
+			signal: controller.signal,
+		});
+
+		expect(result.reason).toBe("aborted");
+		expect(result.cleanup.termSent).toBe(true);
+	});
+
+	it("returns typed spawn failures instead of rejecting past cleanup boundaries", async () => {
+		const result = await runManagedProcess({
+			command: "missing",
+			args: [],
+			cwd: process.cwd(),
+			cutoffMs: 1_000,
+			spawnProcess: () => {
+				throw new Error("fixture spawn failure");
+			},
+		});
+
+		expect(result).toMatchObject({
+			pid: -1,
+			exitCode: 1,
+			reason: "spawn-error",
+			errorMessage: "fixture spawn failure",
+		});
+	});
+
+	it("does not spawn when the parent signal is already aborted", async () => {
+		const controller = new AbortController();
+		controller.abort(new Error("already canceled"));
+		let spawned = false;
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: [fixturePath],
+			cwd: process.cwd(),
+			cutoffMs: 1_000,
+			signal: controller.signal,
+			spawnProcess: () => {
+				spawned = true;
+				throw new Error("must not spawn");
+			},
+		});
+
+		expect(spawned).toBe(false);
+		expect(result).toMatchObject({ pid: -1, exitCode: 130, reason: "aborted" });
+	});
+
+	it("leaves a normally completed process untouched", async () => {
+		let stdout = "";
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: ["-e", "process.stdout.write('done')"],
+			cwd: process.cwd(),
+			cutoffMs: 1_000,
+			onStdout: (chunk) => {
+				stdout += chunk;
+			},
+		});
+
+		expect(result).toMatchObject({ reason: "completed", exitCode: 0 });
+		expect(result.cleanup).toEqual({ termSent: false, killSent: false, processGroup: process.platform !== "win32" });
+		expect(stdout).toBe("done");
+	});
+});

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

@@ -0,0 +1,236 @@
+import {
+	type ChildProcessByStdio,
+	type SpawnOptionsWithStdioTuple,
+	type StdioNull,
+	type StdioPipe,
+	spawn,
+} from "node:child_process";
+import type { Readable } from "node:stream";
+
+type ManagedChild = ChildProcessByStdio<null, Readable, Readable>;
+type ManagedSpawnOptions = SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>;
+
+export type ManagedProcessReason = "completed" | "cutoff" | "aborted" | "spawn-error";
+
+export interface ManagedProcessCleanup {
+	readonly termSent: boolean;
+	readonly killSent: boolean;
+	readonly processGroup: boolean;
+}
+
+export interface ManagedProcessResult {
+	readonly pid: number;
+	readonly exitCode: number;
+	readonly signal: NodeJS.Signals | null;
+	readonly reason: ManagedProcessReason;
+	readonly elapsedMs: number;
+	readonly cleanup: ManagedProcessCleanup;
+	readonly errorMessage?: string;
+}
+
+export interface RunManagedProcessOptions {
+	readonly command: string;
+	readonly args: readonly string[];
+	readonly cwd: string;
+	readonly cutoffMs: number;
+	readonly terminationGraceMs?: number;
+	readonly forceSettleMs?: number;
+	readonly signal?: AbortSignal;
+	readonly onStdout?: (chunk: string) => void;
+	readonly onStderr?: (chunk: string) => void;
+	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 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, {
+			cwd: options.cwd,
+			shell: false,
+			stdio: ["ignore", "pipe", "pipe"],
+			detached: processGroup,
+			windowsHide: true,
+		});
+	} catch (error) {
+		return withoutChild(
+			"spawn-error",
+			startedAtMs,
+			processGroup,
+			error instanceof Error ? error.message : String(error),
+		);
+	}
+	const pid = child.pid ?? -1;
+
+	return await new Promise<ManagedProcessResult>((resolve) => {
+		let settled = false;
+		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);
+			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),
+				signal: processSignal,
+				reason,
+				elapsedMs: Date.now() - startedAtMs,
+				cleanup: { termSent, killSent, processGroup },
+				...(errorMessage === undefined ? {} : { errorMessage }),
+			});
+		};
+
+		const requestTermination = (nextReason: "cutoff" | "aborted"): void => {
+			if (settled || reason !== "completed") return;
+			reason = nextReason;
+			termSent = true;
+			signalProcessTree(child, "SIGTERM", processGroup);
+			const graceMs = Math.max(0, options.terminationGraceMs ?? DEFAULT_TERMINATION_GRACE_MS);
+			escalationTimer = setTimeout(() => {
+				if (settled) return;
+				killSent = true;
+				signalProcessTree(child, "SIGKILL", processGroup);
+			}, graceMs);
+			forceSettleTimer = setTimeout(
+				() => settle(null, null),
+				graceMs + Math.max(1, options.forceSettleMs ?? DEFAULT_FORCE_SETTLE_MS),
+			);
+		};
+
+		function onAbort(): void {
+			requestTermination("aborted");
+		}
+
+		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";
+			errorMessage = error.message;
+			settle(1, null);
+		});
+		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);
+		});
+
+		if (options.cutoffMs > 0) {
+			cutoffTimer = setTimeout(() => requestTermination("cutoff"), options.cutoffMs);
+		}
+		if (options.signal?.aborted) onAbort();
+		else options.signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+
+function withoutChild(
+	reason: "aborted" | "spawn-error",
+	startedAtMs: number,
+	processGroup: boolean,
+	errorMessage?: string,
+): ManagedProcessResult {
+	return {
+		pid: -1,
+		exitCode: reason === "aborted" ? 130 : 1,
+		signal: null,
+		reason,
+		elapsedMs: Date.now() - startedAtMs,
+		cleanup: { termSent: false, killSent: false, processGroup },
+		...(errorMessage === undefined ? {} : { errorMessage }),
+	};
+}
+
+function defaultSpawn(command: string, args: readonly string[], options: ManagedSpawnOptions): ManagedChild {
+	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;
+	if (reason === "cutoff") return 124;
+	if (reason === "aborted") return 130;
+	return 1;
+}

package/examples/extensions/subagent/subagent-extension-smoke.test.ts

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { ExtensionAPI } from "open-multi-agent-kit";
+import { afterEach, describe, expect, it } from "vitest";
+
+interface SmokeToolResult {
+	readonly content: readonly { readonly type: string; readonly text?: string }[];
+	readonly details?: unknown;
+	readonly isError?: boolean;
+}
+
+interface SmokeTool {
+	execute(
+		toolCallId: string,
+		params: unknown,
+		signal: AbortSignal,
+		onUpdate: undefined,
+		context: unknown,
+	): Promise<SmokeToolResult>;
+}
+
+interface SmokeDetails {
+	readonly mode: string;
+	readonly results: readonly {
+		readonly output?: string;
+		readonly exitCode: number;
+		readonly deadline?: { readonly outcome: string; readonly attempts: readonly unknown[] };
+	}[];
+	readonly executionBudget: {
+		readonly hardDeadlineMs: number;
+		readonly plannedShards: number;
+		readonly completedShards: number;
+		readonly resumeCount: number;
+	};
+}
+
+const cleanupPaths: string[] = [];
+const originalArgvEntry = process.argv[1];
+const originalAgentDir = process.env.OMK_CODING_AGENT_DIR;
+
+afterEach(async () => {
+	process.argv[1] = originalArgvEntry;
+	if (originalAgentDir === undefined) delete process.env.OMK_CODING_AGENT_DIR;
+	else process.env.OMK_CODING_AGENT_DIR = originalAgentDir;
+	await Promise.all(cleanupPaths.splice(0).map((entry) => fs.promises.rm(entry, { recursive: true, force: true })));
+});
+
+describe("subagent extension registration and spawn smoke", () => {
+	it("runs the registered tool through the managed process boundary without a provider API", async () => {
+		const cwd = await fs.promises.mkdtemp(path.join(os.tmpdir(), "omk-subagent-extension-smoke-"));
+		cleanupPaths.push(cwd);
+		const projectAgentsDir = path.join(cwd, ".omk", "agents");
+		const agentHome = path.join(cwd, "agent-home");
+		await fs.promises.mkdir(projectAgentsDir, { recursive: true });
+		await fs.promises.mkdir(agentHome, { recursive: true });
+		await fs.promises.writeFile(
+			path.join(projectAgentsDir, "fixture-agent.md"),
+			"---\nname: fixture-agent\ndescription: Offline extension smoke fixture\n---\nReturn the fixture result.\n",
+			"utf8",
+		);
+		process.argv[1] = path.join(import.meta.dirname, "fixtures", "fake-omk-json.mjs");
+		process.env.OMK_CODING_AGENT_DIR = agentHome;
+
+		let registered: unknown;
+		const api = {
+			registerTool(tool: unknown) {
+				registered = tool;
+			},
+		} as unknown as ExtensionAPI;
+		const { default: registerSubagent } = await import("./index.ts");
+		registerSubagent(api);
+		if (!isSmokeTool(registered)) throw new Error("subagent tool was not registered");
+
+		const result = await registered.execute(
+			"fixture-call",
+			{
+				agent: "fixture-agent",
+				task: "Run the offline fixture.",
+				agentScope: "project",
+				confirmProjectAgents: false,
+				executionBudgetMs: 120_000,
+				maxResumeAttempts: 1,
+			},
+			new AbortController().signal,
+			undefined,
+			{ cwd, hasUI: false },
+		);
+		const details = result.details as SmokeDetails;
+
+		expect(result.isError).not.toBe(true);
+		expect(result.content[0]?.text).toContain("fixture subagent completed");
+		expect(details.mode).toBe("single");
+		expect(details.results[0]).toMatchObject({
+			exitCode: 0,
+			output: "fixture subagent completed",
+			deadline: { outcome: "completed" },
+		});
+		expect(details.results[0]?.deadline?.attempts).toHaveLength(1);
+		expect(details.executionBudget).toMatchObject({
+			hardDeadlineMs: 120_000,
+			plannedShards: 1,
+			completedShards: 1,
+			resumeCount: 0,
+		});
+		expect(await fs.promises.stat(path.join(agentHome, "state", "subagent-deadline-profiles.json"))).toBeDefined();
+	}, 120_000);
+});
+
+function isSmokeTool(value: unknown): value is SmokeTool {
+	return typeof value === "object" && value !== null && "execute" in value && typeof value.execute === "function";
+}

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

@@ -0,0 +1,76 @@
+import type { Message } from "omk-ai";
+import type { AgentCheckpoint } from "./checkpoint-runtime.ts";
+import type { ManagedProcessCleanup, ManagedProcessReason } from "./managed-process.ts";
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	contextTokens: number;
+	turns: number;
+}
+
+export type DeadlineOutcome = "completed" | "cutoff" | "aborted" | "failed" | "budget-exhausted";
+
+export interface DeadlineAttemptMetadata {
+	readonly attempt: number;
+	readonly shardId: string;
+	readonly cutoffMs: number;
+	readonly elapsedMs: number;
+	readonly outcome: Exclude<DeadlineOutcome, "budget-exhausted">;
+	readonly exitCode: number;
+	readonly messageCount: number;
+	readonly processReason: ManagedProcessReason;
+	readonly cleanup: ManagedProcessCleanup;
+}
+
+export interface AgentDeadlineMetadata {
+	readonly outcome: DeadlineOutcome;
+	readonly startedAtMs: number;
+	readonly elapsedMs: number;
+	readonly hardDeadlineMs: number;
+	readonly estimatedTokens: number;
+	readonly workUnits: number;
+	readonly predictedMs: number;
+	readonly plannedShardIds: readonly string[];
+	readonly completedShardIds: readonly string[];
+	readonly remainingShardIds: readonly string[];
+	readonly resumeCount: number;
+	readonly duplicateResumeBlocked: boolean;
+	readonly provider: string;
+	readonly model: string;
+	readonly profileSamples: number;
+	readonly attempts: readonly DeadlineAttemptMetadata[];
+	readonly checkpoint?: AgentCheckpoint;
+}
+
+export interface SingleResult {
+	agent: string;
+	agentSource: "user" | "project" | "unknown";
+	task: string;
+	exitCode: number;
+	messages: Message[];
+	stderr: string;
+	usage: UsageStats;
+	output?: string;
+	model?: string;
+	stopReason?: string;
+	errorMessage?: string;
+	step?: number;
+	deadline?: AgentDeadlineMetadata;
+}
+
+export interface SubagentAttemptResult {
+	readonly result: SingleResult;
+	readonly process: {
+		readonly reason: ManagedProcessReason;
+		readonly elapsedMs: number;
+		readonly cleanup: ManagedProcessCleanup;
+	};
+}
+
+export function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
+}

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "omk-extension-with-deps",
-  "version": "0.91.0",
+  "version": "0.93.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omk-extension-with-deps",
-      "version": "0.91.0",
+      "version": "0.93.0",
       "dependencies": {
         "ms": "2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "omk-extension-with-deps",
 	"private": true,
-	"version": "0.91.0",
+	"version": "0.93.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",