@agwab/pi-workflow 0.2.1 → 0.3.0

package/node_modules/@agwab/pi-subagent/src/orchestrate/run-ref.ts

@@ -0,0 +1,219 @@
+import {
+	mkdir,
+	readdir,
+	readFile,
+	rename,
+	stat,
+	writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+const DEFAULT_RUNS_DIR = ".pi/agent/runs";
+const SAFE_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+const RUN_LOCATOR_SCHEMA_VERSION = 1 as const;
+
+export interface RunRefLocator {
+	schemaVersion: typeof RUN_LOCATOR_SCHEMA_VERSION;
+	runId: string;
+	cwd: string;
+	runsDir?: string;
+	parentSessionId?: string;
+	correlationId?: string;
+	updatedAt: string;
+}
+
+export interface LocatableRunRef {
+	cwd?: string;
+	runId: string;
+	runsDir?: string;
+}
+
+export interface WriteRunLocatorOptions extends LocatableRunRef {
+	cwd: string;
+	parentSessionId?: string;
+	correlationId?: string;
+}
+
+export interface RunLocatorListResult {
+	locators: RunRefLocator[];
+	invalidCount: number;
+	skippedCount: number;
+}
+
+function assertSafeId(name: string, value: string): void {
+	if (!SAFE_ID_PATTERN.test(value))
+		throw new Error(
+			`${name} must contain only letters, numbers, dots, underscores, or dashes.`,
+		);
+}
+
+function isInsideOrEqual(parent: string, child: string): boolean {
+	const childRelative = relative(parent, child);
+	return (
+		childRelative === "" ||
+		(!childRelative.startsWith("..") && !isAbsolute(childRelative))
+	);
+}
+
+function normalizeCwd(cwd: string): string {
+	return resolve(cwd);
+}
+
+function assertSafeRunsDir(cwd: string, runsDir: string | undefined): void {
+	const absolute = resolve(cwd, runsDir ?? DEFAULT_RUNS_DIR);
+	if (!isInsideOrEqual(cwd, absolute))
+		throw new Error(
+			"runsDir must be inside cwd so lifecycle refs remain relative and safe.",
+		);
+}
+
+function runIndexDir(): string {
+	const override = process.env.PI_SUBAGENT_RUN_INDEX_DIR;
+	return resolve(
+		override && override.length > 0
+			? override
+			: join(homedir(), ".pi", "agent", "subagent-runs"),
+	);
+}
+
+function runLocatorPath(runId: string): string {
+	assertSafeId("runId", runId);
+	return join(runIndexDir(), `${runId}.json`);
+}
+
+function isRunRefLocator(value: unknown): value is RunRefLocator {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		(value as { schemaVersion?: unknown }).schemaVersion ===
+			RUN_LOCATOR_SCHEMA_VERSION &&
+		typeof (value as { runId?: unknown }).runId === "string" &&
+		typeof (value as { cwd?: unknown }).cwd === "string"
+	);
+}
+
+async function localRunDirExists(
+	ref: LocatableRunRef,
+	defaultCwd: string,
+): Promise<boolean> {
+	const cwd = normalizeCwd(ref.cwd ?? defaultCwd);
+	assertSafeRunsDir(cwd, ref.runsDir);
+	const runsDir = resolve(cwd, ref.runsDir ?? DEFAULT_RUNS_DIR);
+	const info = await stat(join(runsDir, ref.runId)).catch(() => null);
+	return info?.isDirectory() === true;
+}
+
+export async function writeRunLocator(
+	options: WriteRunLocatorOptions,
+): Promise<void> {
+	assertSafeId("runId", options.runId);
+	const cwd = normalizeCwd(options.cwd);
+	assertSafeRunsDir(cwd, options.runsDir);
+	const locator: RunRefLocator = {
+		schemaVersion: RUN_LOCATOR_SCHEMA_VERSION,
+		runId: options.runId,
+		cwd,
+		...(options.runsDir === undefined ? {} : { runsDir: options.runsDir }),
+		...(options.parentSessionId === undefined
+			? {}
+			: { parentSessionId: options.parentSessionId }),
+		...(options.correlationId === undefined
+			? {}
+			: { correlationId: options.correlationId }),
+		updatedAt: new Date().toISOString(),
+	};
+	const path = runLocatorPath(options.runId);
+	await mkdir(dirname(path), { recursive: true });
+	const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+	await writeFile(tempPath, `${JSON.stringify(locator, null, 2)}\n`);
+	await rename(tempPath, path);
+}
+
+export async function readRunLocator(
+	runId: string,
+): Promise<RunRefLocator | null> {
+	const path = runLocatorPath(runId);
+	try {
+		const parsed = JSON.parse(await readFile(path, "utf8"));
+		if (!isRunRefLocator(parsed) || parsed.runId !== runId) return null;
+		const cwd = normalizeCwd(parsed.cwd);
+		assertSafeRunsDir(cwd, parsed.runsDir);
+		return { ...parsed, cwd };
+	} catch (error) {
+		if (
+			error &&
+			typeof error === "object" &&
+			"code" in error &&
+			error.code === "ENOENT"
+		)
+			return null;
+		return null;
+	}
+}
+
+export async function listRunLocators(): Promise<RunLocatorListResult> {
+	const indexDir = runIndexDir();
+	const entries = await readdir(indexDir, { withFileTypes: true }).catch(
+		() => [],
+	);
+	const locators: RunRefLocator[] = [];
+	let invalidCount = 0;
+	let skippedCount = 0;
+
+	for (const entry of entries) {
+		if (!entry.isFile()) {
+			skippedCount += 1;
+			continue;
+		}
+		if (!entry.name.endsWith(".json") || entry.name.endsWith(".tmp")) {
+			skippedCount += 1;
+			continue;
+		}
+		const runId = entry.name.slice(0, -".json".length);
+		try {
+			assertSafeId("runId", runId);
+			const path = join(indexDir, entry.name);
+			const info = await stat(path);
+			if (!info.isFile() || info.size > 64 * 1024) {
+				invalidCount += 1;
+				continue;
+			}
+			const parsed = JSON.parse(await readFile(path, "utf8"));
+			if (!isRunRefLocator(parsed) || parsed.runId !== runId) {
+				invalidCount += 1;
+				continue;
+			}
+			const cwd = normalizeCwd(parsed.cwd);
+			assertSafeRunsDir(cwd, parsed.runsDir);
+			locators.push({ ...parsed, cwd });
+		} catch {
+			invalidCount += 1;
+		}
+	}
+
+	return { locators, invalidCount, skippedCount };
+}
+
+export async function resolveRunRef<T extends LocatableRunRef>(
+	ref: T,
+	defaultCwd = process.cwd(),
+): Promise<T & { cwd: string }> {
+	assertSafeId("runId", ref.runId);
+	const fallbackCwd = normalizeCwd(ref.cwd ?? defaultCwd);
+	if (ref.cwd !== undefined || ref.runsDir !== undefined)
+		return { ...ref, cwd: fallbackCwd };
+	if (await localRunDirExists(ref, fallbackCwd))
+		return { ...ref, cwd: fallbackCwd };
+
+	const locator = await readRunLocator(ref.runId);
+	if (locator !== null) {
+		return {
+			...ref,
+			cwd: locator.cwd,
+			...(locator.runsDir === undefined ? {} : { runsDir: locator.runsDir }),
+		};
+	}
+
+	return { ...ref, cwd: fallbackCwd };
+}

