pi-subagents 0.35.0 → 0.36.0

package/src/runs/foreground/execution.ts

@@ -9,6 +9,7 @@ import type { Message } from "@earendil-works/pi-ai";
 import type { AgentConfig } from "../../agents/agents.ts";
 import {
 	ensureArtifactsDir,
+	formatOutputArtifactContent,
 	getArtifactPaths,
 	writeArtifact,
 	writeMetadata,
@@ -51,7 +52,8 @@ 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 { resolveEffectiveThinking } from "../../shared/model-info.ts";
+import { MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput } from "../shared/structured-output.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { captureSingleOutputSnapshot, extractChildWrittenOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
 import {
@@ -71,6 +73,7 @@ import {
 	summarizeRecentMutatingFailures,
 } from "../shared/long-running-guard.ts";
 import { acceptanceFailureMessage, buildSkippedAcceptanceLedger, evaluateAcceptance, formatAcceptancePrompt, resolveEffectiveAcceptance, stripAcceptanceReport } from "../shared/acceptance.ts";
+import { attachContractProjections, isAgentContractV1 } from "../shared/agent-contract.ts";
 import { appendTurnBudgetSystemPrompt, formatTurnBudgetOutput, initialTurnBudgetState, turnBudgetDecision, turnBudgetDeferredNote, turnBudgetDeferredState, turnBudgetExceededMessage, turnBudgetSoftNote, turnBudgetState } from "../shared/turn-budget.ts";
 import { initialToolBudgetState, toolBudgetState } from "../shared/tool-budget.ts";
 import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
@@ -90,6 +93,12 @@ function emptyUsage(): Usage {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
 }
 
+function withRunContext<T extends SingleResult>(result: T, context: RunSyncOptions["context"]): T {
+	if (!context) return result;
+	result.context = context;
+	return result;
+}
+
 function sumUsage(target: Usage, source: Usage): void {
 	target.input += source.input;
 	target.output += source.output;
@@ -196,6 +205,7 @@ async function runSingleAttempt(
 ): Promise<SingleResult> {
 	const effectiveThinking = options.thinkingOverride ?? agent.thinking;
 	const modelArg = applyThinkingSuffix(model, effectiveThinking, options.thinkingOverride !== undefined);
+	const resolvedThinking = resolveEffectiveThinking(modelArg, effectiveThinking);
 	const watchdogConfig = resolveWatchdogConfig(options.cwd ?? runtimeCwd);
 	const childWatchdog = watchdogConfig.ok
 		? resolveChildWatchdogConfig({
@@ -236,24 +246,27 @@ async function runSingleAttempt(
 		parentSessionId: options.parentSessionId,
 		structuredOutput: options.structuredOutput,
 		toolBudget: options.toolBudget,
+		allowZeroToolBudget: options.allowZeroToolBudget,
 		childWatchdog,
 		waitToolEnabled: options.waitToolEnabled,
 	});
 
-	const result: SingleResult = {
+	const result: SingleResult = withRunContext({
 		agent: agent.name,
 		task: shared.originalTask ?? task,
+		...(options.agentContract ? { agentContract: options.agentContract } : {}),
 		exitCode: 0,
 		messages: [],
 		usage: emptyUsage(),
 		model: modelArg,
+		...(resolvedThinking ? { thinking: resolvedThinking } : {}),
 		artifactPaths: shared.artifactPaths,
 		transcriptPath: shared.transcriptWriter ? shared.artifactPaths?.transcriptPath : undefined,
 		skills: shared.resolvedSkillNames,
 		skillsWarning: shared.skillsWarning,
 		...(options.turnBudget ? { turnBudget: initialTurnBudgetState(options.turnBudget) } : {}),
 		...(options.toolBudget ? { toolBudget: initialToolBudgetState(options.toolBudget) } : {}),
-	};
+	}, options.context);
 	const startTime = Date.now();
 	if (options.structuredOutput) {
 		try {
@@ -307,6 +320,7 @@ async function runSingleAttempt(
 	}
 	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 	let observedMutationAttempt = false;
+	let structuredOutputToolInvoked = false;
 
 	const exitCode = await new Promise<number>((resolve) => {
 		const spawnSpec = getPiSpawnCommand(args);
@@ -592,7 +606,7 @@ async function runSingleAttempt(
 				result.wrapUpRequested = true;
 				appendRecentOutput(progress, [turnBudgetSoftNote(budget, turnCount)]);
 			}
-			const decision = turnBudgetDecision(budget, turnCount, terminalAssistantStop, toolWorkActiveOrStarting);
+			const decision = turnBudgetDecision(budget, turnCount, terminalAssistantStop, toolWorkActiveOrStarting, options.enforceHardTurnLimit);
 			if (decision === "defer") {
 				result.turnBudget = turnBudgetDeferredState(
 					budget,
@@ -646,7 +660,7 @@ async function runSingleAttempt(
 		const fireUpdate = () => {
 			if (!options.onUpdate || processClosed) return;
 			progress.durationMs = Date.now() - startTime;
-			const output = (result.timedOut || result.turnBudgetExceeded) && result.finalOutput ? result.finalOutput : getFinalOutput(result.messages);
+			const output = (result.timedOut || result.turnBudgetExceeded) && result.finalOutput ? result.finalOutput : getFinalOutput(result.messages ?? []);
 			emitUpdateSnapshot(output || "(running...)");
 		};
 
@@ -696,6 +710,7 @@ async function runSingleAttempt(
 				const toolArgs = evt.args && typeof evt.args === "object" && !Array.isArray(evt.args)
 					? evt.args as Record<string, unknown>
 					: {};
+				if (options.structuredOutput && evt.toolName === "structured_output") structuredOutputToolInvoked = true;
 				if (options.allowIntercomDetach && (evt.toolName === "intercom" || evt.toolName === "contact_supervisor")) {
 					intercomStarted = true;
 				}
@@ -729,15 +744,20 @@ async function runSingleAttempt(
 			}
 
 			if (evt.type === "message_end" && evt.message) {
-				result.messages.push(evt.message);
+				result.messages!.push(evt.message);
 				if (evt.message.role === "assistant") {
 					result.usage.turns++;
 					progress.turnCount = result.usage.turns;
 					const stopReason = (evt.message as { stopReason?: string }).stopReason;
-					const hasToolCall = Array.isArray(evt.message.content)
-						&& evt.message.content.some((part) => (part as { type?: string }).type === "toolCall");
+					const toolCalls = Array.isArray(evt.message.content)
+						? evt.message.content.filter((part) => (part as { type?: string }).type === "toolCall")
+						: [];
+					const hasToolCall = toolCalls.length > 0;
 					const terminalAssistantStop = stopReason === "stop" && !hasToolCall;
-					updateTurnBudget(result.usage.turns, terminalAssistantStop, hasToolCall || Boolean(progress.currentTool));
+					const terminalStructuredOutputCall = Boolean(options.structuredOutput)
+						&& toolCalls.length === 1
+						&& (toolCalls[0] as { name?: string }).name === "structured_output";
+					updateTurnBudget(result.usage.turns, terminalAssistantStop || terminalStructuredOutputCall, hasToolCall || Boolean(progress.currentTool));
 					const u = evt.message.usage;
 					if (u) {
 						result.usage.input += u.input || 0;
@@ -763,7 +783,7 @@ async function runSingleAttempt(
 			}
 
 			if (evt.type === "tool_result_end" && evt.message) {
-				result.messages.push(evt.message);
+				result.messages!.push(evt.message);
 				const resultText = extractTextFromContent(evt.message.content);
 				if (options.toolBudget && pendingToolResult && resultText.includes("Tool budget hard limit reached")) {
 					result.toolBudgetBlocked = true;
@@ -1021,7 +1041,7 @@ async function runSingleAttempt(
 		result.exitCode = 1;
 	}
 	if (result.exitCode === 0 && !result.error) {
-		const errInfo = detectSubagentError(result.messages);
+		const errInfo = detectSubagentError(result.messages ?? []);
 		if (errInfo.hasError) {
 			result.exitCode = errInfo.exitCode ?? 1;
 			result.error = errInfo.details
@@ -1030,7 +1050,7 @@ async function runSingleAttempt(
 		}
 	}
 	if (result.exitCode === 0 && !result.error) {
-		const finalText = getFinalOutput(result.messages);
+		const finalText = getFinalOutput(result.messages ?? []);
 		const missingStructuredOutput = options.structuredOutput
 			? !existsSync(options.structuredOutput.outputPath)
 			: false;
@@ -1040,18 +1060,25 @@ async function runSingleAttempt(
 		}
 	}
 	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) {
+		if (!structuredOutputToolInvoked) {
 			result.exitCode = 1;
-			result.error = structured.error;
+			result.error = MISSING_STRUCTURED_OUTPUT_CALL_ERROR;
+			result.structuredOutputFailed = true;
 		} else {
-			result.structuredOutput = structured.value;
+			const structured = await readStructuredOutput({
+				schema: options.structuredOutput.schema,
+				schemaPath: options.structuredOutput.schemaPath,
+				outputPath: options.structuredOutput.outputPath,
+			});
+			if (structured.error) {
+				result.exitCode = 1;
+				result.error = structured.error;
+				result.structuredOutputFailed = true;
+			} else {
+				result.structuredOutput = structured.value;
+			}
 		}
 	}
 
@@ -1070,7 +1097,7 @@ async function runSingleAttempt(
 		durationMs: progress.durationMs,
 	};
 
-	const acceptanceOutput = getFinalOutput(result.messages);
+	const acceptanceOutput = getFinalOutput(result.messages ?? []);
 	let fullOutput = stripAcceptanceReport(acceptanceOutput);
 	if (result.timedOut) {
 		const timeoutMessage = formatTimeoutMessage(options.timeoutMs ?? 0);
@@ -1086,16 +1113,29 @@ async function runSingleAttempt(
 		const note = turnBudgetSoftNote(result.turnBudget, result.turnBudget.wrapUpRequestedAtTurn ?? result.turnBudget.turnCount);
 		fullOutput = fullOutput.trim() ? `${note}\n\n${fullOutput}` : note;
 	}
-	const completionGuard = result.exitCode === 0 && !result.error && agent.completionGuard !== false
+	const completionGuardEnabled = isAgentContractV1(options.agentContract) ? agent.completionGuard === true : agent.completionGuard !== false;
+	const completionGuard = result.exitCode === 0 && !result.error && completionGuardEnabled
 		? evaluateCompletionMutationGuard({
 			agent: agent.name,
 			task: shared.originalTask ?? task,
-			messages: result.messages,
+			messages: result.messages ?? [],
 			tools: agent.tools,
 			mcpDirectTools: agent.mcpDirectTools,
 		})
 		: undefined;
-	if (completionGuard?.triggered && !observedMutationAttempt) {
+	const completionGuardTriggered = completionGuard?.triggered === true && !observedMutationAttempt;
+	if (completionGuard) {
+		result.effects = {
+			...(result.effects ?? {}),
+			fileMutation: {
+				status: completionGuard.expectedMutation ? completionGuardTriggered ? "missing" : "observed" : "not-applicable",
+				expected: completionGuard.expectedMutation,
+				attempted: completionGuard.attemptedMutation || observedMutationAttempt,
+				...(completionGuardTriggered ? { message: "Subagent completed without making edits for an implementation task." } : {}),
+			},
+		};
+	}
+	if (completionGuardTriggered && !isAgentContractV1(options.agentContract)) {
 		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";
@@ -1156,18 +1196,18 @@ export async function runSync(
 ): Promise<SingleResult> {
 	const agent = agents.find((a) => a.name === agentName);
 	if (!agent) {
-		return {
+		return withRunContext({
 			agent: agentName,
 			task,
 			exitCode: 1,
 			messages: [],
 			usage: emptyUsage(),
 			error: `Unknown agent: ${agentName}`,
-		};
+		}, options.context);
 	}
 	const outputModeValidationError = validateFileOnlyOutputMode(options.outputMode, options.outputPath, `Single run (${agentName})`);
 	if (outputModeValidationError) {
-		return {
+		return withRunContext({
 			agent: agentName,
 			task,
 			exitCode: 1,
@@ -1175,7 +1215,7 @@ export async function runSync(
 			usage: emptyUsage(),
 			outputMode: options.outputMode,
 			error: outputModeValidationError,
-		};
+		}, options.context);
 	}
 
 	const shareEnabled = options.share === true;
@@ -1188,8 +1228,9 @@ export async function runSync(
 		async: options.acceptanceContext?.async,
 		dynamic: options.acceptanceContext?.dynamic,
 		dynamicGroup: options.acceptanceContext?.dynamicGroup,
+		agentContract: options.agentContract,
 	});
-	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance);
+	const acceptancePrompt = formatAcceptancePrompt(effectiveAcceptance, { reportOptional: isAgentContractV1(options.agentContract) });
 	const taskWithAcceptance = acceptancePrompt ? `${task}\n${acceptancePrompt}` : task;
 	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
 	const skillNames = options.skills ?? agent.skills ?? [];
@@ -1202,14 +1243,14 @@ export async function runSync(
 		agent.filePath ? path.dirname(agent.filePath) : skillCwd,
 	);
 	if (skillNames.some((skill) => skill.trim() === "pi-subagents") && missingSkills.includes("pi-subagents")) {
-		return {
+		return withRunContext({
 			agent: agentName,
 			task,
 			exitCode: 1,
 			messages: [],
 			usage: emptyUsage(),
 			error: "Skills not found: pi-subagents",
-		};
+		}, options.context);
 	}
 	let systemPrompt = agent.systemPrompt?.trim() || "";
 	if (resolvedSkills.length > 0) {
@@ -1275,7 +1316,11 @@ export async function runSync(
 			durationMs: target.progressSummary?.durationMs,
 			toolCount: target.progressSummary?.toolCount,
 			error: target.error,
+			agentContract: target.agentContract,
+			execution: target.execution,
 			acceptance: target.acceptance,
+			review: target.review,
+			effects: target.effects,
 			...(transcriptWriter ? { transcriptPath: artifactPathsResult.transcriptPath } : {}),
 			transcriptError: target.transcriptError,
 			skills: target.skills,
@@ -1299,10 +1344,11 @@ export async function runSync(
 							? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
 							: undefined,
 						cwd: options.cwd ?? runtimeCwd,
+						reportOptional: isAgentContractV1(options.agentContract),
 					});
 					const acceptanceFailure = acceptanceFailureMessage(recoveredResult.acceptance);
 					stripAcceptanceReportsFromMessages(recoveredResult.messages);
-					if (acceptanceFailure && recoveredResult.acceptance.explicit && recoveredResult.exitCode === 0) {
+					if (acceptanceFailure && recoveredResult.acceptance.explicit && recoveredResult.exitCode === 0 && !isAgentContractV1(options.agentContract)) {
 						recoveredResult.exitCode = 1;
 						recoveredResult.error = recoveredResult.error ? `${recoveredResult.error}\n${acceptanceFailure}` : acceptanceFailure;
 						if (recoveredResult.progress) {
@@ -1310,6 +1356,7 @@ export async function runSync(
 							recoveredResult.progress.error = recoveredResult.error;
 						}
 					}
+					if (isAgentContractV1(options.agentContract)) attachContractProjections(recoveredResult);
 					persistResultMetadata(recoveredResult);
 					options.onDetachedExit?.(recoveredResult);
 				})().catch((error) => {
@@ -1366,14 +1413,14 @@ export async function runSync(
 		attemptNotes.push(formatModelAttemptNote(attempt, modelsToTry[i + 1]));
 	}
 
-	const result = lastResult ?? {
+	const result = withRunContext(lastResult ?? {
 		agent: agentName,
 		task,
 		exitCode: 1,
 		messages: [],
 		usage: emptyUsage(),
 		error: "Subagent did not produce a result.",
-	} satisfies SingleResult;
+	} satisfies SingleResult, options.context);
 
 	result.usage = aggregateUsage;
 	result.attemptedModels = attemptedModels.length > 0 ? attemptedModels : undefined;
@@ -1396,7 +1443,12 @@ export async function runSync(
 	if (artifactPathsResult && options.artifactConfig?.enabled !== false) {
 		result.artifactPaths = artifactPathsResult;
 		if (options.artifactConfig?.includeOutput !== false) {
-			writeArtifact(artifactPathsResult.outputPath, artifactOutputByResult.get(result) ?? result.finalOutput ?? "");
+			writeArtifact(artifactPathsResult.outputPath, formatOutputArtifactContent({
+				output: artifactOutputByResult.get(result) ?? result.finalOutput ?? "",
+				error: result.error,
+				transcriptPath: result.transcriptPath,
+				metadataPath: options.artifactConfig?.includeMetadata === false ? undefined : artifactPathsResult.metadataPath,
+			}));
 		}
 		if (options.maxOutput) {
 			const config = { ...DEFAULT_MAX_OUTPUT, ...options.maxOutput };
@@ -1435,11 +1487,12 @@ export async function runSync(
 				? { content: childWrittenOutput, path: options.outputPath, authoritative: options.outputMode === "file-only" }
 				: undefined,
 			cwd: options.cwd ?? runtimeCwd,
+			reportOptional: isAgentContractV1(options.agentContract),
 		});
 	}
 	const acceptanceFailure = acceptanceFailureMessage(result.acceptance);
 	stripAcceptanceReportsFromMessages(result.messages);
-	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted && !result.timedOut) {
+	if (acceptanceFailure && result.acceptance.explicit && result.exitCode === 0 && !result.detached && !result.interrupted && !result.timedOut && !isAgentContractV1(options.agentContract)) {
 		result.exitCode = 1;
 		result.error = result.error ? `${result.error}\n${acceptanceFailure}` : acceptanceFailure;
 		if (result.progress) {
@@ -1447,6 +1500,7 @@ export async function runSync(
 			result.progress.error = result.error;
 		}
 	}
+	if (isAgentContractV1(options.agentContract)) attachContractProjections(result);
 	persistResultMetadata(result);
 
 	return result;

package/src/runs/foreground/foreground-control.ts

@@ -0,0 +1,90 @@
+import type { AgentProgress, ForegroundChildControl, ForegroundRunControl } from "../../shared/types.ts";
+
+interface BeginForegroundChildInput {
+	index: number;
+	agent: string;
+	description?: string;
+	interrupt: () => boolean;
+}
+
+function copyProgress(target: ForegroundChildControl, progress: AgentProgress | undefined): void {
+	if (!progress) return;
+	target.currentActivityState = progress.activityState;
+	target.lastActivityAt = progress.lastActivityAt;
+	target.currentTool = progress.currentTool;
+	target.currentToolStartedAt = progress.currentToolStartedAt;
+	target.currentPath = progress.currentPath;
+	target.turnCount = progress.turnCount;
+	target.tokens = progress.tokens;
+	target.toolCount = progress.toolCount;
+}
+
+function syncCurrentChild(control: ForegroundRunControl, child: ForegroundChildControl): void {
+	control.currentAgent = child.agent;
+	control.currentIndex = child.index;
+	control.description = child.description;
+	control.currentActivityState = child.currentActivityState;
+	control.lastActivityAt = child.lastActivityAt;
+	control.currentTool = child.currentTool;
+	control.currentToolStartedAt = child.currentToolStartedAt;
+	control.currentPath = child.currentPath;
+	control.turnCount = child.turnCount;
+	control.tokens = child.tokens;
+	control.toolCount = child.toolCount;
+	control.interrupt = child.interrupt;
+	control.updatedAt = child.updatedAt;
+}
+
+function clearCurrentChild(control: ForegroundRunControl): void {
+	control.currentAgent = undefined;
+	control.currentIndex = undefined;
+	control.currentActivityState = undefined;
+	control.lastActivityAt = undefined;
+	control.currentTool = undefined;
+	control.currentToolStartedAt = undefined;
+	control.currentPath = undefined;
+	control.turnCount = undefined;
+	control.tokens = undefined;
+	control.toolCount = undefined;
+	control.interrupt = undefined;
+}
+
+export function beginForegroundChild(control: ForegroundRunControl, input: BeginForegroundChildInput): void {
+	const now = Date.now();
+	const child: ForegroundChildControl = {
+		index: input.index,
+		agent: input.agent,
+		...(input.description ? { description: input.description } : {}),
+		startedAt: now,
+		updatedAt: now,
+	};
+	child.interrupt = () => {
+		if (!input.interrupt()) return false;
+		child.currentActivityState = undefined;
+		child.updatedAt = Date.now();
+		syncCurrentChild(control, child);
+		return true;
+	};
+	control.activeChildren ??= new Map();
+	control.activeChildren.set(input.index, child);
+	syncCurrentChild(control, child);
+}
+
+export function updateForegroundChild(control: ForegroundRunControl, index: number, progress: AgentProgress | undefined): void {
+	const child = control.activeChildren?.get(index);
+	if (!child) return;
+	copyProgress(child, progress);
+	child.updatedAt = Date.now();
+	syncCurrentChild(control, child);
+}
+
+export function finishForegroundChild(control: ForegroundRunControl, index: number): void {
+	control.activeChildren?.delete(index);
+	if (control.currentIndex === index) {
+		const next = [...(control.activeChildren?.values() ?? [])]
+			.sort((left, right) => right.updatedAt - left.updatedAt || left.index - right.index)[0];
+		if (next) syncCurrentChild(control, next);
+		else clearCurrentChild(control);
+	}
+	control.updatedAt = Date.now();
+}