@bastani/atomic 0.8.24-alpha.2 → 0.8.24-alpha.3

package/dist/builtin/subagents/src/runs/shared/workflow-graph.ts

@@ -0,0 +1,206 @@
+import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
+import type { SingleResult, SubagentRunMode, WorkflowGraphNode, WorkflowGraphSnapshot, WorkflowNodeStatus } from "../../shared/types.ts";
+
+export interface WorkflowGraphBuildInput {
+	runId: string;
+	mode?: SubagentRunMode;
+	steps: ChainStep[];
+	results?: Array<Pick<SingleResult, "exitCode" | "detached" | "interrupted" | "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 "detached":
+			return "detached";
+		case "pending":
+			return "pending";
+		default:
+			return undefined;
+	}
+}
+
+function resultStatus(result: Pick<SingleResult, "exitCode" | "detached" | "interrupted"> | undefined): WorkflowNodeStatus | undefined {
+	if (!result) return undefined;
+	if (result.detached) return "detached";
+	if (result.interrupted) return "paused";
+	return result.exitCode === 0 ? "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 === "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/dist/builtin/subagents/src/shared/formatters.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Usage, SingleResult } from "./types.ts";
 import type { ChainStep } from "./settings.ts";
-import { isParallelStep } from "./settings.ts";
+import { isDynamicParallelStep, isParallelStep } from "./settings.ts";
 import { splitKnownThinkingSuffix, THINKING_LEVELS } from "./model-info.ts";
 
 /**
@@ -70,7 +70,7 @@ export function buildChainSummary(
 	failedStep?: { index: number; error: string },
 ): string {
 	const stepNames = steps
-		.map((step) => (isParallelStep(step) ? `parallel[${step.parallel.length}]` : step.agent))
+		.map((step) => (isParallelStep(step) ? `parallel[${step.parallel.length}]` : isDynamicParallelStep(step) ? `expand:${step.parallel.agent}` : step.agent))
 		.join(" → ");
 
 	const totalDuration = results.reduce((sum, r) => sum + (r.progress?.durationMs || 0), 0);

package/dist/builtin/subagents/src/shared/settings.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
 import { normalizeSkillInput } from "../agents/skills.ts";
-import { CHAIN_RUNS_DIR, type OutputMode } from "./types.ts";
+import { CHAIN_RUNS_DIR, type AcceptanceInput, type JsonSchemaObject, type OutputMode } from "./types.ts";
 const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours
 const INITIAL_PROGRESS_CONTENT = "# Progress\n\n## Status\nIn Progress\n\n## Tasks\n\n## Files Changed\n\n## Notes\n";
 
@@ -44,6 +44,10 @@ function normalizeOutputOverride(output: string | false | undefined): string | f
 export interface SequentialStep {
 	agent: string;
 	task?: string;
+	phase?: string;
+	label?: string;
+	as?: string;
+	outputSchema?: JsonSchemaObject;
 	cwd?: string;
 	output?: string | false;
 	outputMode?: OutputMode;
@@ -51,12 +55,17 @@ export interface SequentialStep {
 	progress?: boolean;
 	skill?: string | string[] | false;
 	model?: string;
+	acceptance?: AcceptanceInput;
 }
 
 /** Parallel task item within a parallel step */
