pi-subagents 0.25.0 → 0.28.0

package/src/runs/shared/acceptance-finalization.ts

@@ -0,0 +1,173 @@
+import type {
+	AcceptanceFinalizationTurn,
+	AcceptanceLedger,
+	ResolvedAcceptanceConfig,
+} from "../../shared/types.ts";
+import { acceptanceFailureMessage } from "./acceptance-evaluation.ts";
+import { formatEvidenceReportFieldMapping } from "./acceptance-contract.ts";
+import { stripAcceptanceReport } from "./acceptance-reports.ts";
+
+const INITIAL_OUTPUT_LIMIT = 8_000;
+
+function truncateForPrompt(value: string): string {
+	const trimmed = stripAcceptanceReport(value).trim();
+	if (trimmed.length <= INITIAL_OUTPUT_LIMIT) return trimmed || "(initial output was empty after removing acceptance-report)";
+	return `${trimmed.slice(0, INITIAL_OUTPUT_LIMIT)}\n...[truncated]`;
+}
+
+function formatReportForPrompt(ledger: AcceptanceLedger): string {
+	if (ledger.childReport) return JSON.stringify(ledger.childReport, null, 2);
+	return `Missing or malformed acceptance report: ${ledger.childReportParseError ?? "no parse detail"}`;
+}
+
+export function formatAcceptanceFinalizationPrompt(input: {
+	acceptance: ResolvedAcceptanceConfig;
+	initialOutput: string;
+	initialLedger: AcceptanceLedger;
+	turn: number;
+	maxTurns: number;
+	previousFailure?: string;
+}): string {
+	const lines = [
+		"## Acceptance Finalization",
+		"You are continuing the same subagent session. Before this run can be accepted, compare the current work to the acceptance contract and the evidence below.",
+		`This is finalization turn ${input.turn} of ${input.maxTurns}. The run will be rejected if the contract is still not satisfied after turn ${input.maxTurns}.`,
+		"",
+		"If a criterion is incomplete and fixable in this session, keep working now before returning the final report.",
+		"If a criterion cannot be satisfied in this session, report it as not-satisfied, explain the blocker in residualRisks, and say what input would unblock progress.",
+		"Do not claim a criterion is satisfied unless the current work has concrete evidence from files, commands, validation output, or other inspectable artifacts.",
+		"",
+		"## Acceptance Contract",
+		"Criteria:",
+		...(input.acceptance.criteria.length ? input.acceptance.criteria.map((criterion) => `- ${criterion.id}: ${criterion.must}`) : ["- No explicit criteria were configured; satisfy the requested task and required evidence/checks."]),
+		"",
+		`Required evidence: ${input.acceptance.evidence.join(", ") || "none explicitly requested"}`,
+	];
+	if (input.acceptance.evidence.length > 0) {
+		lines.push(
+			"",
+			"Structured evidence must be present in the final `acceptance-report` JSON fields. Markdown sections in the visible answer do not satisfy required evidence by themselves. If the previous visible output already included the evidence, copy or summarize it into the matching JSON field.",
+			"Evidence field mapping:",
+			...formatEvidenceReportFieldMapping(input.acceptance.evidence),
+		);
+	}
+	if (input.acceptance.verify.length > 0) {
+		lines.push("", "Runtime verification commands that must pass:", ...input.acceptance.verify.map((command) => `- ${command.id}: ${command.command}`));
+	}
+	if (input.acceptance.review) {
+		lines.push("", `Independent review gate after self-review: ${input.acceptance.review.required === false ? "optional" : "required"}${input.acceptance.review.agent ? ` by ${input.acceptance.review.agent}` : ""}.`);
+	}
+	if (input.acceptance.stopRules.length > 0) {
+		lines.push("", "Stop rules are hard constraints while deciding whether to continue, stop as blocked, or report success:", ...input.acceptance.stopRules.map((rule) => `- ${rule}`));
+	}
+	lines.push(
+		"",
+		"Initial visible output:",
+		truncateForPrompt(input.initialOutput),
+		"",
+		"Initial acceptance report:",
+		formatReportForPrompt(input.initialLedger),
+	);
+	if (input.previousFailure) {
+		lines.push("", "Previous finalization failure to address:", input.previousFailure);
+	}
+	lines.push(
+		"",
+		"Now do the self-check. If work was missing and you repaired it, report the repaired final state. Finish with exactly one fenced JSON block tagged `acceptance-report`.",
+		"```acceptance-report",
+		JSON.stringify({
+			criteriaSatisfied: [{ id: "criterion-1", status: "satisfied", evidence: "specific proof from the final state" }],
+			changedFiles: [],
+			testsAddedOrUpdated: [],
+			commandsRun: [{ command: "command", result: "passed", summary: "short result" }],
+			validationOutput: [],
+			residualRisks: [],
+			noStagedFiles: true,
+			diffSummary: "concise summary of changed behavior and important files",
+			reviewFindings: [],
+			manualNotes: "manual notes or external evidence, if any",
+			notes: "final self-review summary",
+		}, null, 2),
+		"```",
+	);
+	return lines.join("\n");
+}
+
+export function createFinalizationTurn(input: {
+	turn: number;
+	prompt: string;
+	rawOutput: string;
+	ledger: AcceptanceLedger;
+}): AcceptanceFinalizationTurn {
+	const failureMessage = acceptanceFailureMessage(input.ledger);
+	return {
+		turn: input.turn,
+		prompt: input.prompt,
+		status: input.ledger.status,
+		rawOutput: input.rawOutput,
+		...(input.ledger.childReport ? { report: input.ledger.childReport } : {}),
+		...(input.ledger.childReportParseError ? { parseError: input.ledger.childReportParseError } : {}),
+		runtimeChecks: input.ledger.runtimeChecks,
+		verifyRuns: input.ledger.verifyRuns,
+		...(failureMessage ? { failureMessage } : {}),
+	};
+}
+
+export function createFinalizationProcessFailureTurn(input: {
+	turn: number;
+	prompt: string;
+	rawOutput?: string;
+	message: string;
+}): AcceptanceFinalizationTurn {
+	return {
+		turn: input.turn,
+		prompt: input.prompt,
+		status: "rejected",
+		...(input.rawOutput ? { rawOutput: input.rawOutput } : {}),
+		runtimeChecks: [{ id: "finalization-process", status: "failed", message: input.message }],
+		verifyRuns: [],
+		failureMessage: `Acceptance rejected: ${input.message}`,
+	};
+}
+
+export function attachFinalizationToLedger(input: {
+	initialLedger: AcceptanceLedger;
+	authoritativeLedger: AcceptanceLedger;
+	turns: AcceptanceFinalizationTurn[];
+	status: "completed" | "failed";
+	maxTurns: number;
+}): AcceptanceLedger {
+	return {
+		...input.authoritativeLedger,
+		...(input.initialLedger.childReport ? { initialChildReport: input.initialLedger.childReport } : {}),
+		...(input.initialLedger.childReportParseError ? { initialChildReportParseError: input.initialLedger.childReportParseError } : {}),
+		finalization: {
+			mode: "self-review-loop",
+			status: input.status,
+			maxTurns: input.maxTurns,
+			turns: input.turns,
+		},
+	};
+}
+
+export function buildFinalizationProcessFailureLedger(input: {
+	initialLedger: AcceptanceLedger;
+	turns: AcceptanceFinalizationTurn[];
+	maxTurns: number;
+	message: string;
+}): AcceptanceLedger {
+	return attachFinalizationToLedger({
+		initialLedger: input.initialLedger,
+		authoritativeLedger: {
+			...input.initialLedger,
+			status: "rejected",
+			runtimeChecks: [
+				...input.initialLedger.runtimeChecks,
+				{ id: "finalization-process", status: "failed", message: input.message },
+			],
+		},
+		turns: input.turns,
+		status: "failed",
+		maxTurns: input.maxTurns,
+	});
+}

