pi-subagents 0.56.0 → 0.58.0

package/src/runs/background/wait-completions.ts

@@ -3,6 +3,7 @@ import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild
 import type { AsyncRunSummary } from "./async-status.ts";
 import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
 import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
+import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
 
 function asNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value ? value : undefined;
@@ -60,6 +61,8 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 	const agent = asNonEmptyString(data.agent);
 	const mode = asNonEmptyString(data.mode);
 	const state = asNonEmptyString(data.state);
+	const workflowChildren = parseWorkflowChildSummary(data.workflowChildren);
+	if (workflowChildren && workflowChildren.workflowRunId !== runId) throw new Error("workflowChildren.workflowRunId does not match its completion run id.");
 	return {
 		runId,
 		...(agent ? { agent } : {}),
@@ -67,6 +70,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 		...(state ? { state } : {}),
 		...(typeof data.success === "boolean" ? { success: data.success } : {}),
 		...(results && results.length > 0 ? { results } : {}),
+		...(workflowChildren ? { workflowChildren } : {}),
 	};
 }
 

package/src/runs/foreground/execution.ts

@@ -6,7 +6,7 @@ import { spawn } from "node:child_process";
 import { existsSync, unlinkSync } from "node:fs";
 import * as path from "node:path";
 import type { Message } from "@earendil-works/pi-ai";
