@fitchmultz/pi-subagents 0.0.0-stage → 0.44.4

package/src/runs/shared/workflow-graph.ts

@@ -0,0 +1,220 @@
+import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
+import type { SingleResult, SubagentRunMode, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowNodeStatus } from "../../shared/types.ts";
+
+/** Pending fanouts keep their own slot until their actual children are known. */
+export function workflowAgentNodes(graph: WorkflowGraphSnapshot): WorkflowGraphNode[] {
+	return graph.nodes.flatMap((node) => node.children?.length ? node.children
+		: node.kind === "dynamic-parallel-group" && node.status !== "completed" && node.status !== "complete" ? [node]
+		: node.children ?? [node]);
+}
+
+export interface WorkflowGraphBuildInput {
+	runId: string;
+	mode?: SubagentRunMode;
+	steps: ChainStep[];
+	results?: Array<Pick<SingleResult, "exitCode" | "detached" | "interrupted" | "timedOut" | "error" | "acceptance">>;
+	currentFlatIndex?: number;
+	currentStepIndex?: number;
+	stepStatuses?: Array<{ status?: string; error?: string }>;
+	dynamicChildren?: Record<number, Array<{ agent: string; label?: string; flatIndex: number; itemKey: string; outputName?: string; structured?: boolean; error?: string }>>;
+	dynamicGroupStatuses?: Record<number, { status: WorkflowNodeStatus; error?: string; acceptance?: SingleResult["acceptance"] }>;
+}
+
+function normalizeStatus(status: string | undefined): WorkflowNodeStatus | undefined {
+	switch (status) {
+		case "complete":
+		case "completed":
+			return "completed";
+		case "running":
+			return "running";
+		case "failed":
+			return "failed";
+		case "paused":
+			return "paused";
+		case "blocked":
+			return "blocked";
+		case "detached":
+			return "detached";
+		case "timed-out":
+			return "timed-out";
+		case "pending":
+			return "pending";
+		default:
+			return undefined;
+	}
+}
+
+function resultStatus(result: Pick<SingleResult, "exitCode" | "detached" | "interrupted" | "timedOut" | "acceptance"> | undefined): WorkflowNodeStatus | undefined {
+	if (!result) return undefined;
+	if (result.detached) return "detached";
+	if (result.timedOut) return "timed-out";
+	if (result.interrupted) return "paused";
+	return result.exitCode === 0 ? result.acceptance?.status === "blocked" ? "blocked" : "completed" : "failed";
+}
+
+function nodeStatus(input: WorkflowGraphBuildInput, flatIndex: number): WorkflowNodeStatus {
+	return normalizeStatus(input.stepStatuses?.[flatIndex]?.status)
+		?? resultStatus(input.results?.[flatIndex])
+		?? (input.currentFlatIndex === flatIndex ? "running" : "pending");
+}
+
+function pushPhase(phases: WorkflowGraphSnapshot["phases"], phase: string | undefined, nodeId: string): void {
+	if (!phase) return;
+	let group = phases.find((candidate) => candidate.title === phase);
+	if (!group) {
+		group = { title: phase, nodeIds: [] };
+		phases.push(group);
+	}
+	group.nodeIds.push(nodeId);
+}
+
+function seqLabel(step: SequentialStep, stepIndex: number): string {
+	return step.label?.trim() || step.agent || `Step ${stepIndex + 1}`;
+}
+
+function summarizeParallelStatuses(statuses: WorkflowNodeStatus[]): WorkflowNodeStatus {
+	if (statuses.some((status) => status === "running")) return "running";
+	if (statuses.some((status) => status === "failed")) return "failed";
+	if (statuses.some((status) => status === "timed-out")) return "timed-out";
+	if (statuses.some((status) => status === "blocked")) return "blocked";
+	if (statuses.some((status) => status === "paused")) return "paused";
+	if (statuses.some((status) => status === "detached")) return "detached";
+	if (statuses.length > 0 && statuses.every((status) => status === "completed")) return "completed";
+	if (statuses.some((status) => status === "completed")) return "running";
+	return "pending";
+}
+
+export function buildWorkflowGraphSnapshot(input: WorkflowGraphBuildInput): WorkflowGraphSnapshot {
+	const nodes: WorkflowGraphNode[] = [];
+	const phases: WorkflowGraphSnapshot["phases"] = [];
+	let flatIndex = 0;
+	let currentNodeId: string | undefined;
+
+	for (let stepIndex = 0; stepIndex < input.steps.length; stepIndex++) {
+		const step = input.steps[stepIndex]!;
+		if (isParallelStep(step)) {
+			const groupId = `step-${stepIndex}`;
+			const children: WorkflowGraphNode[] = [];
+			const childStatuses: WorkflowNodeStatus[] = [];
+			for (let taskIndex = 0; taskIndex < step.parallel.length; taskIndex++) {
+				const task = step.parallel[taskIndex]!;
+				const status = nodeStatus(input, flatIndex);
+				childStatuses.push(status);
+				const childId = `step-${stepIndex}-agent-${taskIndex}`;
+				const child: WorkflowGraphNode = {
+					id: childId,
+					kind: "agent",
+					agent: task.agent,
+					phase: task.phase,
+					label: task.label?.trim() || task.agent || `Agent ${taskIndex + 1}`,
+					status,
+					flatIndex,
+					stepIndex,
+					outputName: task.as,
+					structured: Boolean(task.outputSchema),
+					acceptanceStatus: input.results?.[flatIndex]?.acceptance?.status,
+					error: input.stepStatuses?.[flatIndex]?.error ?? input.results?.[flatIndex]?.error,
+				};
+				children.push(child);
+				pushPhase(phases, task.phase, childId);
+				if (status === "running" || input.currentFlatIndex === flatIndex) currentNodeId = childId;
+				flatIndex++;
+			}
+			const groupStatus = summarizeParallelStatuses(childStatuses);
+			if (input.currentStepIndex === stepIndex && !currentNodeId) currentNodeId = groupId;
+			nodes.push({
+				id: groupId,
+				kind: "parallel-group",
+				label: step.parallel.length === 1 ? "Parallel task" : `Parallel group (${step.parallel.length})`,
+				status: groupStatus,
+				stepIndex,
+				children,
+			});
+			continue;
+		}
+
+		if (isDynamicParallelStep(step)) {
+			const groupId = `step-${stepIndex}`;
+			const materialized = input.dynamicChildren?.[stepIndex] ?? [];
+			const groupOverride = input.dynamicGroupStatuses?.[stepIndex];
+			const children: WorkflowGraphNode[] = [];
+			const childStatuses: WorkflowNodeStatus[] = [];
+			for (let taskIndex = 0; taskIndex < materialized.length; taskIndex++) {
+				const task = materialized[taskIndex]!;
+				const status = nodeStatus(input, task.flatIndex);
+				childStatuses.push(status);
+				const childId = `step-${stepIndex}-item-${task.itemKey.replace(/[^a-zA-Z0-9_-]/g, "-")}`;
+				const child: WorkflowGraphNode = {
+					id: childId,
+					kind: "agent",
+					agent: task.agent,
+					phase: step.parallel.phase ?? step.phase,
+					label: task.label?.trim() || step.parallel.label?.trim() || `${task.agent} ${task.itemKey}`,
+					status,
+					flatIndex: task.flatIndex,
+					stepIndex,
+					itemKey: task.itemKey,
+					outputName: task.outputName,
+					structured: task.structured,
+					acceptanceStatus: input.results?.[task.flatIndex]?.acceptance?.status,
+					error: input.stepStatuses?.[task.flatIndex]?.error ?? input.results?.[task.flatIndex]?.error ?? task.error,
+				};
+				children.push(child);
+				pushPhase(phases, child.phase, childId);
+				if (status === "running" || input.currentFlatIndex === task.flatIndex) currentNodeId = childId;
+			}
+			const groupStatus = groupOverride?.status ?? (children.length > 0 ? summarizeParallelStatuses(childStatuses) : (input.currentStepIndex === stepIndex ? "running" : "pending"));
+			if (input.currentStepIndex === stepIndex && !currentNodeId) currentNodeId = groupId;
+			nodes.push({
+				id: groupId,
+				kind: "dynamic-parallel-group",
+				label: step.label?.trim() || step.parallel.label?.trim() || `Dynamic fanout (${step.collect.as})`,
+				status: groupStatus,
+				stepIndex,
+				outputName: step.collect.as,
+				structured: Boolean(step.collect.outputSchema),
+				acceptanceStatus: groupOverride?.acceptance?.status,
+				error: groupOverride?.error,
+				dynamic: {
+					sourceOutput: step.expand.from.output,
+					sourcePath: step.expand.from.path,
+					itemName: step.expand.item ?? "item",
+					maxItems: step.expand.maxItems,
+					collectAs: step.collect.as,
+				},
+				children,
+			});
+			if (materialized.length > 0) flatIndex = Math.max(flatIndex, ...materialized.map((child) => child.flatIndex + 1));
+			continue;
+		}
+
+		const seq = step as SequentialStep;
+		const status = nodeStatus(input, flatIndex);
+		const id = `step-${stepIndex}`;
+		nodes.push({
+			id,
+			kind: "step",
+			agent: seq.agent,
+			phase: seq.phase,
+			label: seqLabel(seq, stepIndex),
+			status,
+			flatIndex,
+			stepIndex,
+			outputName: seq.as,
+			structured: Boolean(seq.outputSchema),
+			acceptanceStatus: input.results?.[flatIndex]?.acceptance?.status,
+			error: input.stepStatuses?.[flatIndex]?.error ?? input.results?.[flatIndex]?.error,
+		});
+		pushPhase(phases, seq.phase, id);
+		if (status === "running" || input.currentFlatIndex === flatIndex || input.currentStepIndex === stepIndex) currentNodeId = id;
+		flatIndex++;
+	}
+
+	return {
+		runId: input.runId,
+		mode: input.mode ?? "chain",
+		phases,
+		nodes,
+		currentNodeId,
+	};
+}

