pi-subagents 0.24.4 → 0.27.0

package/src/runs/foreground/execution.ts

@@ -3,7 +3,9 @@
  */
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync, unlinkSync } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig } from "../../agents/agents.ts";
 import {
@@ -13,10 +15,13 @@ import {
 	writeMetadata,
 } from "../../shared/artifacts.ts";
 import {
+	type AcceptanceFinalizationTurn,
+	type AcceptanceLedger,
 	type AgentProgress,
 	type ArtifactPaths,
 	type ControlEvent,
 	type ModelAttempt,
+	type ResolvedAcceptanceConfig,
 	type RunSyncOptions,
 	type SingleResult,
 	type Usage,
@@ -41,11 +46,12 @@ import {
 	extractTextFromContent,
 } from "../../shared/utils.ts";
 import { buildSkillInjection, resolveSkillsWithFallback } from "../../agents/skills.ts";
-import { evaluateCompletionMutationGuard } from "../shared/completion-guard.ts";
+import { evaluateCompletionMutationGuard, resolveCompletionPolicy, type CompletionPolicy } from "../shared/completion-guard.ts";
 import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
 import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "../shared/pi-args.ts";
+import { readStructuredOutput } from "../shared/structured-output.ts";
 import { captureSingleOutputSnapshot, formatSavedOutputReference, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
 	buildModelCandidates,
@@ -63,8 +69,23 @@ import {
 	shouldEscalateMutatingFailures,
 	summarizeRecentMutatingFailures,
 } from "../shared/long-running-guard.ts";
+import {
+	acceptanceFailureMessage,
+	acceptanceSelfReviewConfig,
+	attachFinalizationToLedger,
+	buildFinalizationProcessFailureLedger,
+	createFinalizationProcessFailureTurn,
+	createFinalizationTurn,
+	evaluateAcceptance,
+	formatAcceptanceFinalizationPrompt,
+	formatAcceptancePrompt,
+	resolveEffectiveAcceptance,
+	shouldRunAcceptanceFinalization,
+	stripAcceptanceReport,
+} from "../shared/acceptance.ts";
 
 const artifactOutputByResult = new WeakMap<SingleResult, string>();
+const acceptanceOutputByResult = new WeakMap<SingleResult, string>();
 
 function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
@@ -87,6 +108,17 @@ function appendRecentOutput(progress: AgentProgress, lines: string[]): void {
 	}
 }
 
+function stripAcceptanceReportsFromMessages(messages: Message[] | undefined): void {
+	for (const message of messages ?? []) {
+		if (message.role !== "assistant" || !Array.isArray(message.content)) continue;
+		for (const part of message.content) {
+			if (part.type === "text" && "text" in part && typeof part.text === "string") {
+				part.text = stripAcceptanceReport(part.text);
+			}
+		}
+	}
+}
+
 function snapshotProgress(progress: AgentProgress): AgentProgress {
 	return {
 		...progress,
@@ -133,6 +165,8 @@ async function runSingleAttempt(
 		artifactPaths?: ArtifactPaths;
 		attemptNotes: string[];
 		outputSnapshot?: SingleOutputSnapshot;
+		originalTask?: string;
+		completionPolicy: CompletionPolicy;
 	},
 ): Promise<SingleResult> {
 	const modelArg = applyThinkingSuffix(model, agent.thinking);
@@ -158,11 +192,16 @@ async function runSingleAttempt(
 		runId: options.runId,
 		childAgentName: agent.name,
 		childIndex: options.index ?? 0,
+		parentEventSink: options.nestedRoute?.eventSink,
+		parentControlInbox: options.nestedRoute?.controlInbox,
+		parentRootRunId: options.nestedRoute?.rootRunId,
+		parentCapabilityToken: options.nestedRoute?.capabilityToken,
+		structuredOutput: options.structuredOutput,
 	});
 
 	const result: SingleResult = {
 		agent: agent.name,
-		task,
+		task: shared.originalTask ?? task,
 		exitCode: 0,
 		messages: [],
 		usage: emptyUsage(),
@@ -172,6 +211,13 @@ async function runSingleAttempt(
 		skillsWarning: shared.skillsWarning,
 	};
 	const startTime = Date.now();
+	if (options.structuredOutput) {
+		try {
+			if (existsSync(options.structuredOutput.outputPath)) unlinkSync(options.structuredOutput.outputPath);
+		} catch {
+			// Missing/stale structured-output files are handled after the child exits.
+		}
+	}
 	const controlConfig = options.controlConfig ?? DEFAULT_CONTROL_CONFIG;
 	let interruptedByControl = false;
 	const allControlEvents: ControlEvent[] = [];
@@ -651,6 +697,21 @@ async function runSingleAttempt(
 				: `${errInfo.errorType} failed with exit code ${errInfo.exitCode}`;
 		}
 	}
+	if (options.structuredOutput && result.exitCode === 0 && !result.error) {
+		const structured = readStructuredOutput({
+			schema: options.structuredOutput.schema,
+			schemaPath: options.structuredOutput.schemaPath,
+			outputPath: options.structuredOutput.outputPath,
+		});
+		result.structuredOutputSchemaPath = options.structuredOutput.schemaPath;
+		result.structuredOutputPath = options.structuredOutput.outputPath;
+		if (structured.error) {
+			result.exitCode = 1;
+			result.error = structured.error;
+		} else {
+			result.structuredOutput = structured.value;
+		}
+	}
 
 	progress.status = result.exitCode === 0 ? "completed" : "failed";
 	progress.durationMs = Date.now() - startTime;
@@ -667,17 +728,19 @@ async function runSingleAttempt(
 		durationMs: progress.durationMs,
 	};
 
-	let fullOutput = getFinalOutput(result.messages);
-	const completionGuard = result.exitCode === 0 && !result.error && agent.completionGuard !== false
+	const acceptanceOutput = getFinalOutput(result.messages);
+	let fullOutput = stripAcceptanceReport(acceptanceOutput);
+	const completionGuard = result.exitCode === 0 && !result.error && shared.completionPolicy === "mutation-guard"
 		? evaluateCompletionMutationGuard({
 			agent: agent.name,
-			task,
+			task: shared.originalTask ?? task,
 			messages: result.messages,
 			tools: agent.tools,
 			mcpDirectTools: agent.mcpDirectTools,
 		})
 		: undefined;
-	if (completionGuard?.triggered && !observedMutationAttempt) {
+	const completionGuardTriggered = completionGuard?.triggered === true && !observedMutationAttempt;
+	if (completionGuardTriggered) {
 		result.exitCode = 1;
 		result.error = "Subagent completed without making edits for an implementation task.\nIt appears to have returned planning or scratchpad output instead of applying changes.";
 		progress.status = "failed";
@@ -695,7 +758,7 @@ async function runSingleAttempt(
 	}
 	if (options.outputPath && result.exitCode === 0) {
 		const resolvedOutput = resolveSingleOutput(options.outputPath, fullOutput, shared.outputSnapshot);
-		fullOutput = resolvedOutput.fullOutput;
+		fullOutput = stripAcceptanceReport(resolvedOutput.fullOutput);
 		result.savedOutputPath = resolvedOutput.savedPath;
 		result.outputSaveError = resolvedOutput.saveError;
 		if (resolvedOutput.savedPath) {
@@ -703,6 +766,7 @@ async function runSingleAttempt(
 		}
 	}
 	artifactOutputByResult.set(result, fullOutput);
+	acceptanceOutputByResult.set(result, acceptanceOutput);
 	result.outputMode = options.outputMode ?? "inline";
 	result.finalOutput = options.outputMode === "file-only" && result.savedOutputPath && result.outputReference
 		? result.outputReference.message
@@ -725,6 +789,99 @@ async function runSingleAttempt(
 	return result;
 }
 
+async function runAcceptanceFinalizationLoop(input: {
+	runtimeCwd: string;
+	agent: AgentConfig;
+	result: SingleResult;
+	initialLedger: AcceptanceLedger;
+	initialOutput: string;
+	acceptance: ResolvedAcceptanceConfig;
+	options: RunSyncOptions;
+	systemPrompt: string;
+	resolvedSkillNames?: string[];
+	skillsWarning?: string;
+}): Promise<AcceptanceLedger> {
+	const sessionFile = input.result.sessionFile ?? input.options.sessionFile;
+	const maxTurns = input.acceptance.finalization.maxTurns;
+	const turns: AcceptanceFinalizationTurn[] = [];
+	if (!sessionFile) {
+		const message = "Acceptance finalization requires a session file for same-session continuation.";
+		turns.push(createFinalizationProcessFailureTurn({ turn: 1, prompt: "", message }));
+		return buildFinalizationProcessFailureLedger({ initialLedger: input.initialLedger, turns, maxTurns, message });
+	}
+
+	const selfReviewAcceptance = acceptanceSelfReviewConfig(input.acceptance);
+	let previousFailure = acceptanceFailureMessage(input.initialLedger);
+	let authoritativeLedger = input.initialLedger;
+	for (let turn = 1; turn <= maxTurns; turn++) {
+		const prompt = formatAcceptanceFinalizationPrompt({
+			acceptance: input.acceptance,
+			initialOutput: input.initialOutput,
+			initialLedger: input.initialLedger,
+			turn,
+			maxTurns,
+			...(previousFailure ? { previousFailure } : {}),
+		});
+		const finalizationOptions: RunSyncOptions = { ...input.options, sessionFile, outputMode: "inline" };
+		delete finalizationOptions.sessionDir;
+		delete finalizationOptions.outputPath;
+		delete finalizationOptions.structuredOutput;
+		delete finalizationOptions.onUpdate;
+		finalizationOptions.allowIntercomDetach = false;
+		const finalizationResult = await runSingleAttempt(
+			input.runtimeCwd,
+			input.agent,
+			prompt,
+			input.result.model,
+			finalizationOptions,
+			{
+				sessionEnabled: true,
+				systemPrompt: input.systemPrompt,
+				resolvedSkillNames: input.resolvedSkillNames,
+				skillsWarning: input.skillsWarning,
+				attemptNotes: [],
+				originalTask: prompt,
+				completionPolicy: "acceptance-contract",
+			},
+		);
+		sumUsage(input.result.usage, finalizationResult.usage);
+		input.result.progressSummary = {
+			toolCount: (input.result.progressSummary?.toolCount ?? 0) + (finalizationResult.progressSummary?.toolCount ?? 0),
+			tokens: input.result.usage.input + input.result.usage.output,
+			durationMs: (input.result.progressSummary?.durationMs ?? 0) + (finalizationResult.progressSummary?.durationMs ?? 0),
+		};
+		if (finalizationResult.controlEvents?.length) {
+			input.result.controlEvents = [...(input.result.controlEvents ?? []), ...finalizationResult.controlEvents];
+		}
+		const rawOutput = acceptanceOutputByResult.get(finalizationResult) ?? getFinalOutput(finalizationResult.messages) ?? finalizationResult.finalOutput ?? "";
+		if (finalizationResult.exitCode !== 0 || finalizationResult.error || finalizationResult.detached || finalizationResult.interrupted) {
+			const message = finalizationResult.error ?? "Acceptance finalization turn did not complete successfully.";
+			turns.push(createFinalizationProcessFailureTurn({ turn, prompt, rawOutput, message }));
+			return buildFinalizationProcessFailureLedger({ initialLedger: input.initialLedger, turns, maxTurns, message });
+		}
+		const selfReviewLedger = await evaluateAcceptance({
+			acceptance: selfReviewAcceptance,
+			output: rawOutput,
+			cwd: input.options.cwd ?? input.runtimeCwd,
+		});
+		authoritativeLedger = selfReviewLedger;
+		turns.push(createFinalizationTurn({ turn, prompt, rawOutput, ledger: selfReviewLedger }));
+		const failure = acceptanceFailureMessage(selfReviewLedger);
+		if (!failure) {
+			authoritativeLedger = input.acceptance === selfReviewAcceptance
+				? selfReviewLedger
+				: await evaluateAcceptance({
+					acceptance: input.acceptance,
+					output: rawOutput,
+					cwd: input.options.cwd ?? input.runtimeCwd,
+				});
+			return attachFinalizationToLedger({ initialLedger: input.initialLedger, authoritativeLedger, turns, status: "completed", maxTurns });
+		}
+		previousFailure = failure;
+	}
+	return attachFinalizationToLedger({ initialLedger: input.initialLedger, authoritativeLedger, turns, status: "failed", maxTurns });
+}
+
 /**
  * Run a subagent synchronously (blocking until complete)
  */
@@ -760,6 +917,21 @@ export async function runSync(
 	}
 
 	const shareEnabled = options.share === true;
+	const effectiveAcceptance = resolveEffectiveAcceptance({
+		explicit: options.acceptance,
+		agentName,
+		task,
+		mode: options.acceptanceContext?.mode ?? "single",
+		async: options.acceptanceContext?.async,
+		dynamic: options.acceptanceContext?.dynamic,
+		dynamicGroup: options.acceptanceContext?.dynamicGroup,
+	});
+	if (shouldRunAcceptanceFinalization(effectiveAcceptance) && !options.sessionFile) {
+		const sessionDir = options.sessionDir ?? mkdtempSync(path.join(os.tmpdir(), "pi-subagent-finalization-"));
+		options.sessionFile = path.join(sessionDir, "session.jsonl");
+	}
+	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance);
+	const taskWithAcceptance = acceptancePrompt ? `${task}\n${acceptancePrompt}` : task;
 	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
 	const skillNames = options.skills ?? agent.skills ?? [];
 	const skillCwd = options.cwd ?? runtimeCwd;
@@ -799,7 +971,7 @@ export async function runSync(
 		artifactPathsResult = getArtifactPaths(options.artifactsDir, options.runId, agentName, options.index);
 		ensureArtifactsDir(options.artifactsDir);
 		if (options.artifactConfig?.includeInput !== false) {
-			writeArtifact(artifactPathsResult.inputPath, `# Task for ${agentName}\n\n${task}`);
+				writeArtifact(artifactPathsResult.inputPath, `# Task for ${agentName}\n\n${taskWithAcceptance}`);
 		}
 		if (options.artifactConfig?.includeJsonl !== false) {
 			jsonlPath = artifactPathsResult.jsonlPath;
@@ -812,7 +984,7 @@ export async function runSync(
 		const candidate = modelsToTry[i];
 		if (candidate) attemptedModels.push(candidate);
 		const outputSnapshot = captureSingleOutputSnapshot(options.outputPath);
-		const result = await runSingleAttempt(runtimeCwd, agent, task, candidate, options, {
+		const result = await runSingleAttempt(runtimeCwd, agent, taskWithAcceptance, candidate, options, {
 			sessionEnabled,
 			systemPrompt,
 			resolvedSkillNames: resolvedSkills.length > 0 ? resolvedSkills.map((skill) => skill.name) : undefined,
@@ -821,6 +993,15 @@ export async function runSync(
 			artifactPaths: artifactPathsResult,
 			attemptNotes,
 			outputSnapshot,
+			originalTask: task,
+			completionPolicy: resolveCompletionPolicy({
+				agent: agent.name,
+				task,
+				completionGuardEnabled: agent.completionGuard !== false,
+				usesAcceptanceContract: effectiveAcceptance.explicit,
+				tools: agent.tools,
+				mcpDirectTools: agent.mcpDirectTools,
+			}),
 		});
 		lastResult = result;
 		sumUsage(aggregateUsage, result.usage);
@@ -910,5 +1091,40 @@ export async function runSync(
 		if (sessionFile) result.sessionFile = sessionFile;
 	}
 
+	const initialAcceptanceOutput = acceptanceOutputByResult.get(result) ?? result.finalOutput ?? "";
+	const acceptanceForInitialReport = shouldRunAcceptanceFinalization(effectiveAcceptance)
+		? acceptanceSelfReviewConfig(effectiveAcceptance)
+		: effectiveAcceptance;
+	const initialAcceptance = await evaluateAcceptance({
+		acceptance: acceptanceForInitialReport,
+		output: initialAcceptanceOutput,
+		cwd: options.cwd ?? runtimeCwd,
+	});
+	result.acceptance = initialAcceptance;
+	if (shouldRunAcceptanceFinalization(effectiveAcceptance) && result.exitCode === 0 && !result.detached && !result.interrupted) {
+		result.acceptance = await runAcceptanceFinalizationLoop({
+			runtimeCwd,
+			agent,
+			result,
+			initialLedger: initialAcceptance,
+			initialOutput: initialAcceptanceOutput,
+			acceptance: effectiveAcceptance,
+			options,
+			systemPrompt,
+			resolvedSkillNames: resolvedSkills.length > 0 ? resolvedSkills.map((skill) => skill.name) : undefined,
+			...(missingSkills.length > 0 ? { skillsWarning: `Skills not found: ${missingSkills.join(", ")}` } : {}),
+		});
+	}
+	const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
+	stripAcceptanceReportsFromMessages(result.messages);
+	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted) {
+		result.exitCode = 1;
+		result.error = result.error ? `${result.error}\n${acceptanceFailure}` : acceptanceFailure;
+		if (result.progress) {
+			result.progress.status = "failed";
+			result.progress.error = result.error;
+		}
+	}
+
 	return result;
 }