package/src/runs/shared/acceptance-reports.ts

@@ -0,0 +1,127 @@
+import type {
+	AcceptanceReport,
+} from "../../shared/types.ts";
+
+function extractBalancedJson(text: string, start: number): string | undefined {
+	let depth = 0;
+	let inString = false;
+	let escaped = false;
+	for (let i = start; i < text.length; i++) {
+		const char = text[i]!;
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (char === "\\") escaped = true;
+			else if (char === "\"") inString = false;
+			continue;
+		}
+		if (char === "\"") {
+			inString = true;
+			continue;
+		}
+		if (char === "{") depth++;
+		if (char === "}") {
+			depth--;
+			if (depth === 0) return text.slice(start, i + 1);
+		}
+	}
+	return undefined;
+}
+
+export function parseAcceptanceReport(output: string): { report?: AcceptanceReport; error?: string } {
+	const fenced = [...output.matchAll(/```acceptance-report\s*\n([\s\S]*?)```/gi)]
+		.map((match) => match[1]?.trim())
+		.filter((value): value is string => Boolean(value));
+	const parseErrors: string[] = [];
+	for (const body of fenced) {
+		try {
+			const parsed = JSON.parse(body) as unknown;
+			const report = (parsed && typeof parsed === "object" && "acceptance" in parsed)
+				? (parsed as { acceptance?: unknown }).acceptance
+				: parsed;
+			if (isAcceptanceReport(report)) return { report };
+			parseErrors.push("acceptance-report block does not contain a valid acceptance report");
+		} catch (error) {
+			parseErrors.push(error instanceof Error ? error.message : String(error));
+		}
+	}
+	if (parseErrors.length > 0) return { error: `Failed to parse acceptance-report: ${parseErrors.join("; ")}` };
+	const markerIndex = output.search(/ACCEPTANCE_REPORT\s*:/i);
+	if (markerIndex !== -1) {
+		const jsonStart = output.indexOf("{", markerIndex);
+		if (jsonStart !== -1) {
+			const json = extractBalancedJson(output, jsonStart);
+			if (json) {
+				try {
+					const parsed = JSON.parse(json) as unknown;
+					if (isAcceptanceReport(parsed)) return { report: parsed };
+				} catch (error) {
+					return { error: error instanceof Error ? error.message : String(error) };
+				}
+			}
+		}
+	}
+	return { error: "Structured acceptance report not found." };
+}
+
+export function stripAcceptanceReport(output: string): string {
+	return output
+		.replace(/\n?```acceptance-report\s*\n[\s\S]*?```\s*$/i, "")
+		.replace(/\n?ACCEPTANCE_REPORT\s*:\s*\{[\s\S]*\}\s*$/i, "")
+		.trimEnd();
+}
+
+function isStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isCriterionReport(value: unknown): value is NonNullable<AcceptanceReport["criteriaSatisfied"]>[number] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const criterion = value as { id?: unknown; status?: unknown; evidence?: unknown };
+	if (criterion.id !== undefined && typeof criterion.id !== "string") return false;
+	if (criterion.status !== "satisfied" && criterion.status !== "not-satisfied" && criterion.status !== "not-applicable") return false;
+	return typeof criterion.evidence === "string" && criterion.evidence.trim().length > 0;
+}
+
+function isCommandReport(value: unknown): value is NonNullable<AcceptanceReport["commandsRun"]>[number] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const command = value as { command?: unknown; result?: unknown; summary?: unknown };
+	return typeof command.command === "string"
+		&& (command.result === "passed" || command.result === "failed" || command.result === "not-run")
+		&& typeof command.summary === "string";
+}
+
+function isAcceptanceReport(value: unknown): value is AcceptanceReport {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const report = value as {
+		criteriaSatisfied?: unknown;
+		changedFiles?: unknown;
+		testsAddedOrUpdated?: unknown;
+		commandsRun?: unknown;
+		validationOutput?: unknown;
+		residualRisks?: unknown;
+		noStagedFiles?: unknown;
+		diffSummary?: unknown;
+		reviewFindings?: unknown;
+		manualNotes?: unknown;
+		notes?: unknown;
+	};
+	if (report.criteriaSatisfied !== undefined && (!Array.isArray(report.criteriaSatisfied) || !report.criteriaSatisfied.every(isCriterionReport))) return false;
+	if (report.changedFiles !== undefined && !isStringArray(report.changedFiles)) return false;
+	if (report.testsAddedOrUpdated !== undefined && !isStringArray(report.testsAddedOrUpdated)) return false;
+	if (report.commandsRun !== undefined && (!Array.isArray(report.commandsRun) || !report.commandsRun.every(isCommandReport))) return false;
+	if (report.validationOutput !== undefined && !isStringArray(report.validationOutput)) return false;
+	if (report.residualRisks !== undefined && !isStringArray(report.residualRisks)) return false;
+	if (report.noStagedFiles !== undefined && typeof report.noStagedFiles !== "boolean") return false;
+	if (report.diffSummary !== undefined && typeof report.diffSummary !== "string") return false;
+	if (report.reviewFindings !== undefined && !isStringArray(report.reviewFindings)) return false;
+	if (report.manualNotes !== undefined && typeof report.manualNotes !== "string") return false;
+	if (report.notes !== undefined && typeof report.notes !== "string") return false;
+	return report.criteriaSatisfied !== undefined
+		|| report.changedFiles !== undefined
+		|| report.testsAddedOrUpdated !== undefined
+		|| report.commandsRun !== undefined
+		|| report.residualRisks !== undefined
+		|| report.manualNotes !== undefined
+		|| report.reviewFindings !== undefined;
+}
+