package/node_modules/@agwab/pi-subagent/src/orchestrate/run.ts

@@ -21,6 +21,7 @@ import {
 	resolveWorkspace,
 	type ResolvedWorkspace,
 } from "../workspace/worktree.ts";
+import { writeRunLocator } from "./run-ref.ts";
 
 export const DEFAULT_PARALLEL_CONCURRENCY = 4;
 export const MAX_PARALLEL_TASKS = 12;
@@ -44,6 +45,10 @@ export interface ParallelRunResult {
 	runIds: string[];
 	results: ResultEnvelope[];
 	concurrency: number;
+	totalTasks: number;
+	startedCount: number;
+	skippedCount: number;
+	failFastTriggered: boolean;
 }
 
 export class SubagentToolAuthorityError extends Error {
@@ -63,6 +68,8 @@ function mergeTaskInput(
 		worktree: parent.worktree,
 		worktreePolicy: parent.worktreePolicy,
 		concurrency: undefined,
+		failFast: undefined,
+		cancelSiblingsOnFailure: undefined,
 		asyncDependency: undefined,
 		runsDir: parent.runsDir,
 		correlationId: parent.correlationId,
@@ -150,6 +157,11 @@ export async function runSubagentTask(
 			},
 		],
 	});
+	await writeRunLocator({
+		...runRef,
+		parentSessionId: input.parentSessionId,
+		correlationId: input.correlationId,
+	}).catch(() => undefined);
 
 	try {
 		const workspace = await resolveWorkspace({
@@ -319,29 +331,97 @@ export async function runParallelSubagentTasks(
 	const tasks = input.tasks;
 	const runCwd = resolve(input.cwd ?? cwd);
 	const concurrency = Math.min(parallelConcurrency(input), tasks.length);
-	const results: ResultEnvelope[] = new Array(tasks.length);
+	const resultSlots: Array<ResultEnvelope | undefined> = new Array(
+		tasks.length,
+	);
+	const failFast =
+		input.failFast === true || input.cancelSiblingsOnFailure === true;
+	const cancelSiblings = input.cancelSiblingsOnFailure === true;
+	const controller = cancelSiblings ? new AbortController() : undefined;
+	const childSignal = controller?.signal ?? signal;
 	let nextIndex = 0;
+	let startedCount = 0;
+	let stopScheduling = false;
+	let failFastTriggered = false;
+	let parentAbortTriggered = false;
+	let siblingCancelTriggered = false;
+	const workerErrors: unknown[] = [];
+
+	function triggerFailFast(): void {
+		if (!failFast) return;
+		failFastTriggered = true;
+		stopScheduling = true;
+		if (cancelSiblings && !controller?.signal.aborted) {
+			siblingCancelTriggered = true;
+			controller?.abort();
+		}
+	}
+
+	function onParentAbort(): void {
+		parentAbortTriggered = true;
+		controller?.abort();
+	}
+	if (controller !== undefined && signal !== undefined) {
+		if (signal.aborted) controller.abort();
+		else signal.addEventListener("abort", onParentAbort, { once: true });
+	}
 
 	async function worker(): Promise<void> {
 		while (true) {
+			if (stopScheduling) return;
 			const index = nextIndex;
 			nextIndex += 1;
 			if (index >= tasks.length) return;
+			startedCount += 1;
 			const taskInput = mergeTaskInput(input, tasks[index]!);
-			results[index] = await runSubagentTask({
-				input: taskInput,
-				cwd: runCwd,
-				signal,
-				taskIndex: index,
-			});
+			try {
+				const result = await runSubagentTask({
+					input: taskInput,
+					cwd: runCwd,
+					signal: childSignal,
+					taskIndex: index,
+				});
+				resultSlots[index] = result;
+				if (result.status !== "completed") triggerFailFast();
+			} catch (error) {
+				const siblingAbort =
+					controller?.signal.aborted === true &&
+					siblingCancelTriggered &&
+					!parentAbortTriggered;
+				triggerFailFast();
+				if (!failFast || !siblingAbort) throw error;
+				workerErrors.push(error);
+				return;
+			}
 		}
 	}
 
-	await Promise.all(Array.from({ length: concurrency }, () => worker()));
+	try {
+		const workers = await Promise.allSettled(
+			Array.from({ length: concurrency }, () => worker()),
+		);
+		const rejected = workers.find(
+			(workerResult): workerResult is PromiseRejectedResult =>
+				workerResult.status === "rejected",
+		);
+		if (rejected !== undefined) throw rejected.reason;
+		if (workerErrors.length > 0) failFastTriggered = true;
+	} finally {
+		if (controller !== undefined && signal !== undefined)
+			signal.removeEventListener("abort", onParentAbort);
+	}
+
+	const results = resultSlots.filter(
+		(result): result is ResultEnvelope => result !== undefined,
+	);
 	return {
 		mode: "parallel",
 		runIds: results.map((result) => result.runId),
 		results,
 		concurrency,
+		totalTasks: tasks.length,
+		startedCount,
+		skippedCount: Math.max(0, tasks.length - startedCount),
+		failFastTriggered,
 	};
 }