pi-subagents 0.25.0 → 0.27.0

package/src/runs/shared/pi-args.ts

@@ -4,6 +4,8 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { encodeNestedPathEnv, parseNestedPathEnv, type NestedPathEntry } from "./nested-path.ts";
 import { resolveMcpDirectToolNames } from "./mcp-direct-tool-allowlist.ts";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV } from "./structured-output.ts";
+import type { JsonSchemaObject } from "../../shared/types.ts";
 
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"];
 const TASK_ARG_LIMIT = 8000;
@@ -54,6 +56,11 @@ interface BuildPiArgsInput {
 	parentDepth?: number;
 	parentPath?: NestedPathEntry[];
 	parentCapabilityToken?: string;
+	structuredOutput?: {
+		schema: JsonSchemaObject;
+		schemaPath: string;
+		outputPath: string;
+	};
 }
 
 interface BuildPiArgsResult {
@@ -204,6 +211,10 @@ export function buildPiArgs(input: BuildPiArgsInput): BuildPiArgsResult {
 	} else {
 		env.MCP_DIRECT_TOOLS = "__none__";
 	}
+	if (input.structuredOutput) {
+		env[STRUCTURED_OUTPUT_CAPTURE_ENV] = input.structuredOutput.outputPath;
+		env[STRUCTURED_OUTPUT_SCHEMA_ENV] = input.structuredOutput.schemaPath;
+	}
 
 	return { args, env, tempDir };
 }

package/src/runs/shared/structured-output.ts

