open-multi-agent-kit 0.98.5 → 1.0.0

package/examples/extensions/subagent/index.ts

@@ -13,6 +13,7 @@
  * Uses JSON mode to capture structured output from subagents.
  */
 
+import { randomUUID } from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -42,8 +43,10 @@ import {
 	resolveSubagentExecutionPolicy,
 } from "./deadline-budget.ts";
 import { DeadlineProfileStore } from "./deadline-profile-store.ts";
+import { blockedResult, dependencyDigests, failedResult as isFailedResult, laneResult } from "./graph-result.ts";
 import { runManagedProcess } from "./managed-process.ts";
 import { emptyUsage, type SingleResult, type SubagentAttemptResult } from "./subagent-runtime-types.ts";
+import { createSubagentStream } from "./subagent-stream.ts";
 import {
 	type GraphTask,
 	GraphValidationError,
@@ -233,10 +236,6 @@ function getFinalOutput(messages: Message[]): string {
 	return "";
 }
 
-function isFailedResult(result: SingleResult): boolean {
-	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
-}
-
 function getResultOutput(result: SingleResult): string {
 	const partialOutput = result.output || getFinalOutput(result.messages);
 	if (isFailedResult(result)) {
@@ -385,6 +384,7 @@ async function runSingleAgentAttempt(
 	let tmpPromptPath: string | null = null;
 
 	const currentResult: SingleResult = {
+		attemptId: randomUUID(),
 		agent: agentName,
 		agentSource: agent.source,
 		task: logicalTask,
@@ -419,38 +419,7 @@ async function runSingleAgentAttempt(
 		}
 
 		args.push(`Task: ${task}`);
-		let buffer = "";
-		const processLine = (line: string) => {
-			const event = parseSubagentEvent(line);
-			if (event === undefined) return;
-			if (event.type === "message_end" && event.message !== undefined) {
-				const msg = event.message;
-				currentResult.messages.push(msg);
-				if (msg.role === "assistant") {
-					currentResult.usage.turns += 1;
-					const usage = msg.usage;
-					if (usage) {
-						currentResult.usage.input += usage.input || 0;
-						currentResult.usage.output += usage.output || 0;
-						currentResult.usage.cacheRead += usage.cacheRead || 0;
-						currentResult.usage.cacheWrite += usage.cacheWrite || 0;
-						currentResult.usage.cost += usage.cost?.total || 0;
-						currentResult.usage.contextTokens = Math.max(
-							currentResult.usage.contextTokens,
-							usage.totalTokens || 0,
-						);
-					}
-					if (!currentResult.model && msg.model) currentResult.model = msg.model;
-					if (msg.stopReason) currentResult.stopReason = msg.stopReason;
-					if (msg.errorMessage) currentResult.errorMessage = msg.errorMessage;
-				}
-				emitUpdate();
-			}
-			if (event.type === "tool_result_end" && event.message !== undefined) {
-				currentResult.messages.push(event.message);
-				emitUpdate();
-			}
-		};
+		const stream = createSubagentStream(currentResult, emitUpdate);
 		const invocation = getOmkInvocation(args);
 		const processResult = await runManagedProcess({
 			command: invocation.command,
@@ -458,17 +427,11 @@ async function runSingleAgentAttempt(
 			cwd: cwd ?? defaultCwd,
 			cutoffMs,
 			signal,
-			onStdout: (chunk) => {
-				buffer += chunk;
-				const lines = buffer.split("\n");
-				buffer = lines.pop() || "";
-				for (const line of lines) processLine(line);
-			},
-			onStderr: (chunk) => {
-				currentResult.stderr += chunk;
-			},
+			onStdout: stream.stdout,
+			onStderr: stream.stderr,
 		});
-		if (buffer.trim()) processLine(buffer);
+		currentResult.process = processResult;
+		const streamFailure = stream.finish(processResult.reason === "completed" && processResult.exitCode === 0);
 		currentResult.exitCode = processResult.exitCode;
 		currentResult.output = getFinalOutput(currentResult.messages);
 		if (processResult.reason === "cutoff") {
@@ -484,6 +447,17 @@ async function runSingleAgentAttempt(
 			currentResult.stopReason = "error";
 			currentResult.errorMessage = processResult.errorMessage ?? "Unable to spawn subagent";
 		}
+		if (processResult.reason === "signal" || processResult.reason === "callback-error" || streamFailure) {
+			currentResult.exitCode ||= 1;
+			currentResult.stopReason = "error";
+			currentResult.errorMessage =
+				streamFailure ?? processResult.errorMessage ?? `Subagent terminated by ${processResult.signal}`;
+		}
+		if (!processResult.terminationObserved) {
+			currentResult.exitCode ||= 1;
+			currentResult.stopReason = "unsettled";
+			currentResult.errorMessage = `${currentResult.errorMessage ?? "Subagent termination unconfirmed"} (unsettled)`;
+		}
 		return { result: currentResult, process: processResult };
 	} finally {
 		if (tmpPromptPath)
@@ -501,30 +475,6 @@ async function runSingleAgentAttempt(
 	}
 }
 
-interface SubagentJsonEvent {
-	readonly type: string;
-	readonly message?: Message;
-}
-
-function parseSubagentEvent(line: string): SubagentJsonEvent | undefined {
-	if (line.trim() === "") return undefined;
-	let value: unknown;
-	try {
-		value = JSON.parse(line);
-	} catch {
-		return undefined;
-	}
-	if (!isRecord(value) || typeof value.type !== "string") return undefined;
-	const message = value.message;
-	if (message === undefined) return { type: value.type };
-	if (!isRecord(message) || typeof message.role !== "string" || !Array.isArray(message.content)) return undefined;
-	return { type: value.type, message: message as unknown as Message };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 async function runSingleAgent(
 	defaultCwd: string,
 	agents: AgentConfig[],
@@ -602,6 +552,11 @@ const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
+	writeScope: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Owned write paths for ownership-safe parallel scheduling (spec 020).",
+		}),
+	),
 });
 
 const ChainItem = Type.Object({
@@ -616,6 +571,11 @@ const GraphItem = Type.Object({
 	task: Type.String({ description: "Task; use {dependencies} to inject declared dependency outputs" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Task node ids that must complete first" })),
+	writeScope: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Owned write paths for ownership-safe parallel scheduling (spec 020).",
+		}),
+	),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -830,15 +790,46 @@ export default function (omk: ExtensionAPI) {
 
 				const results: SingleResult[] = [];
 				const outputs = new Map<string, string>();
+				const resultById = new Map<string, SingleResult>();
 				const completedNodeIds: string[] = [];
 				graphDetails = { waves: plan.waves, completedNodeIds };
-				for (const [waveIndex, wave] of plan.waves.entries()) {
-					const waveResults = await mapWithConcurrencyLimit<string, { id: string; result: SingleResult }>(
-						[...wave],
-						executionPolicy.concurrency,
-						async (id) => {
-							const task = plan.tasks.get(id);
-							if (!task) throw new GraphValidationError(`node '${id}' disappeared after validation`);
+
+				// Spec 020 Req1 — when the session binds a lane authority, the DAG
+				// routes through buildSubagentOrchestrationPlan → launchSubagentLanes.
+				// Batches run sequentially, so renderDependencyContext sees completed
+				// dependency outputs at launch time.
+				const laneAuthority = ctx.getSubagentLaneAuthority?.();
+				if (laneAuthority) {
+					const nodeById = new Map(plan.tasks);
+					const lanes = params.graph.map((node) => ({
+						id: node.id,
+						role: "executor" as const,
+						task: node.task,
+						agentName: node.agent,
+						dependsOn: node.dependsOn ?? [],
+						...(node.writeScope ? { writeScope: node.writeScope } : {}),
+					}));
+					const dispatch = await laneAuthority.dispatchLanes({
+						lanes,
+						spawnPlan: {
+							whyParallel: `${params.graph.length} DAG tasks in graph mode`,
+							whyNotLocal: "isolated subagent context per node",
+							independence: "explicit dependsOn DAG",
+							expectedReceiptShape: "per-node SingleResult map",
+							maxInlineTokens: 8192,
+						},
+						configuredMaxParallelLanes: executionPolicy.unbounded ? undefined : executionPolicy.concurrency,
+						heavyLaneIds: laneAuthority.getCurrentResourceAdmission()
+							? new Set(lanes.map((lane) => lane.id))
+							: undefined,
+						signal,
+						launchLane: async ({ laneId, signal: laneSignal }) => {
+							const task = nodeById.get(laneId);
+							if (!task) return { status: "failed" as const };
+							if ((task.dependsOn ?? []).some((id) => !outputs.has(id))) {
+								resultById.set(laneId, blockedResult(task));
+								return { status: "failed" as const };
+							}
 							const result = await runSingleAgent(
 								ctx.cwd,
 								agents,
@@ -846,52 +837,104 @@ export default function (omk: ExtensionAPI) {
 								renderDependencyContext(task, outputs),
 								task.cwd,
 								undefined,
-								signal,
+								laneSignal,
 								undefined,
 								makeDetails("graph"),
 								executionPolicy.unbounded,
 								executionBudget,
 								profileStore,
-								plan.waves.length - waveIndex,
+								0,
 							);
-							return { id, result };
+							result.nodeId = laneId;
+							result.dependencyDigests = dependencyDigests(task, outputs);
+							resultById.set(laneId, result);
+							if (!isFailedResult(result)) {
+								outputs.set(laneId, getResultOutput(result));
+								completedNodeIds.push(laneId);
+							}
+							return laneResult(result);
 						},
-					);
-					for (const { id, result } of waveResults) {
-						results.push(result);
-						if (!isFailedResult(result)) {
-							outputs.set(id, getResultOutput(result));
-							completedNodeIds.push(id);
+					});
+					const outcomes = new Map(dispatch.outcomes.map((outcome) => [outcome.laneId, outcome]));
+					for (const [id, task] of plan.tasks) {
+						if (!resultById.has(id)) {
+							const outcome = outcomes.get(id);
+							resultById.set(
+								id,
+								blockedResult(
+									task,
+									dispatch.blockers.join("; ") ||
+										outcome?.diagnostic ||
+										outcome?.status ||
+										"blocked-dependency",
+								),
+							);
 						}
 					}
 					graphDetails = { waves: plan.waves, completedNodeIds: [...completedNodeIds] };
-					const failed = waveResults.filter(({ result }) => isFailedResult(result));
-					if (failed.length > 0) {
-						const failedIds = failed.map(({ id }) => id).join(", ");
-						return {
-							content: [
-								{
-									type: "text",
-									text: `Graph stopped after wave ${waveIndex + 1}; failed nodes: ${failedIds}. Downstream nodes were not started.`,
-								},
-							],
-							details: makeDetails("graph")(results),
-							isError: true,
-						};
+				} else {
+					for (const [waveIndex, wave] of plan.waves.entries()) {
+						const waveResults = await mapWithConcurrencyLimit<string, { id: string; result: SingleResult }>(
+							[...wave],
+							executionPolicy.concurrency,
+							async (id) => {
+								const task = plan.tasks.get(id);
+								if (!task) throw new GraphValidationError(`node '${id}' disappeared after validation`);
+								if ((task.dependsOn ?? []).some((dependency) => !outputs.has(dependency)))
+									return { id, result: blockedResult(task) };
+								const result = await runSingleAgent(
+									ctx.cwd,
+									agents,
+									task.agent,
+									renderDependencyContext(task, outputs),
+									task.cwd,
+									undefined,
+									signal,
+									undefined,
+									makeDetails("graph"),
+									executionPolicy.unbounded,
+									executionBudget,
+									profileStore,
+									plan.waves.length - waveIndex,
+								);
+								return { id, result };
+							},
+						);
+						for (const { id, result } of waveResults) {
+							result.nodeId = id;
+							const task = plan.tasks.get(id);
+							if (task) result.dependencyDigests = dependencyDigests(task, outputs);
+							resultById.set(id, result);
+							if (!isFailedResult(result)) {
+								outputs.set(id, getResultOutput(result));
+								completedNodeIds.push(id);
+							}
+						}
+						graphDetails = { waves: plan.waves, completedNodeIds: [...completedNodeIds] };
+						const failed = waveResults.filter(({ result }) => isFailedResult(result));
+						if (failed.length > 0) break;
 					}
 				}
-				const summaries = results.map((result, index) => {
-					const id = completedNodeIds[index] ?? `node-${index + 1}`;
-					return `### [${id}] completed\n\n${truncateParallelOutput(getResultOutput(result))}`;
+				for (const [id, task] of plan.tasks) results.push(resultById.get(id) ?? blockedResult(task));
+				graphDetails = {
+					waves: plan.waves,
+					completedNodeIds: results
+						.filter((result) => !isFailedResult(result))
+						.flatMap((result) => (result.nodeId ? [result.nodeId] : [])),
+				};
+				const summaries = results.map((result) => {
+					const status = isFailedResult(result) ? (result.stopReason ?? "failed") : "completed";
+					return `### [${result.nodeId}] ${status}\n\n${truncateParallelOutput(getResultOutput(result))}`;
 				});
 				return {
 					content: [
 						{
 							type: "text",
-							text: `Graph: ${results.length}/${params.graph.length} completed in ${plan.waves.length} waves\n\n${summaries.join("\n\n---\n\n")}`,
+							text: `Graph: ${graphDetails.completedNodeIds.length}/${params.graph.length} completed in ${plan.waves.length} waves\n\n${summaries.join("\n\n---\n\n")}`,
 						},
 					],
 					details: makeDetails("graph")(results),
+					isError: results.some(isFailedResult),
 				};
 			}
 
@@ -936,10 +979,101 @@ export default function (omk: ExtensionAPI) {
 					}
 				};
 
-				const results = await mapWithConcurrencyLimit(
-					params.tasks,
-					executionPolicy.concurrency,
-					async (t, index) => {
+				// Spec 020 Req1 — when the session binds a lane authority, parallel
+				// tasks route through buildSubagentOrchestrationPlan →
+				// launchSubagentLanes (parent admission + shared pool + settlement).
+				// Without one (bare/test contexts) keep the local concurrency path.
+				const laneAuthority = ctx.getSubagentLaneAuthority?.();
+				let results: SingleResult[];
+				if (laneAuthority) {
+					const laneIndexById = new Map<string, number>();
+					const lanes = params.tasks.map((t, index) => {
+						const id = `task-${index}`;
+						laneIndexById.set(id, index);
+						return {
+							id,
+							role: "executor" as const,
+							task: t.task,
+							agentName: t.agent,
+							...(t.writeScope ? { writeScope: t.writeScope } : {}),
+						};
+					});
+					const dispatch = await laneAuthority.dispatchLanes({
+						lanes,
+						spawnPlan: {
+							whyParallel: `${params.tasks.length} independent agent tasks requested in parallel mode`,
+							whyNotLocal: "isolated subagent context per task",
+							independence: "tasks declare no dependencies",
+							expectedReceiptShape: "per-task SingleResult array",
+							maxInlineTokens: 8192,
+						},
+						configuredMaxParallelLanes: executionPolicy.unbounded ? undefined : executionPolicy.concurrency,
+						// Child omk processes are heavy — they draw the shared permit
+						// only under a governed admission decision; observe/off keeps
+						// the legacy breadth (spec Req1.3 vs. observe-mode semantics).
+						heavyLaneIds: laneAuthority.getCurrentResourceAdmission()
+							? new Set(lanes.map((lane) => lane.id))
+							: undefined,
+						signal,
+						launchLane: async ({ laneId, signal: laneSignal }) => {
+							const index = laneIndexById.get(laneId);
+							if (index === undefined) return;
+							const t = params.tasks?.[index];
+							if (!t) return;
+							const result = await runSingleAgent(
+								ctx.cwd,
+								agents,
+								t.agent,
+								t.task,
+								t.cwd,
+								undefined,
+								laneSignal,
+								(partial) => {
+									if (partial.details?.results[0]) {
+										allResults[index] = partial.details.results[0];
+										emitParallelUpdate();
+									}
+								},
+								makeDetails("parallel"),
+								executionPolicy.unbounded,
+								executionBudget,
+								profileStore,
+								1,
+							);
+							allResults[index] = result;
+							emitParallelUpdate();
+							return laneResult(result);
+						},
+					});
+					if (dispatch.blockers.length > 0) {
+						return {
+							content: [{ type: "text", text: `Lane dispatch blocked: ${dispatch.blockers.join("; ")}` }],
+							details: makeDetails("parallel")([]),
+						};
+					}
+					// Req2.4 — lanes that never launched still yield a typed outcome,
+					// never an empty-success. Convert non-launched outcomes to failed
+					// results so the summary is honest.
+					for (const outcome of dispatch.outcomes) {
+						if (outcome.status === "completed") continue;
+						const index = laneIndexById.get(outcome.laneId);
+						if (index === undefined) continue;
+						if (allResults[index].exitCode === -1) {
+							allResults[index] = {
+								agent: params.tasks[index].agent,
+								agentSource: "unknown",
+								task: params.tasks[index].task,
+								exitCode: 1,
+								messages: [],
+								stderr: outcome.diagnostic ?? outcome.status,
+								stopReason: outcome.status,
+								usage: emptyUsage(),
+							};
+						}
+					}
+					results = allResults;
+				} else {
+					results = await mapWithConcurrencyLimit(params.tasks, executionPolicy.concurrency, async (t, index) => {
 						const result = await runSingleAgent(
 							ctx.cwd,
 							agents,
@@ -964,8 +1098,8 @@ export default function (omk: ExtensionAPI) {
 						allResults[index] = result;
 						emitParallelUpdate();
 						return result;
-					},
-				);
+					});
+				}
 
 				const successCount = results.filter((r) => !isFailedResult(r)).length;
 				const summaries = results.map((r) => {
@@ -983,6 +1117,7 @@ export default function (omk: ExtensionAPI) {
 						},
 					],
 					details: makeDetails("parallel")(results),
+					isError: results.some(isFailedResult),
 				};
 			}
 
@@ -1184,8 +1319,8 @@ export default function (omk: ExtensionAPI) {
 				const failed = details.results.some(isFailedResult);
 				const icon = failed ? theme.fg("error", "✗") : theme.fg("success", "✓");
 				let text = `${icon} ${theme.fg("toolTitle", theme.bold("graph "))}${theme.fg("accent", `${completed}/${total} nodes · ${waves} waves`)}`;
-				for (const [index, result] of details.results.entries()) {
-					const id = details.graph?.completedNodeIds[index] ?? result.agent;
+				for (const result of details.results) {
+					const id = result.nodeId ?? result.agent;
 					const resultIcon = isFailedResult(result) ? theme.fg("error", "✗") : theme.fg("success", "✓");
 					text += `\n${theme.fg("muted", "─── ")}${theme.fg("accent", id)} ${resultIcon}`;
 					if (expanded) text += `\n${theme.fg("toolOutput", getResultOutput(result))}`;

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

@@ -0,0 +1,42 @@
+import { type ChildProcess, spawn } from "node:child_process";
+
+/** EPERM and other observation errors cannot prove that a group is gone. */
+export function processGroupState(pid: number): "alive" | "gone" | "unknown" {
+	if (process.platform === "win32" || pid < 1) return "gone";
+	try {
+		process.kill(-pid, 0);
+		return "alive";
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code === "ESRCH" ? "gone" : "unknown";
+	}
+}
+
+/** Requests termination, never confirms it. Only signal the child owned by this invocation. */
+export function signalProcessTree(child: ChildProcess, signal: "SIGTERM" | "SIGKILL", processGroup: boolean): void {
+	const pid = child.pid;
+	if (pid === undefined) return;
+	if (process.platform === "win32" && signal === "SIGKILL") {
+		try {
+			const killer = spawn("taskkill", ["/F", "/T", "/PID", String(pid)], {
+				detached: true,
+				stdio: "ignore",
+				windowsHide: true,
+			});
+			killer.on("error", () => {});
+			killer.unref();
+			return;
+		} catch {
+			// Fall back to the owned direct child, without claiming descendant containment.
+		}
+	}
+	try {
+		if (process.platform === "win32") child.kill(signal);
+		else process.kill(processGroup ? -pid : pid, signal);
+	} catch {
+		try {
+			child.kill(signal);
+		} catch {
+			/* Termination remains unconfirmed. */
+		}
+	}
+}

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

@@ -18,6 +18,30 @@ async function processExists(pid: number): Promise<boolean> {
 }
 
 describe("managed subagent process lifecycle", () => {
+	it.skipIf(process.platform === "win32").each(["SIGTERM", "SIGKILL"] as const)(
+		"does not report %s termination as success",
+		async (signal) => {
+			const result = await runManagedProcess({
+				command: process.execPath,
+				args: ["-e", `process.kill(process.pid, ${JSON.stringify(signal)})`],
+				cwd: process.cwd(),
+				cutoffMs: 5_000,
+			});
+			expect(result.signal).toBe(signal);
+			expect(result.exitCode).not.toBe(0);
+		},
+	);
+
+	it("preserves an explicit nonzero exit", async () => {
+		const result = await runManagedProcess({
+			command: process.execPath,
+			args: ["-e", "process.exit(7)"],
+			cwd: process.cwd(),
+			cutoffMs: 5_000,
+		});
+		expect(result.exitCode).toBe(7);
+		expect(result.signal).toBeNull();
+	});
 	it("escalates a cutoff from SIGTERM to SIGKILL and reaps the process tree", async () => {
 		let stdout = "";
 		const result = await runManagedProcess({