-import type { AgentConfig } from "../../agents/agents.ts";
+import { discoverAgents, formatUnknownAgentError, unknownAgentDiagnosticContext, type AgentConfig } from "../../agents/agents.ts";
 import { appendAgentRefinementOverlay } from "../../agents/agent-refinements.ts";
 import { alignForkedSessionCwd } from "../../shared/fork-context.ts";
 import {
@@ -58,6 +58,7 @@ import { effectiveToolTimeoutMs, formatToolTimeoutMessage, resolveToolTimeoutMs,
 import { evaluateCompletionMutationGuard, validateImplementationToolContract } from "../shared/completion-guard.ts";
 import { arbitrateCompletionGuardRescue } from "../shared/llm-intent-arbiter.ts";
 import { getPiSpawnCommand } from "../shared/pi-spawn.ts";
+import { preflightLaunchCwd } from "../shared/launch-cwd.ts";
 import { createJsonlWriter } from "../../shared/jsonl-writer.ts";
 import { createOrcaProgressTab, type OrcaProgressTab } from "../shared/orca-progress-tabs.ts";
 import { attachPostExitStdioGuard, trySignalChild } from "../../shared/post-exit-stdio-guard.ts";
@@ -68,7 +69,7 @@ import { assertAgentAllowedByCapabilityCeiling, decodeSubagentCapabilityCeiling,
 import { resolveEffectiveThinking } from "../../shared/model-info.ts";
 import { assertThinkingWithinCeiling, decodeThinkingCeiling, intersectThinkingCeilings, SUBAGENT_THINKING_CEILING_ENV } from "../../shared/thinking-ceiling.ts";
 import { MISSING_STRUCTURED_OUTPUT_CALL_ERROR, readStructuredOutput, readStructuredOutputAcceptanceReport } from "../shared/structured-output.ts";
-import { formatProcessSignalError, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
+import { formatMidToolExitError, formatProcessSignalError, isOrdinaryToolForMidToolExit, isUnexplainedProcessSignal } from "../shared/process-signal.ts";
 import { readChildToolDiagnosticError } from "../shared/tool-availability.ts";
 import { buildTimeoutRecoverySummary, collectTrackedMutationEvidence, snapshotTrackedMutations } from "../shared/mutation-evidence.ts";
 import { captureSingleOutputSnapshot, extractChildWrittenOutput, finalizeSingleOutput, formatSavedOutputReference, injectOutputPathSystemPrompt, resolveSingleOutput, validateFileOnlyOutputMode, type SingleOutputSnapshot } from "../shared/single-output.ts";
@@ -77,7 +78,7 @@ import {
 	formatSubagentModelVerificationError,
 	formatModelAttemptNote,
 	isContextOverflow,
-	isRetryableModelFailure,
+	isRetryableModelFailureAttempt,
 	recordRetryableModelFailure,
 } from "../shared/model-fallback.ts";
 import {
@@ -106,7 +107,8 @@ import { appendTurnBudgetSystemPrompt, formatTurnBudgetOutput, initialTurnBudget
 import { initialToolBudgetState, toolBudgetState } from "../shared/tool-budget.ts";
 import { resolveWatchdogConfig } from "../../watchdog/settings.ts";
 import { agentDefinitionDigest, launchBindingDigest } from "../../shared/launch-contract.ts";
-import { createBoundedByteTail, createBoundedLineReader, formatProtocolOutputLimit, MAX_CHILD_STDERR_BYTES, PI_AGGREGATE_EVENT_PROJECTOR, projectChildLifecycle, type ChildLifecycleAction, type ProtocolOutputLimit } from "../shared/child-protocol.ts";
+import { consumeWorkflowChildPermit } from "../../shared/workflow-child-permit.ts";
+import { createBoundedByteTail, createBoundedLineReader, formatProtocolOutputLimit, MAX_CHILD_STDERR_BYTES, PI_AGGREGATE_EVENT_PROJECTOR, projectChildLifecycle, type ChildLifecycleAction, type ChildLifecycleState, type ProtocolOutputLimit } from "../shared/child-protocol.ts";
 import {
 	acceptChildWatchdogEvent,
 	childWatchdogIsActive,
@@ -345,6 +347,7 @@ async function runSingleAttempt(
 		thinking: effectiveThinking,
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
+		inheritGlobalContext: agent.inheritGlobalContext,
 		inheritSkills: agent.inheritSkills,
 		requireReadTool: Boolean(shared.resolvedSkillNames?.length),
 		tools: agent.tools,
@@ -380,6 +383,7 @@ async function runSingleAttempt(
 		capabilityCeiling: options.capabilityCeiling,
 		thinkingCeiling: options.thinkingCeiling,
 		extensionBindings: options.extensionBindings,
+		runtimeSnapshotHost: options.runtimeSnapshotHost,
 	});
 	if (!shared.launchWarnings.emitted && warnings.length > 0) {
 		for (const warning of warnings) console.warn(`[pi-subagents] ${warning}`);
@@ -402,6 +406,7 @@ async function runSingleAttempt(
 		inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
 		agentName: agent.name,
 		permissionRules,
+		runtimeSnapshotHost: options.runtimeSnapshotHost,
 	});
 	const contractTools = toolPlan.explicitToolAllowlist ? toolPlan.effectiveToolAllowlist : undefined;
 	const contractError = validateImplementationToolContract({
@@ -445,6 +450,7 @@ async function runSingleAttempt(
 		systemPrompt: effectiveSystemPrompt,
 		systemPromptMode: agent.systemPromptMode,
 		inheritProjectContext: agent.inheritProjectContext,
+		inheritGlobalContext: agent.inheritGlobalContext,
 		inheritSkills: agent.inheritSkills,
 		skills: shared.resolvedSkillNames ?? [],
 		tools: toolPlan.effectiveToolAllowlist,
@@ -538,9 +544,29 @@ async function runSingleAttempt(
 	let structuredOutputToolInvoked = false;
 	let structuredOutputMessageStartIndex: number | undefined;
 	let toolAvailabilityError: string | undefined;
+	let abortedBySignal = options.signal?.aborted === true;
 
+	const spawnSpec = getPiSpawnCommand(args);
+	if (options.workflowChildPermitLaunch) {
+		const permitError = consumeWorkflowChildPermit(options.workflowChildPermitLaunch.permit, {
+			workflowRunId: options.workflowChildPermitLaunch.workflowRunId,
+			childKey: options.workflowChildPermitLaunch.childKey,
+			agent: agent.name,
+			launchContractDigest,
+			context: options.context ?? "fresh",
+			runner: "pi",
+		});
+		if (permitError) {
+			cleanupTempDir(tempDir);
+			result.exitCode = 1;
+			result.error = permitError;
+			result.finalOutput = permitError;
+			progress.status = "failed";
+			progress.error = permitError;
+			return result;
+		}
+	}
 	const exitCode = await new Promise<number>((resolve) => {
-		const spawnSpec = getPiSpawnCommand(args);
 		const proc = spawn(spawnSpec.command, spawnSpec.args, {
 			cwd: options.cwd ?? runtimeCwd,
 			env: spawnEnv,
@@ -707,6 +733,7 @@ async function runSingleAttempt(
 			}
 			if (action === "start-drain") startFinalDrain();
 		};
+		const childLifecycleState: ChildLifecycleState = { compactionRetryActive: false };
 
 		const unsubscribeIntercomDetach = options.intercomEvents?.on?.(INTERCOM_DETACH_REQUEST_EVENT, (payload) => {
 			if (!options.allowIntercomDetach || processClosed) return;
@@ -994,8 +1021,9 @@ async function runSingleAttempt(
 			}
 			shared.transcriptWriter?.writeChildEvent(evt);
 			shared.orcaProgressTab?.event(evt);
-			if (evt.type === "agent_settled") agentSettledReceived = true;
-			applyChildLifecycle(projectChildLifecycle(evt));
+			const lifecycleAction = projectChildLifecycle(evt, false, childLifecycleState);
+			if (evt.type === "agent_settled" && lifecycleAction === "start-drain") agentSettledReceived = true;
+			applyChildLifecycle(lifecycleAction);
 
 			if (isChildWatchdogStatusEvent(evt)) {
 				if (!childWatchdog) return;
@@ -1041,7 +1069,7 @@ async function runSingleAttempt(
 				if (options.toolBudget) {
 					result.toolBudget = toolBudgetState(options.toolBudget, progress.toolCount);
 				}
-				const mutates = isMutatingTool(evt.toolName, toolArgs);
+				const mutates = isMutatingTool(evt.toolName, toolArgs, agent.mutationTools);
 				observedMutationAttempt = observedMutationAttempt || mutates;
 				pendingToolResult = { tool: evt.toolName ?? "tool", path: activeTool?.path, mutates, startedAt: now };
 				fireUpdate();
@@ -1078,6 +1106,7 @@ async function runSingleAttempt(
 					updateTurnBudget(result.usage.turns, terminalAssistantStop || terminalStructuredOutputCall, hasToolCall || Boolean(progress.currentTool));
 					const u = evt.message.usage;
 					if (u) {
+						const window = (u.input || 0) + (u.cacheRead || 0);
 						result.usage.input += u.input || 0;
 						result.usage.output += u.output || 0;
 						result.usage.cacheRead += u.cacheRead || 0;
@@ -1086,6 +1115,8 @@ async function runSingleAttempt(
 						progress.tokens = result.usage.input + result.usage.output;
 						progress.inputTokens = result.usage.input;
 						progress.outputTokens = result.usage.output;
+						progress.window = window;
+						progress.windowPeak = Math.max(progress.windowPeak ?? 0, window);
 					}
 					if (evt.message.model) {
 						progress.model = evt.message.model;
@@ -1102,7 +1133,11 @@ async function runSingleAttempt(
 					if (terminalAssistantStop) {
 						if (!evt.message.errorMessage && assistantText.trim()) assistantError = undefined;
 						cleanTerminalAssistantStopReceived ||= !evt.message.errorMessage;
-						applyChildLifecycle(projectChildLifecycle(evt, true));
+						clearAllToolTimeouts();
+						activeToolCalls.clear();
+						activeToolKeysByName.clear();
+						refreshCurrentTool();
+						applyChildLifecycle(projectChildLifecycle(evt, true, childLifecycleState));
 					}
 				}
 				updateActivityState(now);
@@ -1369,6 +1404,7 @@ async function runSingleAttempt(
 		if (options.signal) {
 			const kill = () => {
 				if (processClosed || lifecycleFinished) return;
+				abortedBySignal = true;
 				proc.kill("SIGTERM");
 				setTimeout(() => !proc.killed && proc.kill("SIGKILL"), 3000);
 			};
@@ -1431,6 +1467,22 @@ async function runSingleAttempt(
 		};
 		return result;
 	}
+	if (progress.currentTool
+		&& isOrdinaryToolForMidToolExit(progress.currentTool)
+		&& !abortedBySignal
+		&& !result.timedOut
+		&& !result.stopped
+		&& !result.turnBudgetExceeded
+		&& !result.protocolError
+		&& !toolAvailabilityError) {
+		const processExitCode = result.exitCode;
+		result.exitCode = 1;
+		result.error = formatMidToolExitError({
+			toolName: progress.currentTool,
+			exitCode: processExitCode,
+			processSignal: result.processSignal,
+		});
+	}
 	result.error = formatSubagentExtensionConflictError(result.error, {
 		agent: agent.name,
 		ambientExtensionsEnabled: !launchResolvedExtensions.disableAmbientExtensions,
@@ -1536,6 +1588,7 @@ async function runSingleAttempt(
 			messages: result.messages ?? [],
 			tools: contractTools,
 			mcpDirectTools: toolPlan.effectiveMcpTools,
+			mutationTools: agent.mutationTools,
 			toolAvailabilityError,
 			mutationEvidence,
 		})
@@ -1641,12 +1694,27 @@ async function runSyncCompletionInner(
 	task: string,
 	options: RunSyncOptions,
 ): Promise<SingleResult> {
+	const effectiveCwd = options.cwd ?? runtimeCwd;
+	const cwdError = preflightLaunchCwd(options.requestedCwd ?? effectiveCwd, effectiveCwd);
+	if (cwdError) {
+		return redactResultPrompt(withRunContext({
+			index: options.index ?? 0,
+			agent: agentName,
+			task,
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			error: cwdError,
+		}, options.context));
+	}
 	options = {
 		...options,
 		capabilityCeiling: intersectSubagentCapabilityCeilings(options.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(options.parentSessionId), decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV])),
 	};
 	const agent = agents.find((a) => a.name === agentName);
 	if (!agent) {
+		const diagnosticContext = options.unknownAgentDiagnosticContext
+			?? unknownAgentDiagnosticContext(discoverAgents(path.resolve(options.cwd ?? runtimeCwd), "both"));
 		return redactResultPrompt(withRunContext({
 			index: options.index ?? 0,
 			agent: agentName,
@@ -1654,7 +1722,7 @@ async function runSyncCompletionInner(
 			exitCode: 1,
 			messages: [],
 			usage: emptyUsage(),
-			error: `Unknown agent: ${agentName}`,
+			error: formatUnknownAgentError(agentName, diagnosticContext),
 		}, options.context));
 	}
 	options = {
@@ -1781,6 +1849,18 @@ async function runSyncCompletionInner(
 		agent.modelProvider ?? options.preferredModelProvider,
 		{ scope: options.modelScope, primaryModelFromParent: options.modelOverrideFromParent },
 	);
+	if (options.workflowChildPermitLaunch && candidates.length > 1) {
+		const error = "Workflow child permit does not support model fallback.";
+		return redactResultPrompt(withRunContext({
+			index: options.index ?? 0,
+			agent: agent.name,
+			task,
+			exitCode: 1,
+			messages: [],
+			usage: emptyUsage(),
+			error,
+		}, options.context));
+	}
 	try {
 		for (const candidate of candidates) {
 			const model = applyThinkingSuffix(candidate, options.thinkingOverride ?? agent.thinking, options.thinkingOverride !== undefined);
@@ -1914,6 +1994,7 @@ async function runSyncCompletionInner(
 				usage: { ...result.usage },
 			};
 			modelAttempts.push(attempt);
+			if (options.workflowChildPermitLaunch && !attemptSucceeded) break modelAttemptsLoop;
 			// Preserve the legacy intercom handoff contract: once this logical run has
 			// been handed to a supervisor, terminating that attempt must not launch a
 			// startup retry or model fallback. Explicit user detach retains fallback.
@@ -1986,7 +2067,7 @@ async function runSyncCompletionInner(
 				attempt.error = startupError;
 				break modelAttemptsLoop;
 			}
-			const retryableModelFailure = isRetryableModelFailure(result.error);
+			const retryableModelFailure = isRetryableModelFailureAttempt({ error: result.error, messages: result.messages, toolCount: result.progressSummary?.toolCount });
 			if (retryableModelFailure) recordRetryableModelFailure(result.model ?? candidate, result.error);
 			if (isContextOverflow(result.error)) {
 				result.contextOverflow = true;

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

@@ -27,6 +27,8 @@ function copyProgress(target: ForegroundChildControl, progress: AgentProgress |
 	target.tokens = progress.tokens;
 	target.inputTokens = progress.inputTokens;
 	target.outputTokens = progress.outputTokens;
+	target.window = progress.window;
+	target.windowPeak = progress.windowPeak;
 	target.model = progress.model;
 	target.thinking = progress.thinking;
 	target.toolCount = progress.toolCount;
@@ -45,6 +47,8 @@ function syncCurrentChild(control: ForegroundRunControl, child: ForegroundChildC
 	control.tokens = child.tokens;
 	control.inputTokens = child.inputTokens;
 	control.outputTokens = child.outputTokens;
+	control.window = child.window;
+	control.windowPeak = child.windowPeak;
 	control.model = child.model;
 	control.thinking = child.thinking;
 	control.toolCount = child.toolCount;
@@ -65,6 +69,8 @@ function clearCurrentChild(control: ForegroundRunControl): void {
 	control.tokens = undefined;
 	control.inputTokens = undefined;
 	control.outputTokens = undefined;
+	control.window = undefined;
+	control.windowPeak = undefined;
 	control.model = undefined;
 	control.thinking = undefined;
 	control.toolCount = undefined;

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

@@ -4,10 +4,12 @@ import type { ForegroundResumeChild, ForegroundResumeRun, SubagentState } from "
 import { DIRS } from "../../shared/types.ts";
 import { writePrivateAtomicJson } from "../../shared/atomic-json.ts";
 import { utf8Tail } from "../../shared/utf8.ts";
+import { validateAcceptanceInput } from "../shared/acceptance.ts";
 
 export const MAX_REMEMBERED_FOREGROUND_RUNS = 50;
 const HISTORY_VERSION = 1;
 const MAX_INLINE_OUTPUT_BYTES = 64 * 1024;
+const MAX_RESUME_CONTRACT_BYTES = 64 * 1024;
 
 interface ForegroundHistoryIndex {
 	version: 1;
@@ -51,6 +53,7 @@ function compactChild(child: ForegroundResumeChild): ForegroundResumeChild {
 		...(child.transcriptPath ? { transcriptPath: child.transcriptPath } : {}),
 		...(child.transcriptError ? { transcriptError: child.transcriptError } : {}),
 		...(child.acceptance ? { acceptance: child.acceptance } : {}),
+		...(child.resumeContract ? { resumeContract: child.resumeContract } : {}),
 		...(child.launchContractDigest ? { launchContractDigest: child.launchContractDigest } : {}),
 		...(child.extensionBindings ? { extensionBindings: child.extensionBindings } : {}),
 		...(child.capabilityCeiling ? { capabilityCeiling: child.capabilityCeiling } : {}),
@@ -62,9 +65,26 @@ function isRestorableForegroundStatus(status: unknown): status is ForegroundResu
 	return status === "completed" || status === "failed" || status === "paused" || status === "stopped";
 }
 
+function isRestorableResumeContract(value: unknown): boolean {
+	if (value === undefined) return true;
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	try {
+		if (Buffer.byteLength(JSON.stringify(value), "utf8") > MAX_RESUME_CONTRACT_BYTES) return false;
+	} catch {
+		return false;
+	}
+	const contract = value as NonNullable<ForegroundResumeChild["resumeContract"]>;
+	if (Object.keys(contract).some((key) => !["outputSchema", "agentContract", "acceptance", "output", "outputMode"].includes(key))) return false;
+	if (contract.outputSchema !== undefined && (!contract.outputSchema || typeof contract.outputSchema !== "object" || Array.isArray(contract.outputSchema))) return false;
+	if (contract.agentContract !== undefined && (!contract.agentContract || typeof contract.agentContract !== "object" || Array.isArray(contract.agentContract) || contract.agentContract.version !== 1)) return false;
+	if (validateAcceptanceInput(contract.acceptance).length > 0) return false;
+	if (contract.output !== undefined && typeof contract.output !== "string" && typeof contract.output !== "boolean") return false;
+	return contract.outputMode === undefined || contract.outputMode === "inline" || contract.outputMode === "file-only";
+}
+
 function compactRun(run: ForegroundResumeRun): ForegroundResumeRun | undefined {
 	if (!run.sessionId) return undefined;
-	if (run.children.length === 0 || !run.children.every((child) => isRestorableForegroundStatus(child.status))) return undefined;
+	if (run.children.length === 0 || !run.children.every((child) => isRestorableForegroundStatus(child.status) && isRestorableResumeContract(child.resumeContract))) return undefined;
 	return {
 		runId: run.runId,
 		mode: run.mode,
@@ -102,6 +122,7 @@ function isRestorableRun(value: unknown): value is ForegroundResumeRun {
 		&& run.children.every((child) => Boolean(child && typeof child === "object" && !Array.isArray(child)
 			&& typeof (child as Partial<ForegroundResumeChild>).agent === "string"
 			&& typeof (child as Partial<ForegroundResumeChild>).index === "number"
+			&& isRestorableResumeContract((child as Partial<ForegroundResumeChild>).resumeContract)
 			&& isRestorableForegroundStatus((child as Partial<ForegroundResumeChild>).status)));
 }