-interface ParallelTaskItem {
+export interface ParallelTaskItem {
 	agent: string;
 	task?: string;
+	phase?: string;
+	label?: string;
+	as?: string;
+	outputSchema?: JsonSchemaObject;
 	cwd?: string;
 	count?: number;
 	output?: string | false;
@@ -65,10 +74,40 @@ interface ParallelTaskItem {
 	progress?: boolean;
 	skill?: string | string[] | false;
 	model?: string;
+	acceptance?: AcceptanceInput;
+}
+
+export interface DynamicExpandSpec {
+	from: {
+		output: string;
+		path: string;
+	};
+	item?: string;
+	key?: string;
+	maxItems?: number;
+	onEmpty?: "skip" | "fail";
+}
+
+export type DynamicParallelTemplate = Omit<ParallelTaskItem, "as" | "count">;
+
+export interface DynamicCollectSpec {
+	as: string;
+	outputSchema?: JsonSchemaObject;
+}
+
+export interface DynamicParallelStep {
+	expand: DynamicExpandSpec;
+	parallel: DynamicParallelTemplate;
+	collect: DynamicCollectSpec;
+	concurrency?: number;
+	failFast?: boolean;
+	phase?: string;
+	label?: string;
+	acceptance?: AcceptanceInput;
 }
 
 /** Parallel step: multiple agents running concurrently */
-interface ParallelStep {
+export interface ParallelStep {
 	parallel: ParallelTaskItem[];
 	cwd?: string;
 	concurrency?: number;
@@ -77,7 +116,7 @@ interface ParallelStep {
 }
 
 /** Union type for chain steps */
-export type ChainStep = SequentialStep | ParallelStep;
+export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
 
 // =============================================================================
 // Type Guards
@@ -87,11 +126,18 @@ export function isParallelStep(step: ChainStep): step is ParallelStep {
 	return "parallel" in step && Array.isArray((step as ParallelStep).parallel);
 }
 
+export function isDynamicParallelStep(step: ChainStep): step is DynamicParallelStep {
+	return "expand" in step && "collect" in step && "parallel" in step && !Array.isArray((step as { parallel?: unknown }).parallel);
+}
+
 /** Get all agent names in a step (single for sequential, multiple for parallel) */
 export function getStepAgents(step: ChainStep): string[] {
 	if (isParallelStep(step)) {
 		return step.parallel.map((t) => t.agent);
 	}
+	if (isDynamicParallelStep(step)) {
+		return [step.parallel.agent];
+	}
 	return [step.agent];
 }
 
@@ -161,6 +207,9 @@ export function resolveChainTemplates(
 				return "{previous}";
 			});
 		}
+		if (isDynamicParallelStep(step)) {
+			return step.parallel.task ?? "{previous}";
+		}
 		// Sequential step: existing logic
 		const seq = step as SequentialStep;
 		if (seq.task) return seq.task;

package/dist/builtin/subagents/src/shared/types.ts

@@ -26,6 +26,51 @@ export interface MaxOutputConfig {
 
 export type OutputMode = "inline" | "file-only";
 
+export type JsonSchemaObject = Record<string, unknown>;
+
+export interface ChainOutputMapEntry {
+	text: string;
+	structured?: unknown;
+	agent: string;
+	stepIndex: number;
+}
+
+export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
+
+export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "detached";
+
+export interface WorkflowGraphNode {
+	id: string;
+	kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
+	agent?: string;
+	phase?: string;
+	label: string;
+	status: WorkflowNodeStatus;
+	flatIndex?: number;
+	stepIndex?: number;
+	children?: WorkflowGraphNode[];
+	dynamic?: {
+		sourceOutput: string;
+		sourcePath: string;
+		itemName: string;
+		maxItems?: number;
+		collectAs?: string;
+	};
+	itemKey?: string;
+	outputName?: string;
+	structured?: boolean;
+	acceptanceStatus?: AcceptanceLedgerStatus;
+	error?: string;
+}
+
+export interface WorkflowGraphSnapshot {
+	runId: string;
+	mode: "chain" | "parallel" | "single";
+	phases: Array<{ title: string; nodeIds: string[] }>;
+	nodes: WorkflowGraphNode[];
+	currentNodeId?: string;
+}
+
 export interface SavedOutputReference {
 	path: string;
 	bytes: number;
@@ -202,6 +247,151 @@ export interface ModelAttempt {
 	usage?: Usage;
 }
 
+export type AcceptanceLevel = "auto" | "none" | "attested" | "checked" | "verified" | "reviewed";
+
+export type AcceptanceEvidenceKind =
+	| "changed-files"
+	| "tests-added"
+	| "commands-run"
+	| "validation-output"
+	| "residual-risks"
+	| "no-staged-files"
+	| "diff-summary"
+	| "review-findings"
+	| "manual-notes";
+
+export interface AcceptanceGate {
+	id: string;
+	must: string;
+	evidence?: AcceptanceEvidenceKind[];
+	severity?: "required" | "recommended";
+}
+
+export interface AcceptanceVerifyCommand {
+	id: string;
+	command: string;
+	timeoutMs?: number;
+	cwd?: string;
+	env?: Record<string, string>;
+	allowFailure?: boolean;
+}
+
+export interface AcceptanceReviewGate {
+	agent?: string;
+	focus?: string;
+	required?: boolean;
+}
+
+export interface AcceptanceConfig {
+	level?: AcceptanceLevel;
+	criteria?: Array<string | AcceptanceGate>;
+	evidence?: AcceptanceEvidenceKind[];
+	verify?: AcceptanceVerifyCommand[];
+	review?: AcceptanceReviewGate | false;
+	stopRules?: string[];
+	reason?: string;
+}
+
+export type AcceptanceInput = AcceptanceLevel | false | AcceptanceConfig;
+
+export interface ResolvedAcceptanceGate extends AcceptanceGate {
+	id: string;
+	must: string;
+	evidence: AcceptanceEvidenceKind[];
+	severity: "required" | "recommended";
+}
+
+export interface ResolvedAcceptanceConfig {
+	level: Exclude<AcceptanceLevel, "auto">;
+	explicit: boolean;
+	inferredReason: string[];
+	criteria: ResolvedAcceptanceGate[];
+	evidence: AcceptanceEvidenceKind[];
+	verify: AcceptanceVerifyCommand[];
+	review?: AcceptanceReviewGate | false;
+	stopRules: string[];
+	reason?: string;
+}
+
+export interface AcceptanceReport {
+	criteriaSatisfied?: Array<{
+		id?: string;
+		status: "satisfied" | "not-satisfied" | "not-applicable";
+		evidence: string;
+	}>;
+	changedFiles?: string[];
+	testsAddedOrUpdated?: string[];
+	commandsRun?: Array<{
+		command: string;
+		result: "passed" | "failed" | "not-run";
+		summary: string;
+	}>;
+	validationOutput?: string[];
+	residualRisks?: string[];
+	noStagedFiles?: boolean;
+	diffSummary?: string;
+	reviewFindings?: string[];
+	manualNotes?: string;
+	notes?: string;
+}
+
+export type AcceptanceRuntimeCheckStatus = "passed" | "failed" | "not-applicable";
+
+export interface AcceptanceRuntimeCheck {
+	id: string;
+	status: AcceptanceRuntimeCheckStatus;
+	message: string;
+}
+
+export interface AcceptanceVerifyResult {
+	id: string;
+	command: string;
+	cwd?: string;
+	exitCode: number | null;
+	status: "passed" | "failed" | "timed-out" | "allowed-failure";
+	stdout?: string;
+	stderr?: string;
+	durationMs: number;
+}
+
+export interface AcceptanceReviewResult {
+	status: "no-blockers" | "blockers" | "needs-parent-decision";
+	findings: Array<{
+		severity: "blocker" | "non-blocking";
+		file?: string;
+		issue: string;
+		rationale: string;
+	}>;
+}
+
+export type AcceptanceLedgerStatus =
+	| "not-required"
+	| "claimed"
+	| "attested"
+	| "checked"
+	| "verified"
+	| "reviewed"
+	| "accepted"
+	| "rejected";
+
+export interface AcceptanceLedger {
+	status: AcceptanceLedgerStatus;
+	explicit: boolean;
+	effectiveAcceptance: ResolvedAcceptanceConfig;
+	inferredReason: string[];
+	criteria: ResolvedAcceptanceGate[];
+	childReport?: AcceptanceReport;
+	childReportParseError?: string;
+	runtimeChecks: AcceptanceRuntimeCheck[];
+	verifyRuns: AcceptanceVerifyResult[];
+	reviewResult?: AcceptanceReviewResult;
+	parentDecision?: {
+		status: "accepted" | "rejected";
+		at: string;
+		reason?: string;
+	};
+}
+
 export interface SingleResult {
 	agent: string;
 	task: string;
@@ -230,6 +420,10 @@ export interface SingleResult {
 	savedOutputPath?: string;
 	outputReference?: SavedOutputReference;
 	outputSaveError?: string;
+	structuredOutput?: unknown;
+	structuredOutputPath?: string;
+	structuredOutputSchemaPath?: string;
+	acceptance?: AcceptanceLedger;
 }
 
 export interface Details {
@@ -256,6 +450,8 @@ export interface Details {
 	chainAgents?: string[];      // Agent names in order, e.g., ["scout", "planner"]
 	totalSteps?: number;         // Total steps in chain
 	currentStepIndex?: number;   // 0-indexed current step (for running chains)
+	workflowGraph?: WorkflowGraphSnapshot;
+	outputs?: ChainOutputMap;
 }
 
 // Upstream AgentToolResult omits the runtime isError flag that subagent tool results still emit/read.
@@ -372,6 +568,7 @@ export interface AsyncStartedEvent {
 	chain?: string[];
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
+	workflowGraph?: WorkflowGraphSnapshot;
 	nestedRoute?: NestedRouteInfo;
 }
 
@@ -395,8 +592,13 @@ export interface AsyncStatus {
 	currentStep?: number;
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
+	workflowGraph?: WorkflowGraphSnapshot;
 	steps?: Array<{
 		agent: string;
+		phase?: string;
+		label?: string;
+		outputName?: string;
+		structured?: boolean;
 		status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
 		children?: NestedRunSummary[];
 		sessionFile?: string;
@@ -422,11 +624,16 @@ export interface AsyncStatus {
 		attemptedModels?: string[];
 		modelAttempts?: ModelAttempt[];
 		error?: string;
+		structuredOutput?: unknown;
+		structuredOutputPath?: string;
+		structuredOutputSchemaPath?: string;
+		acceptance?: AcceptanceLedger;
 	}>;
 	sessionDir?: string;
 	outputFile?: string;
 	totalTokens?: TokenUsage;
 	sessionFile?: string;
+	outputs?: ChainOutputMap;
 }
 
 export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
@@ -592,6 +799,18 @@ export interface RunSyncOptions {
 	currentModel?: string;
 	/** Skills to inject (overrides agent default if provided) */
 	skills?: string[];
+	structuredOutput?: {
+		schema: JsonSchemaObject;
+		schemaPath: string;
+		outputPath: string;
+	};
+	acceptance?: AcceptanceInput;
+	acceptanceContext?: {
+		mode?: SubagentRunMode;
+		async?: boolean;
+		dynamic?: boolean;
+		dynamicGroup?: boolean;
+	};
 }
 
 export type IntercomBridgeMode = "off" | "fork-only" | "always";
@@ -606,6 +825,12 @@ interface TopLevelParallelConfig {
 	concurrency?: number;
 }
 
+interface ExtensionChainConfig {
+	dynamicFanout?: {
+		maxItems?: number;
+	};
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;
@@ -613,6 +838,7 @@ export interface ExtensionConfig {
 	maxSubagentDepth?: number;
 	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
+	chain?: ExtensionChainConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	intercomBridge?: IntercomBridgeConfig;

package/dist/builtin/subagents/src/shared/utils.ts

@@ -132,7 +132,8 @@ export function getFinalOutput(messages: Message[]): string {
 			const hasAssistantError = ("errorMessage" in msg && typeof msg.errorMessage === "string" && msg.errorMessage.length > 0)
 				|| ("stopReason" in msg && msg.stopReason === "error");
 			if (hasAssistantError) continue;
-			for (const part of msg.content) {
+			for (let j = msg.content.length - 1; j >= 0; j--) {
+				const part = msg.content[j];
 				if (part.type === "text" && part.text.trim().length > 0) return part.text;
 			}
 		}