package/src/runs/shared/workflow-policy.ts

@@ -0,0 +1,125 @@
+import type { DynamicParallelStep } from "../../shared/settings.ts";
+import type { ArtifactPaths, ChainOutputMap } from "../../shared/types.ts";
+import { outputEntryFromResult } from "./chain-outputs.ts";
+import { collectDynamicResults, validateDynamicCollection, type DynamicCollectedResult, type DynamicMaterializedItem } from "./dynamic-fanout.ts";
+import { aggregateParallelOutputs, FAIL_FAST_REASON, mapConcurrent, type ParallelTaskResult } from "./parallel-utils.ts";
+
+export interface WorkflowOutcome extends ParallelTaskResult {
+	interrupted?: boolean;
+	detached?: boolean;
+	timedOut?: boolean;
+	acceptance?: import("../../shared/types.ts").AcceptanceLedger;
+	structuredOutput?: unknown;
+	artifactPaths?: ArtifactPaths;
+	savedOutputPath?: string;
+}
+
+export type ParallelStopReason = "cancelled" | "interrupted" | "fail-fast" | "detached" | "timed-out";
+
+type ChildOutcome = Pick<WorkflowOutcome, "exitCode" | "interrupted" | "detached" | "timedOut" | "acceptance">;
+type WorkflowStepStatus = "completed" | "failed" | "blocked" | "paused" | "detached" | "timed-out";
+
+export function workflowChildSucceeded(result: ChildOutcome): boolean {
+	return result.exitCode === 0 && !result.interrupted && !result.detached && !result.timedOut && result.acceptance?.status !== "blocked";
+}
+
+export async function runParallelTasks<T, R extends ChildOutcome>(input: {
+	tasks: T[];
+	concurrency: number;
+	failFast?: boolean;
+	signal?: AbortSignal;
+	interruptSignal?: AbortSignal;
+	runTask: (task: T, index: number, failFastSignal: AbortSignal) => Promise<R>;
+	stoppedTask: (task: T, index: number, reason: ParallelStopReason) => R;
+}): Promise<R[]> {
+	const failFast = new AbortController();
+	let stopped: ParallelStopReason | undefined;
+	return mapConcurrent(input.tasks, input.concurrency, async (task, index) => {
+		const reason = input.signal?.aborted ? "cancelled" : input.interruptSignal?.aborted ? "interrupted" : stopped;
+		if (reason) return input.stoppedTask(task, index, reason);
+		const result = await input.runTask(task, index, failFast.signal);
+		// A selected-child stop must not skip independent siblings; whole-group stops use interruptSignal.
+		if (result.detached) stopped ??= "detached";
+		else if (result.timedOut) stopped ??= "timed-out";
+		else if (input.failFast && !result.interrupted && !(result.exitCode === 0 && result.acceptance?.status === "blocked") && !workflowChildSucceeded(result)) {
+			stopped ??= "fail-fast";
+			failFast.abort(FAIL_FAST_REASON);
+		}
+		return result;
+	});
+}
+
+export function completeWorkflowStep(input: {
+	stepIndex: number;
+	stepCount: number;
+	results: WorkflowOutcome[];
+	outputNames?: Array<string | undefined>;
+	previousOutput: string;
+	parallel?: boolean;
+	dynamic?: { step: DynamicParallelStep; items: DynamicMaterializedItem[] };
+}): {
+	advance: boolean;
+	complete: boolean;
+	status: WorkflowStepStatus;
+	failedIndices: number[];
+	timedOutIndex: number;
+	interruptedIndex: number;
+	detachedIndex: number;
+	outputs: ChainOutputMap;
+	previousOutput: string;
+	collection?: DynamicCollectedResult[];
+	error?: string;
+} {
+	const outputs: ChainOutputMap = {};
+	const failedIndices: number[] = [];
+	const timedOutIndex = input.results.findIndex((result) => result.timedOut);
+	const interruptedIndex = input.results.findIndex((result) => result.interrupted);
+	const detachedIndex = input.results.findIndex((result) => result.detached);
+	const blocked = input.results.some((result) => result.exitCode === 0 && result.acceptance?.status === "blocked");
+	for (const [index, result] of input.results.entries()) {
+		if (workflowChildSucceeded(result)) {
+			const name = input.outputNames?.[index];
+			if (name) outputs[name] = outputEntryFromResult(result, input.stepIndex);
+		} else if (!result.timedOut && !result.interrupted && !result.detached && !(result.exitCode === 0 && result.acceptance?.status === "blocked")) {
+			failedIndices.push(index);
+		}
+	}
+	let status: WorkflowStepStatus = failedIndices.length > 0 ? "failed"
+		: timedOutIndex >= 0 ? "timed-out"
+		: blocked ? "blocked"
+		: interruptedIndex >= 0 ? "paused"
+		: detachedIndex >= 0 ? "detached" : "completed";
+	let error: string | undefined;
+	let collection: DynamicCollectedResult[] | undefined;
+	let previousOutput = input.previousOutput;
+	if (status === "completed" && input.dynamic) {
+		const { step, items } = input.dynamic;
+		try {
+			if (items.length !== input.results.length) throw new Error("Dynamic fanout did not complete every child.");
+			collection = collectDynamicResults(step, items, input.results);
+			validateDynamicCollection(step.collect.outputSchema, collection);
+			outputs[step.collect.as] = { text: JSON.stringify(collection), structured: collection, agent: step.parallel.agent, stepIndex: input.stepIndex };
+			previousOutput = items.length === 0 ? "Dynamic fanout produced 0 results." : aggregateParallelOutputs(input.results,
+				(index, agent) => `=== Dynamic Item ${index + 1} (${agent}, key ${items[index]?.key ?? index}) ===`);
+		} catch (cause) {
+			error = cause instanceof Error ? cause.message : String(cause);
+			status = "failed";
+		}
+	} else if (status === "completed") {
+		previousOutput = input.parallel ? aggregateParallelOutputs(input.results) : input.results[0]?.output ?? input.previousOutput;
+	}
+	const advance = status === "completed";
+	return {
+		advance,
+		complete: advance && input.stepIndex + 1 === input.stepCount,
+		status,
+		failedIndices,
+		timedOutIndex,
+		interruptedIndex,
+		detachedIndex,
+		outputs,
+		previousOutput,
+		collection,
+		error,
+	};
+}