@agwab/pi-workflow 0.2.1 → 0.3.0

package/src/subagent-backend.ts

@@ -57,7 +57,12 @@ const LEGACY_FETCH_CACHE_ENV = "PI_WORKFLOW_FETCH_CACHE";
 const DEFAULT_TRANSIENT_MODEL_FAILURE_RETRIES = 5;
 const DEFAULT_ARTIFACT_OUTPUT_RETRIES = 2;
 const MAX_CONCURRENT_LAUNCHES_ENV = "PI_WORKFLOW_MAX_CONCURRENT_LAUNCHES";
+const PARENT_SUBAGENT_CWD_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_CWD";
+const PARENT_SUBAGENT_RUNS_DIR_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_RUNS_DIR";
+const PARENT_SUBAGENT_RUN_ID_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_RUN_ID";
+const PARENT_SUBAGENT_ATTEMPT_ID_ENV = "PI_WORKFLOW_PARENT_SUBAGENT_ATTEMPT_ID";
 const DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS = 3_000;
+const STALE_LAUNCH_CLAIM_GRACE_MS = 30_000;
 const MIN_TRANSIENT_RETRY_JITTER_MS = 1_000;
 const MAX_TRANSIENT_RETRY_JITTER_MS = 5_000;
 const MODULE_PATH = fileURLToPath(import.meta.url);
@@ -161,8 +166,31 @@ interface SubagentApi {
 	): Promise<SubagentRunStatusSnapshot | null>;
 	interruptSubagent(options: Record<string, unknown>): Promise<unknown>;
 	reconcileSubagentRun(options: Record<string, unknown>): Promise<unknown>;
+	recordSubagentChildEvent?(
+		options: Record<string, unknown>,
+	): Promise<unknown>;
+}
+
+type ParentSubagentChildEvent =
+	| "started"
+	| "completed"
+	| "failed"
+	| "cancelled";
+
+interface ParentSubagentRef {
+	cwd: string;
+	runsDir: string;
+	runId: string;
+	attemptId?: string;
 }
 
+const GENERIC_TASK_STATUS_DETAILS = new Set([
+	"completed",
+	"failed",
+	"interrupted",
+	"running",
+]);
+
 const subagentApiSpecifier = "@agwab/pi-subagent/api";
 let cachedSubagentApi: Promise<SubagentApi> | undefined;
 let injectedSubagentApi: SubagentApi | undefined;
@@ -180,6 +208,85 @@ async function loadSubagentApi(): Promise<SubagentApi> {
 	return cachedSubagentApi;
 }
 
+function nonEmptyEnv(
+	env: Record<string, string | undefined>,
+	key: string,
+): string | undefined {
+	const value = env[key]?.trim();
+	return value ? value : undefined;
+}
+
+function parentSubagentRefFromEnv(
+	env: Record<string, string | undefined> = process.env,
+): ParentSubagentRef | undefined {
+	const cwd = nonEmptyEnv(env, PARENT_SUBAGENT_CWD_ENV);
+	const runsDir = nonEmptyEnv(env, PARENT_SUBAGENT_RUNS_DIR_ENV);
+	const runId = nonEmptyEnv(env, PARENT_SUBAGENT_RUN_ID_ENV);
+	if (!cwd || !runsDir || !runId) return undefined;
+	const attemptId = nonEmptyEnv(env, PARENT_SUBAGENT_ATTEMPT_ID_ENV);
+	return { cwd, runsDir, runId, ...(attemptId ? { attemptId } : {}) };
+}
+
+function terminalChildEventForTaskStatus(
+	status: WorkflowTaskRunRecord["status"],
+): ParentSubagentChildEvent | undefined {
+	if (status === "completed") return "completed";
+	if (status === "failed") return "failed";
+	if (status === "interrupted") return "cancelled";
+	return undefined;
+}
+
+async function recordParentSubagentChildEvent(options: {
+	event: ParentSubagentChildEvent;
+	childRunId: string;
+	run: WorkflowRunRecord;
+	task: WorkflowTaskRunRecord;
+	failureKind?: string | null;
+	message?: string;
+}): Promise<void> {
+	const parent = parentSubagentRefFromEnv();
+	if (!parent) return;
+	const api = await loadSubagentApi().catch(() => undefined);
+	if (!api?.recordSubagentChildEvent) return;
+	await api
+		.recordSubagentChildEvent({
+			...parent,
+			event: options.event,
+			childRunId: options.childRunId,
+			workflowRunId: options.run.runId,
+			childTaskId: options.task.taskId,
+			...(options.failureKind === undefined
+				? {}
+				: { failureKind: options.failureKind }),
+			...(options.message === undefined ? {} : { message: options.message }),
+		})
+		.catch(() => undefined);
+}
+
+async function recordTerminalParentSubagentChildEvent(
+	run: WorkflowRunRecord,
+	task: WorkflowTaskRunRecord,
+	snapshot: SubagentRunStatusSnapshot,
+): Promise<void> {
+	const event = terminalChildEventForTaskStatus(task.status);
+	if (!event) return;
+	const taskFailureKind =
+		task.statusDetail && !GENERIC_TASK_STATUS_DETAILS.has(task.statusDetail)
+			? task.statusDetail
+			: undefined;
+	await recordParentSubagentChildEvent({
+		event,
+		childRunId: snapshot.runId,
+		run,
+		task,
+		failureKind:
+			event === "completed"
+				? undefined
+				: (snapshot.failureKind ?? taskFailureKind ?? task.statusDetail),
+		message: task.lastMessage,
+	});
+}
+
 let launchSlotReleaseDelayMs = DEFAULT_LAUNCH_SLOT_RELEASE_DELAY_MS;
 let transientRetryJitterForTests: (() => number) | undefined;
 const launchWaitQueue: Array<() => void> = [];
