pi-subagents 0.24.4 → 0.27.0

package/src/shared/types.ts

@@ -19,6 +19,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;
@@ -83,6 +128,8 @@ export interface ControlEvent {
 	agent: string;
 	index?: number;
 	runId: string;
+	nestedRunId?: string;
+	nestingPath?: NestedRunAddress["path"];
 	message: string;
 	reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "time_threshold" | "turn_threshold" | "token_threshold";
 	turns?: number;
@@ -98,6 +145,21 @@ export interface ControlEvent {
 export type SubagentResultStatus = "completed" | "failed" | "paused" | "detached";
 export type SubagentRunMode = "single" | "parallel" | "chain";
 
+export type PublicNestedStepSummary = Pick<
+	NestedStepSummary,
+	"agent" | "status" | "sessionFile" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "startedAt" | "endedAt" | "error"
+> & {
+	children?: PublicNestedRunSummary[];
+};
+
+export type PublicNestedRunSummary = Pick<
+	NestedRunSummary,
+	"id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "totalTokens" | "startedAt" | "endedAt" | "lastUpdate" | "error"
+> & {
+	steps?: PublicNestedStepSummary[];
+	children?: PublicNestedRunSummary[];
+};
+
 export interface SubagentResultIntercomChild {
 	agent: string;
 	status: SubagentResultStatus;
@@ -106,6 +168,7 @@ export interface SubagentResultIntercomChild {
 	artifactPath?: string;
 	sessionPath?: string;
 	intercomTarget?: string;
+	children?: PublicNestedRunSummary[];
 }
 
 export interface SubagentResultIntercomPayload {
@@ -176,6 +239,175 @@ export interface ModelAttempt {
 	usage?: Usage;
 }
 
+export type AcceptanceProvenanceLevel = "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 {
+	criteria?: Array<string | AcceptanceGate>;
+	evidence?: AcceptanceEvidenceKind[];
+	verify?: AcceptanceVerifyCommand[];
+	review?: AcceptanceReviewGate;
+	stopRules?: string[];
+	maxFinalizationTurns?: number;
+}
+
+export type AcceptanceInput = AcceptanceConfig;
+
+export interface ResolvedAcceptanceGate extends AcceptanceGate {
+	id: string;
+	must: string;
+	evidence: AcceptanceEvidenceKind[];
+	severity: "required" | "recommended";
+}
+
+export interface ResolvedAcceptanceConfig {
+	level: AcceptanceProvenanceLevel;
+	explicit: boolean;
+	inferredReason: string[];
+	criteria: ResolvedAcceptanceGate[];
+	evidence: AcceptanceEvidenceKind[];
+	verify: AcceptanceVerifyCommand[];
+	review?: AcceptanceReviewGate;
+	stopRules: string[];
+	finalization: {
+		mode: "none" | "self-review-loop";
+		maxTurns: number;
+	};
+}
+
+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 AcceptanceFinalizationTurn {
+	turn: number;
+	prompt: string;
+	status: AcceptanceLedgerStatus;
+	rawOutput?: string;
+	report?: AcceptanceReport;
+	parseError?: string;
+	runtimeChecks: AcceptanceRuntimeCheck[];
+	verifyRuns: AcceptanceVerifyResult[];
+	failureMessage?: string;
+}
+
+export interface AcceptanceFinalizationLedger {
+	mode: "self-review-loop";
+	status: "not-run" | "completed" | "failed";
+	maxTurns: number;
+	turns: AcceptanceFinalizationTurn[];
+}
+
+export interface AcceptanceLedger {
+	status: AcceptanceLedgerStatus;
+	explicit: boolean;
+	effectiveAcceptance: ResolvedAcceptanceConfig;
+	inferredReason: string[];
+	criteria: ResolvedAcceptanceGate[];
+	childReport?: AcceptanceReport;
+	childReportParseError?: string;
+	initialChildReport?: AcceptanceReport;
+	initialChildReportParseError?: string;
+	runtimeChecks: AcceptanceRuntimeCheck[];
+	verifyRuns: AcceptanceVerifyResult[];
+	reviewResult?: AcceptanceReviewResult;
+	finalization?: AcceptanceFinalizationLedger;
+	parentDecision?: {
+		status: "accepted" | "rejected";
+		at: string;
+		reason?: string;
+	};
+}
+
 export interface SingleResult {
 	agent: string;
 	task: string;
@@ -203,6 +435,10 @@ export interface SingleResult {
 	savedOutputPath?: string;
 	outputReference?: SavedOutputReference;
 	outputSaveError?: string;
+	structuredOutput?: unknown;
+	structuredOutputPath?: string;
+	structuredOutputSchemaPath?: string;
+	acceptance?: AcceptanceLedger;
 }
 
 export interface Details {
@@ -229,6 +465,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;
 }
 
 // ============================================================================
@@ -261,6 +499,76 @@ export interface AsyncParallelGroupStatus {
 	stepIndex: number;
 }
 
+export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused";
+export type NestedOwnerState = "live" | "gone" | "unknown";
+
+export interface NestedRunAddress {
+	id: string;
+	parentRunId: string;
+	parentStepIndex?: number;
+	parentAgent?: string;
+	depth: number;
+	path: Array<{ runId: string; stepIndex?: number; agent?: string }>;
+}
+
+export interface NestedStepSummary {
+	agent: string;
+	status: "pending" | "running" | "complete" | "completed" | "failed" | "paused";
+	sessionFile?: string;
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	startedAt?: number;
+	endedAt?: number;
+	error?: string;
+	children?: NestedRunSummary[];
+}
+
+export interface NestedRunSummary extends NestedRunAddress {
+	asyncDir?: string;
+	pid?: number;
+	sessionId?: string;
+	sessionFile?: string;
+	intercomTarget?: string;
+	ownerIntercomTarget?: string;
+	leafIntercomTarget?: string;
+	ownerState?: NestedOwnerState;
+	controlInbox?: string;
+	capabilityToken?: string;
+	mode?: SubagentRunMode;
+	state: NestedRunState;
+	agent?: string;
+	agents?: string[];
+	currentStep?: number;
+	chainStepCount?: number;
+	parallelGroups?: AsyncParallelGroupStatus[];
+	steps?: NestedStepSummary[];
+	children?: NestedRunSummary[];
+	activityState?: ActivityState;
+	lastActivityAt?: number;
+	currentTool?: string;
+	currentToolStartedAt?: number;
+	currentPath?: string;
+	turnCount?: number;
+	toolCount?: number;
+	totalTokens?: TokenUsage;
+	startedAt?: number;
+	endedAt?: number;
+	lastUpdate?: number;
+	error?: string;
+}
+
+export interface NestedRouteInfo {
+	rootRunId: string;
+	eventSink: string;
+	controlInbox: string;
+	capabilityToken: string;
+}
+
 export interface AsyncStartedEvent {
 	id?: string;
 	asyncDir?: string;
@@ -272,6 +580,8 @@ export interface AsyncStartedEvent {
 	chain?: string[];
 	chainStepCount?: number;
 	parallelGroups?: AsyncParallelGroupStatus[];
+	workflowGraph?: WorkflowGraphSnapshot;
+	nestedRoute?: NestedRouteInfo;
 }
 
 export interface AsyncStatus {
@@ -294,9 +604,15 @@ 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;
 		activityState?: ActivityState;
 		lastActivityAt?: number;
@@ -319,11 +635,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] & {
@@ -361,6 +682,8 @@ export interface AsyncJobState {
 	totalTokens?: TokenUsage;
 	sessionFile?: string;
 	controlEventCursor?: number;
+	nestedRoute?: NestedRouteInfo;
+	nestedChildren?: NestedRunSummary[];
 }
 
 export interface ForegroundResumeChild {
@@ -398,6 +721,8 @@ export interface SubagentState {
 		turnCount?: number;
 		tokens?: number;
 		toolCount?: number;
+		nestedRoute?: NestedRouteInfo;
+		nestedChildren?: NestedRunSummary[];
 		interrupt?: () => boolean;
 	}>;
 	lastForegroundControlId: string | null;
@@ -473,6 +798,7 @@ export interface RunSyncOptions {
 	outputPath?: string;
 	outputMode?: OutputMode;
 	maxSubagentDepth?: number;
+	nestedRoute?: NestedRouteInfo;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
 	/** Registry models available for heuristic bare-model resolution */
@@ -481,6 +807,18 @@ export interface RunSyncOptions {
 	preferredModelProvider?: 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";
@@ -495,6 +833,12 @@ interface TopLevelParallelConfig {
 	concurrency?: number;
 }
 
+interface ExtensionChainConfig {
+	dynamicFanout?: {
+		maxItems?: number;
+	};
+}
+
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	forceTopLevelAsync?: boolean;
@@ -502,6 +846,7 @@ export interface ExtensionConfig {
 	maxSubagentDepth?: number;
 	control?: ControlConfig;
 	parallel?: TopLevelParallelConfig;
+	chain?: ExtensionChainConfig;
 	worktreeSetupHook?: string;
 	worktreeSetupHookTimeoutMs?: number;
 	intercomBridge?: IntercomBridgeConfig;

package/src/slash/slash-commands.ts

@@ -5,7 +5,8 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Key, matchesKey } from "@earendil-works/pi-tui";
 import { discoverAgents, discoverAgentsAll, type ChainConfig } from "../agents/agents.ts";
 import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
-import { isParallelStep, type ChainStep } from "../shared/settings.ts";
+import { isDynamicParallelStep, isParallelStep, type ChainStep } from "../shared/settings.ts";
+import { assertJsonSchemaObject } from "../runs/shared/structured-output.ts";
 import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
 import {
 	applySlashUpdate,
@@ -20,6 +21,7 @@ import {
 	SLASH_SUBAGENT_RESPONSE_EVENT,
 	SLASH_SUBAGENT_STARTED_EVENT,
 	SLASH_SUBAGENT_UPDATE_EVENT,
+	type JsonSchemaObject,
 	type SingleResult,
 	type SubagentState,
 } from "../shared/types.ts";
@@ -123,12 +125,48 @@ const makeChainCompletions = (state: SubagentState) => (prefix: string) => {
 		.map((chain) => ({ value: chain.name, label: chain.name }));
 };
 
+function loadSavedOutputSchema(chain: ChainConfig, stepAgent: string, outputSchema: unknown): JsonSchemaObject | undefined {
+	if (outputSchema === undefined) return undefined;
+	if (typeof outputSchema === "string") {
+		const schemaPath = path.isAbsolute(outputSchema)
+			? outputSchema
+			: path.join(path.dirname(chain.filePath), outputSchema);
+		const parsed = JSON.parse(fs.readFileSync(schemaPath, "utf-8")) as unknown;
+		assertJsonSchemaObject(parsed, `outputSchema for chain '${chain.name}' step '${stepAgent}' (${schemaPath})`);
+		return parsed;
+	}
+	assertJsonSchemaObject(outputSchema, `outputSchema for chain '${chain.name}' step '${stepAgent}'`);
+	return outputSchema;
+}
+
 const mapSavedChainSteps = (chain: ChainConfig, worktree = false): ChainStep[] => {
-	return (chain.steps as Array<ChainStep & { skills?: string[] | false }>).map((step) => {
-		if (isParallelStep(step)) return worktree ? { ...step, worktree: true } : { ...step };
+	return (chain.steps as unknown as Array<ChainStep & { skills?: string[] | false }>).map((step) => {
+		if (isParallelStep(step)) {
+			const parallel = step.parallel.map((task) => {
+				const { outputSchema: rawOutputSchema, ...rest } = task as typeof task & { outputSchema?: unknown };
+				const outputSchema = loadSavedOutputSchema(chain, task.agent, rawOutputSchema);
+				return { ...rest, ...(outputSchema ? { outputSchema } : {}) };
+			});
+			return { ...step, parallel, ...(worktree ? { worktree: true } : {}) };
+		}
+		if (isDynamicParallelStep(step)) {
+			const { outputSchema: rawOutputSchema, ...parallelRest } = step.parallel as typeof step.parallel & { outputSchema?: unknown };
+			const outputSchema = loadSavedOutputSchema(chain, step.parallel.agent, rawOutputSchema);
+			const collectSchema = loadSavedOutputSchema(chain, `${step.collect.as} collection`, step.collect.outputSchema);
+			return {
+				...step,
+				parallel: { ...parallelRest, ...(outputSchema ? { outputSchema } : {}) },
+				collect: { ...step.collect, ...(collectSchema ? { outputSchema: collectSchema } : {}) },
+			};
+		}
+		const outputSchema = loadSavedOutputSchema(chain, step.agent, (step as { outputSchema?: unknown }).outputSchema);
 		return {
 			agent: step.agent,
 			task: step.task || undefined,
+			...(step.phase ? { phase: step.phase } : {}),
+			...(step.label ? { label: step.label } : {}),
+			...(step.as ? { as: step.as } : {}),
+			...(outputSchema ? { outputSchema } : {}),
 			output: step.output,
 			outputMode: step.outputMode,
 			reads: step.reads,