@@ -0,0 +1,77 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { Compile } from "typebox/compile";
+import type { JsonSchemaObject } from "../../shared/types.ts";
+
+export const STRUCTURED_OUTPUT_SCHEMA_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA";
+export const STRUCTURED_OUTPUT_CAPTURE_ENV = "PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE";
+
+export interface StructuredOutputRuntime {
+	schema: JsonSchemaObject;
+	schemaPath: string;
+	outputPath: string;
+}
+
+interface CompiledJsonSchema {
+	Check(value: unknown): boolean;
+	Errors(value: unknown): Iterable<{ instancePath?: string; message?: string }>;
+}
+
+export function assertJsonSchemaObject(schema: unknown, label = "outputSchema"): asserts schema is JsonSchemaObject {
+	if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+		throw new Error(`${label} must be a JSON Schema object.`);
+	}
+}
+
+export function createStructuredOutputRuntime(schema: JsonSchemaObject, baseDir?: string): StructuredOutputRuntime {
+	assertJsonSchemaObject(schema);
+	const rootDir = baseDir ?? os.tmpdir();
+	fs.mkdirSync(rootDir, { recursive: true });
+	const dir = fs.mkdtempSync(path.join(rootDir, "pi-subagent-structured-"));
+	const schemaPath = path.join(dir, "schema.json");
+	const outputPath = path.join(dir, "output.json");
+	fs.writeFileSync(schemaPath, JSON.stringify(schema), { mode: 0o600 });
+	return { schema, schemaPath, outputPath };
+}
+
+export function validateStructuredOutputValue(schema: JsonSchemaObject, value: unknown): { status: "valid" } | { status: "invalid"; message: string } {
+	let validator: CompiledJsonSchema;
+	try {
+		validator = (Compile as (schema: unknown) => CompiledJsonSchema)(schema);
+	} catch (error) {
+		return { status: "invalid", message: `invalid outputSchema: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	if (validator.Check(value)) return { status: "valid" };
+	const errors = [...validator.Errors(value)]
+		.slice(0, 8)
+		.map((error) => {
+			const pathText = error.instancePath ? error.instancePath.replace(/^\//, "").replace(/\//g, ".") : "root";
+			return `${pathText}: ${error.message}`;
+		});
+	return { status: "invalid", message: errors.join("; ") || "schema validation failed" };
+}
+
+export function readStructuredOutput(runtime: StructuredOutputRuntime): { value?: unknown; error?: string } {
+	if (!fs.existsSync(runtime.outputPath)) {
+		return { error: "Missing structured_output call; this step has outputSchema and must finish by calling structured_output." };
+	}
+	let value: unknown;
+	try {
+		value = JSON.parse(fs.readFileSync(runtime.outputPath, "utf-8"));
+	} catch (error) {
+		return { error: `Failed to read structured output: ${error instanceof Error ? error.message : String(error)}` };
+	}
+	const validation = validateStructuredOutputValue(runtime.schema, value);
+	if (validation.status === "invalid") return { error: `Structured output validation failed: ${validation.message}` };
+	return { value };
+}
+
+export function cleanupStructuredOutputRuntime(runtime: StructuredOutputRuntime | undefined): void {
+	if (!runtime) return;
+	try {
+		fs.rmSync(path.dirname(runtime.schemaPath), { recursive: true, force: true });
+	} catch {
+		// Best-effort temp cleanup.
+	}
+}

package/src/runs/shared/subagent-prompt-runtime.ts

@@ -1,10 +1,20 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_FANOUT_CHILD_ENV } from "./pi-args.ts";
+import { STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
+import type { JsonSchemaObject } from "../../shared/types.ts";
 
 const SUBAGENT_INHERIT_PROJECT_CONTEXT_ENV = "PI_SUBAGENT_INHERIT_PROJECT_CONTEXT";
 const SUBAGENT_INHERIT_SKILLS_ENV = "PI_SUBAGENT_INHERIT_SKILLS";
 export const SUBAGENT_INTERCOM_SESSION_NAME_ENV = "PI_SUBAGENT_INTERCOM_SESSION_NAME";
 
+const STRUCTURED_OUTPUT_INSTRUCTIONS = [
+	"This subagent step has a strict structured output contract.",
+	"Your final action must be to call the `structured_output` tool with JSON matching the provided schema.",
+	"Do not rely on prose-only completion; if you do not call `structured_output`, the parent will fail this step.",
+].join("\n");
+
 export const CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS = [
 	"You are a child subagent, not the parent orchestrator.",
 	"The parent session owns delegation, orchestration, review fanout, and follow-up worker launches.",
@@ -94,7 +104,8 @@ export function rewriteSubagentPrompt(
 	rewritten = stripSubagentOrchestrationSkill(rewritten);
 	rewritten = stripChildBoundaryInstructions(rewritten);
 	const boundary = options.fanoutChild ? CHILD_FANOUT_BOUNDARY_INSTRUCTIONS : CHILD_SUBAGENT_BOUNDARY_INSTRUCTIONS;
-	return `${boundary}\n\n${rewritten}`;
+	const structured = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV] ? `\n\n${STRUCTURED_OUTPUT_INSTRUCTIONS}` : "";
+	return `${boundary}${structured}\n\n${rewritten}`;
 }
 
 function isParentOnlySubagentMessage(message: unknown): boolean {
@@ -143,13 +154,52 @@ export function stripParentOnlySubagentMessages(messages: unknown[]): unknown[]
 }
 
 export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
-	pi.on("context", (event) => {
+	const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
+	const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
+	if (structuredOutputPath && structuredSchemaPath) {
+		const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
+		const parameters = {
+			type: "object",
+			properties: { value: schema },
+			required: ["value"],
+			additionalProperties: false,
+		};
+		const registerTool = pi.registerTool as unknown as (tool: {
+			name: string;
+			label: string;
+			description: string;
+			parameters: unknown;
+			execute: (_id: string, params: { value: unknown }) => Promise<unknown>;
+		}) => void;
+		registerTool({
+			name: "structured_output",
+			label: "Structured Output",
+			description: "Submit the required final structured output for this subagent step. This terminates the step.",
+			parameters: parameters as never,
+			async execute(_id: string, params: { value: unknown }) {
+				const validation = validateStructuredOutputValue(schema, params.value);
+				if (validation.status === "invalid") {
+					throw new Error(`Structured output validation failed: ${validation.message}`);
+				}
+				fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
+				fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
+				return {
+					content: [{ type: "text", text: "Structured output captured." }],
+					details: { path: structuredOutputPath },
+					terminate: true,
+				};
+			},
+		});
+	}
+
+	const onRuntimeEvent = pi.on as unknown as (event: string, handler: (event: unknown) => unknown) => void;
+	onRuntimeEvent("context", (event: { messages: unknown[] }) => {
 		const messages = stripParentOnlySubagentMessages(event.messages);
 		if (messages === event.messages) return undefined;
 		return { messages };
 	});
 
-	pi.on("before_agent_start", async (event) => {
+	onRuntimeEvent("before_agent_start", async (event: { systemPrompt: string }) => {
 		const intercomSessionName = process.env[SUBAGENT_INTERCOM_SESSION_NAME_ENV]?.trim();
 		if (intercomSessionName && typeof pi.setSessionName === "function") {
 			pi.setSessionName(intercomSessionName);

package/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/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";
 
 /**
@@ -63,7 +63,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/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,18 +74,48 @@ 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;
 }
 
 /** Parallel step: multiple agents running concurrently */
-interface ParallelStep {
+export interface ParallelStep {
 	parallel: ParallelTaskItem[];
 	concurrency?: number;
 	failFast?: boolean;
 	worktree?: boolean;
+	cwd?: string;
 }
 
 /** Union type for chain steps */
-export type ChainStep = SequentialStep | ParallelStep;
+export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
 
 // =============================================================================
 // Type Guards
@@ -86,11 +125,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];
 }
 
@@ -160,6 +206,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;