package/src/runs/shared/acceptance.ts

@@ -0,0 +1,22 @@
+export {
+	acceptanceSelfReviewConfig,
+	formatAcceptancePrompt,
+	resolveEffectiveAcceptance,
+	shouldRunAcceptanceFinalization,
+	validateAcceptanceInput,
+} from "./acceptance-contract.ts";
+export {
+	parseAcceptanceReport,
+	stripAcceptanceReport,
+} from "./acceptance-reports.ts";
+export {
+	acceptanceFailureMessage,
+	evaluateAcceptance,
+} from "./acceptance-evaluation.ts";
+export {
+	attachFinalizationToLedger,
+	buildFinalizationProcessFailureLedger,
+	createFinalizationProcessFailureTurn,
+	createFinalizationTurn,
+	formatAcceptanceFinalizationPrompt,
+} from "./acceptance-finalization.ts";

package/src/runs/shared/chain-outputs.ts

@@ -0,0 +1,101 @@
+import { isDynamicParallelStep, isParallelStep, type ChainStep, type SequentialStep } from "../../shared/settings.ts";
+import type { ChainOutputMap, ChainOutputMapEntry, SingleResult } from "../../shared/types.ts";
+import { getSingleResultOutput } from "../../shared/utils.ts";
+import { DynamicFanoutError, hasDynamicFanoutFields, type DynamicFanoutConfig, validateDynamicStepShape } from "./dynamic-fanout.ts";
+
+const OUTPUT_REF_PATTERN = /\{outputs\.([^}]*)\}/g;
+const SAFE_OUTPUT_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export class ChainOutputValidationError extends Error {}
+
+function outputNamesForStep(step: ChainStep): string[] {
+	if (isParallelStep(step)) return step.parallel.map((task) => task.as).filter((name): name is string => Boolean(name));
+	if (isDynamicParallelStep(step)) return [step.collect.as];
+	const name = (step as SequentialStep).as;
+	return name ? [name] : [];
+}
+
+function taskTemplatesForStep(step: ChainStep): string[] {
+	if (isParallelStep(step)) return step.parallel.map((task) => task.task ?? "{previous}");
+	if (isDynamicParallelStep(step)) return [step.parallel.task ?? "{previous}", step.parallel.label ?? ""].filter(Boolean);
+	return [(step as SequentialStep).task ?? "{previous}"];
+}
+
+export function validateChainOutputBindings(steps: ChainStep[], dynamicFanoutConfig: DynamicFanoutConfig = {}): void {
+	const available = new Set<string>();
+	const seen = new Set<string>();
+	for (let stepIndex = 0; stepIndex < steps.length; stepIndex++) {
+		const step = steps[stepIndex]!;
+		if (hasDynamicFanoutFields(step)) {
+			if (!isDynamicParallelStep(step)) {
+				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} requires expand, a single parallel template object, and collect; dynamic expand/collect cannot be mixed with static parallel arrays.`);
+			}
+			try {
+				validateDynamicStepShape(step, stepIndex, dynamicFanoutConfig);
+			} catch (error) {
+				if (error instanceof DynamicFanoutError) throw new ChainOutputValidationError(error.message);
+				throw error;
+			}
+			if (!available.has(step.expand.from.output)) {
+				throw new ChainOutputValidationError(`Dynamic chain step ${stepIndex + 1} references unknown output '${step.expand.from.output}'. Named outputs are only available after producing step/group completes.`);
+			}
+		}
+		for (const name of outputNamesForStep(step)) {
+			if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
+				throw new ChainOutputValidationError(`Invalid chain output name '${name}' at step ${stepIndex + 1}. Use /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+			}
+			if (seen.has(name)) {
+				throw new ChainOutputValidationError(`Duplicate chain output name '${name}'. Each as name must be unique.`);
+			}
+			seen.add(name);
+		}
+		for (const template of taskTemplatesForStep(step)) {
+			for (const match of template.matchAll(OUTPUT_REF_PATTERN)) {
+				const rawReference = match[0];
+				const name = match[1]!;
+				if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
+					throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}' at step ${stepIndex + 1}. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
+				}
+				if (!available.has(name)) {
+					throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}' at step ${stepIndex + 1}. Named outputs are only available after producing step/group completes.`);
+				}
+			}
+		}
+		for (const name of outputNamesForStep(step)) {
+			available.add(name);
+		}
+	}
+}
+
+export function resolveOutputReferences(template: string, outputs: ChainOutputMap): string {
+	return template.replace(OUTPUT_REF_PATTERN, (rawReference, name: string) => {
+		if (!SAFE_OUTPUT_NAME_PATTERN.test(name)) {
+			throw new ChainOutputValidationError(`Invalid chain output reference '${rawReference}'. Use {outputs.name} with /^[A-Za-z_][A-Za-z0-9_]*$/ names.`);
+		}
+		const entry = outputs[name];
+		if (!entry) throw new ChainOutputValidationError(`Unknown chain output reference '${rawReference}'.`);
+		return entry.text;
+	});
+}
+
+function compactStructuredText(value: unknown): string {
+	return JSON.stringify(value);
+}
+
+export function outputEntryFromResult(result: SingleResult, stepIndex: number): ChainOutputMapEntry {
+	return {
+		text: result.structuredOutput !== undefined ? compactStructuredText(result.structuredOutput) : getSingleResultOutput(result),
+		...(result.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+		agent: result.agent,
+		stepIndex,
+	};
+}
+
+export function outputEntryFromAsyncResult(result: { agent: string; output: string; structuredOutput?: unknown }, stepIndex: number): ChainOutputMapEntry {
+	return {
+		text: result.structuredOutput !== undefined ? compactStructuredText(result.structuredOutput) : result.output,
+		...(result.structuredOutput !== undefined ? { structured: result.structuredOutput } : {}),
+		agent: result.agent,
+		stepIndex,
+	};
+}

package/src/runs/shared/completion-guard.ts

@@ -66,6 +66,17 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
 	"contact_supervisor",
 ]);
 