@@ -225,8 +332,7 @@ function releaseLaunchSlotAfterDelay(
 		release();
 		return;
 	}
-	const timer = setTimeout(release, delayMs);
-	timer.unref?.();
+	setTimeout(release, delayMs);
 }
 
 async function runWithLaunchSlot<T>(action: () => Promise<T>): Promise<T> {
@@ -282,7 +388,6 @@ export async function cleanupSubagentRun(
 	run: WorkflowRunRecord,
 ): Promise<void> {
 	for (const task of run.tasks) {
-		if (isTerminalTaskStatus(task.status)) continue;
 		const handle = getSubagentHandle(task);
 		if (!handle) continue;
 		const api = await loadSubagentApi();
@@ -409,6 +514,13 @@ export async function launchSubagentTask(
 	task.statusDetail = "running";
 	task.lastMessage = "launched via pi-subagent/headless";
 	await writeRunRecord(cwd, run).catch(() => undefined);
+	await recordParentSubagentChildEvent({
+		event: "started",
+		childRunId: launched.runId,
+		run,
+		task,
+		message: task.lastMessage,
+	});
 	return { kind: "launched" };
 }
 
@@ -440,8 +552,13 @@ export async function refreshRunFromSubagentArtifacts(
 			}
 		}
 		if (!handle) {
+			if (isStaleLaunchClaim(task)) {
+				resetStaleLaunchClaim(task);
+				changed = true;
+				continue;
+			}
 			if (isTaskTimedOut(task)) {
-				markTaskTimedOut(task);
+				markSubagentTaskTimedOut(task);
 				changed = true;
 			}
 			continue;
@@ -466,16 +583,8 @@ export async function refreshRunFromSubagentArtifacts(
 
 		if (snapshot === null) {
 			if (isTaskTimedOut(task)) {
-				await api
-					.interruptSubagent({
-						cwd: handle.cwd,
-						runsDir: handle.runsDir,
-						runId: handle.runId,
-						attemptId: handle.attemptId,
-						reason: "workflow timeout",
-					})
-					.catch(() => undefined);
-				markTaskTimedOut(task);
+				await interruptTimedOutSubagent(api, handle);
+				markSubagentTaskTimedOut(task);
 				changed = true;
 			}
 			continue;
@@ -492,16 +601,8 @@ export async function refreshRunFromSubagentArtifacts(
 				? `pi-subagent heartbeat ${activeAttempt.heartbeatAt}`
 				: "pi-subagent running";
 			if (isTaskTimedOut(task)) {
-				await api
-					.interruptSubagent({
-						cwd: handle.cwd,
-						runsDir: handle.runsDir,
-						runId: handle.runId,
-						attemptId: handle.attemptId,
-						reason: "workflow timeout",
-					})
-					.catch(() => undefined);
-				markTaskTimedOut(task);
+				await interruptTimedOutSubagent(api, handle);
+				markSubagentTaskTimedOut(task);
 				changed = true;
 			}
 			continue;
@@ -515,6 +616,48 @@ export async function refreshRunFromSubagentArtifacts(
 	return run;
 }
 
+async function interruptTimedOutSubagent(
+	api: Awaited<ReturnType<typeof loadSubagentApi>>,
+	handle: NonNullable<WorkflowTaskRunRecord["backendHandle"]>,
+): Promise<void> {
+	await api
+		.interruptSubagent({
+			cwd: handle.cwd,
+			runsDir: handle.runsDir,
+			runId: handle.runId,
+			attemptId: handle.attemptId,
+			reason: "workflow timeout",
+		})
+		.catch(() => undefined);
+}
+
+function markSubagentTaskTimedOut(task: WorkflowTaskRunRecord): void {
+	markTaskTimedOut(task);
+	task.backendHandle = undefined;
+	task.backendTaskId = task.taskId;
+	task.pid = undefined;
+}
+
+function isStaleLaunchClaim(task: WorkflowTaskRunRecord): boolean {
+	if (task.statusDetail !== "launching" || !task.startedAt) return false;
+	const startedAtMs = Date.parse(task.startedAt);
+	return (
+		Number.isFinite(startedAtMs) &&
+		Date.now() - startedAtMs > STALE_LAUNCH_CLAIM_GRACE_MS
+	);
+}
+
+function resetStaleLaunchClaim(task: WorkflowTaskRunRecord): void {
+	task.status = "pending";
+	task.statusDetail = "pending";
+	task.startedAt = undefined;
+	task.backendHandle = undefined;
+	task.backendFiles = undefined;
+	task.backendTaskId = task.taskId;
+	task.pid = undefined;
+	task.lastMessage = "stale pi-subagent launch claim reset";
+}
+
 async function materializeTerminalSubagentResult(
 	cwd: string,
 	run: WorkflowRunRecord,
@@ -593,7 +736,7 @@ async function materializeTerminalSubagentResult(
 			snapshot.metadata?.contextLengthExceeded,
 	);
 	if (task.artifactGraph?.enabled && statusInfo.status === "completed") {
-		return await materializeTerminalArtifactGraphResult(cwd, run, task, {
+		const changed = await materializeTerminalArtifactGraphResult(cwd, run, task, {
 			outputFile,
 			stderrFile,
 			resultFile,
@@ -602,6 +745,8 @@ async function materializeTerminalSubagentResult(
 			exitCode,
 			subagentResult,
 		});
+		await recordTerminalParentSubagentChildEvent(run, task, snapshot);
+		return changed;
 	}
 	if (
 		shouldAttemptArtifactGraphSalvage({
@@ -615,7 +760,7 @@ async function materializeTerminalSubagentResult(
 			snapshot,
 		})
 	) {
-		return await materializeTerminalArtifactGraphResult(cwd, run, task, {
+		const changed = await materializeTerminalArtifactGraphResult(cwd, run, task, {
 			outputFile,
 			stderrFile,
 			resultFile,
@@ -629,6 +774,8 @@ async function materializeTerminalSubagentResult(
 				subagentFailureKind: snapshot.failureKind,
 			},
 		});
+		await recordTerminalParentSubagentChildEvent(run, task, snapshot);
+		return changed;
 	}
 	const workflowResult = {
 		status: statusInfo.status,
@@ -664,10 +811,12 @@ async function materializeTerminalSubagentResult(
 			),
 			workflowResult,
 		);
-		return retryOrFailTransientSubagentFailure(task, {
+		const changed = retryOrFailTransientSubagentFailure(task, {
 			reason: statusInfo.failureKind ?? "model",
 			message: errorMessage ?? "pi-subagent run failed before producing output",
 		});
+		await recordTerminalParentSubagentChildEvent(run, task, snapshot);
+		return changed;
 	}
 	await writeJson(resultFile, workflowResult);
 
@@ -682,6 +831,7 @@ async function materializeTerminalSubagentResult(
 		delete task.backendHandle;
 		delete task.backendFiles;
 	}
+	await recordTerminalParentSubagentChildEvent(run, task, snapshot);
 	return changed;
 }
 
@@ -1674,6 +1824,7 @@ async function recoverSubagentHandle(
 	const runsDir = subagentRunsDir(run, task);
 	const absoluteRunsDir = resolve(task.cwd, runsDir);
 	const expectedCorrelationId = `${run.runId}:${task.taskId}`;
+	const claimStartedAtMs = timestampMs(task.startedAt);
 	const entries = await readdir(absoluteRunsDir, { withFileTypes: true }).catch(
 		() => [],
 	);
@@ -1688,6 +1839,7 @@ async function recoverSubagentHandle(
 			join(absoluteRunsDir, entry.name, "run.json"),
 		);
 		if (!record || record.correlationId !== expectedCorrelationId) continue;
+		if (isPreClaimSubagentRecord(record, claimStartedAtMs)) continue;
 		const attemptId =
 			record.activeAttemptId ??
 			record.latestAttemptId ??
@@ -1714,6 +1866,20 @@ async function recoverSubagentHandle(
 	return candidates[0]?.handle;
 }
 
+function isPreClaimSubagentRecord(
+	record: SubagentRunRecordLike,
+	claimStartedAtMs: number | undefined,
+): boolean {
+	if (claimStartedAtMs === undefined) return false;
+	const recordStartedAtMs =
+		timestampMs(record.startedAt) ??
+		timestampMs(record.attempts?.[0]?.startedAt) ??
+		timestampMs(record.updatedAt);
+	return (
+		recordStartedAtMs !== undefined && recordStartedAtMs < claimStartedAtMs
+	);
+}
+
 function timestampMs(value: string | undefined): number | undefined {
 	if (value === undefined) return undefined;
 	const time = Date.parse(value);
@@ -1774,7 +1940,14 @@ function subagentSessionId(
 	task: WorkflowTaskRunRecord,
 ): string | undefined {
 	if (!task.artifactGraph?.enabled) return undefined;
-	return task.outputRetry?.sessionId ?? baseSubagentSessionId(run, task);
+	const baseSessionId = baseSubagentSessionId(run, task);
+	if (task.outputRetry?.sessionId) return task.outputRetry.sessionId;
+	const launchAttempt = task.launchRetry?.attempts ?? 0;
+	if (launchAttempt > 0)
+		return `${baseSessionId}:launch-retry-${launchAttempt}`;
+	const resumeAttempt = task.resumeEvents?.length ?? 0;
+	if (resumeAttempt > 0) return `${baseSessionId}:resume-${resumeAttempt}`;
+	return baseSessionId;
 }
 
 function baseSubagentSessionId(

package/src/types.ts

@@ -542,6 +542,9 @@ export interface CompiledTask {
 		branchId?: string;
 		outputProfile?: string;
 	};
+	foreachGenerated?: {
+		placeholderSpecId: string;
+	};
 	loopChild?: CompiledLoopChildTaskRef;
 	loopPlaceholder?: {
 		loopId: string;
@@ -634,6 +637,9 @@ export interface WorkflowTaskRunRecord {
 		branchId?: string;
 		outputProfile?: string;
 	};
+	foreachGenerated?: {
+		placeholderSpecId: string;
+	};
 	launchRetry?: {
 		attempts: number;
 		maxAttempts?: number;

package/src/workflow-runtime.ts

@@ -345,9 +345,25 @@ export function readSimpleJsonPath(value: unknown, path: string): unknown {
 	const parts = path.slice(2).split(".").filter(Boolean);
 	let current = value as any;
 	for (const part of parts) {
-		if (current === null || typeof current !== "object" || !(part in current))
-			return undefined;
+		if (!canReadJsonPathPart(current, part)) return undefined;
 		current = current[part];
 	}
 	return current;
 }
+
+function canReadJsonPathPart(
+	value: unknown,
+	part: string,
+): value is Record<string, unknown> {
+	return (
+		isSafeJsonPathPart(part) && isRecord(value) && Object.hasOwn(value, part)
+	);
+}
+
+function isSafeJsonPathPart(part: string): boolean {
+	return part !== "__proto__" && part !== "prototype" && part !== "constructor";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}

package/src/workflow-view.ts

@@ -1370,10 +1370,11 @@ function statusForSummary(
 ): WorkflowRunStatus | TaskRunStatus {
 	if (summary.running > 0) return "running";
 	if (summary.blocked > 0) return "blocked";
-	if (summary.failed > 0 || summary.interrupted > 0) return "failed";
+	if (summary.failed > 0) return "failed";
 	if (summary.pending > 0) return "pending";
 	if (summary.total > 0 && summary.completed === summary.total)
 		return "completed";
+	if (summary.interrupted > 0) return "interrupted";
 	return "interrupted";
 }