+export type CompletionPolicy = "none" | "mutation-guard" | "acceptance-contract";
+
+interface CompletionPolicyInput {
+	agent: string;
+	task: string;
+	completionGuardEnabled: boolean;
+	usesAcceptanceContract: boolean;
+	tools?: string[];
+	mcpDirectTools?: string[];
+}
+
 interface CompletionMutationGuardInput {
 	agent: string;
 	task: string;
@@ -134,10 +145,22 @@ export function hasMutationToolCall(messages: Message[]): boolean {
 	return false;
 }
 
+export function resolveCompletionPolicy(input: CompletionPolicyInput): CompletionPolicy {
+	if (input.usesAcceptanceContract) return "acceptance-contract";
+	if (!input.completionGuardEnabled) return "none";
+	if (declaresOnlyReadOnlyTools(input.tools, input.mcpDirectTools)) return "none";
+	return expectsImplementationMutation(input.agent, input.task) ? "mutation-guard" : "none";
+}
+
 export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
-	const expectedMutation = declaresOnlyReadOnlyTools(input.tools, input.mcpDirectTools)
-		? false
-		: expectsImplementationMutation(input.agent, input.task);
+	const expectedMutation = resolveCompletionPolicy({
+		agent: input.agent,
+		task: input.task,
+		completionGuardEnabled: true,
+		usesAcceptanceContract: false,
+		tools: input.tools,
+		mcpDirectTools: input.mcpDirectTools,
+	}) === "mutation-guard";
 	const attemptedMutation = hasMutationToolCall(input.messages);
 	return {
 		expectedMutation,