pi-subagents 0.58.0 → 0.60.0

package/src/workflows/workflow-settlement.ts

@@ -0,0 +1,246 @@
+import type {
+	AsyncStatus,
+	WorkflowRecoveryAction,
+	WorkflowTerminalOutcome,
+	WorkflowTerminalResolution,
+	Usage,
+} from "../shared/types.ts";
+import type { WorkflowReceipt } from "./workflow-receipt.ts";
+import { workflowChildSummary } from "./workflow-child-summary.ts";
+
+export const UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION = "unsupported-continuation: detached workflow child settled, but JavaScript workflow continuation was not persisted. Resume the workflow explicitly instead of treating the completed child as top-level workflow completion.";
+export const INTERRUPTED_DETACHED_CHILD = "Interrupted. Waiting for explicit next action.";
+export const EVIDENCE_PERSISTENCE_FAILED = "evidence-persistence-failed";
+
+export type WorkflowStatusStep = NonNullable<AsyncStatus["steps"]>[number] & {
+	outputPathMapping?: { requestedPath: string; savedPath: string };
+	interrupted?: boolean;
+};
+
+export interface WorkflowPublicChild {
+	workflowKey?: string;
+	agent?: string;
+	/** Human-readable display name for the child session, when derived at launch. */
+	sessionName?: string;
+	runId?: string;
+	usage?: Usage;
+	sessionFile?: string;
+	output: string;
+	outputState: "present" | "absent";
+	structuredOutput?: unknown;
+	success: boolean;
+	terminalOutcome?: WorkflowTerminalOutcome;
+	outputReference?: string;
+	outputPathMapping?: { requestedPath: string; savedPath: string };
+	stopped?: boolean;
+	interrupted?: boolean;
+	detached?: boolean;
+	error?: string;
+	artifactPaths?: { outputPath: string };
+}
+
+export interface WorkflowSettlementPlan {
+	status: AsyncStatus;
+	publicResult: Record<string, unknown>;
+	receipt?: WorkflowReceipt;
+	recovery: WorkflowRecoveryAction[];
+	completionEvent?: Record<string, unknown>;
+}
+
+function cloneWorkflowStatus(status: AsyncStatus): AsyncStatus {
+	return {
+		...status,
+		steps: status.steps?.map((step) => ({ ...step })),
+		workflow: status.workflow ? { ...status.workflow, trace: [...(status.workflow.trace ?? [])] } : status.workflow,
+	};
+}
+
+function workflowState(status: AsyncStatus): "completed" | "failed" | "paused" | "stopped" {
+	return status.state === "complete" ? "completed" : status.state === "paused" ? "paused" : status.state === "stopped" ? "stopped" : "failed";
+}
+
+function withWorkflowChildren(status: AsyncStatus): AsyncStatus {
+	return {
+		...status,
+		workflowChildren: workflowChildSummary({
+			parentToolCallId: status.toolCallId ?? status.runId,
+			workflowRunId: status.runId,
+			workflowState: workflowState(status),
+			inventoryComplete: true,
+			trace: status.workflow?.trace,
+			steps: status.steps,
+		}),
+	};
+}
+
+export function findWorkflowSettlementStep(status: AsyncStatus, childRunId: string, workflowKey?: string, sessionFile?: string): WorkflowStatusStep | undefined {
+	const exact = status.steps?.find((candidate) => candidate.runId === childRunId);
+	if (exact || !workflowKey || !sessionFile) return exact;
+	const candidates = status.steps?.filter((candidate) => candidate.runId === undefined
+		&& candidate.workflowKey === workflowKey
+		&& candidate.sessionFile === sessionFile) ?? [];
+	return candidates.length === 1 ? candidates[0] : undefined;
+}
+
+export function promoteSettledPausedWorkflow(status: AsyncStatus, now = Date.now()): AsyncStatus | undefined {
+	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
+	const next = cloneWorkflowStatus(status);
+	const stillOpen = next.steps?.some((candidate) =>
+		candidate.status === "running"
+		|| (candidate.status === "paused" && candidate.activityState === "needs_attention")
+	) === true;
+	if (stillOpen || !next.steps?.length) return undefined;
+	const failed = next.steps.some((candidate) => candidate.status === "failed");
+	next.lastUpdate = now;
+	next.state = "failed";
+	next.endedAt = now;
+	delete next.activityState;
+	if (!failed) next.error = UNSUPPORTED_DETACHED_WORKFLOW_CONTINUATION;
+	return withWorkflowChildren(next);
+}
+
+export function applyDetachedChildSettlement(
+	status: AsyncStatus,
+	input: { childRunId: string; result: { exitCode: number | null; error?: string; interrupted?: boolean; sessionFile?: string; sessionName?: string; stopped?: boolean }; workflowKey?: string; now?: number },
+): AsyncStatus | undefined {
+	if (status.mode !== "workflow" || status.state !== "paused") return undefined;
+	const next = cloneWorkflowStatus(status);
+	const step = findWorkflowSettlementStep(next, input.childRunId, input.workflowKey, input.result.sessionFile);
+	if (!step) return undefined;
+	step.runId ??= input.childRunId;
+	const succeeded = input.result.exitCode === 0 && !input.result.error && !input.result.interrupted;
+	const failedSiblingError = next.steps?.find((candidate) => {
+		const candidateStep = candidate as WorkflowStatusStep;
+		return candidateStep !== step && candidateStep.status === "failed" && !candidateStep.interrupted && candidateStep.error;
+	})?.error;
+	const interruptedChildError = next.steps?.find((candidate) => {
+		const candidateStep = candidate as WorkflowStatusStep;
+		return candidateStep.status === "failed" && candidateStep.interrupted && candidateStep.error;
+	})?.error;
+	const now = input.now ?? Date.now();
+	step.status = succeeded ? "completed" : "failed";
+	step.endedAt = now;
+	delete step.activityState;
+	delete step.currentTool;
+	delete step.currentToolStartedAt;
+	if (input.result.sessionFile) step.sessionFile = input.result.sessionFile;
+	if (input.result.sessionName) step.sessionName = input.result.sessionName;
+	if (succeeded) {
+		delete step.error;
+		delete step.interrupted;
+	} else if (input.result.interrupted || input.result.stopped) {
+		step.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+		step.interrupted = true;
+		if (input.result.stopped) step.stopped = true;
+	} else {
+		delete step.interrupted;
+		delete step.stopped;
+		if (input.result.error) step.error = input.result.error;
+	}
+	next.lastUpdate = now;
+	const promoted = promoteSettledPausedWorkflow(next, now);
+	if (promoted?.state === "failed" && failedSiblingError) promoted.error = failedSiblingError;
+	else if (promoted?.state === "failed" && (input.result.interrupted || input.result.stopped)) promoted.error = input.result.error ?? INTERRUPTED_DETACHED_CHILD;
+	else if (promoted?.state === "failed" && input.result.error) promoted.error = input.result.error;
+	else if (promoted?.state === "failed" && interruptedChildError) promoted.error = interruptedChildError;
+	return withWorkflowChildren(promoted ?? next);
+}
+
+export function classifyWorkflowSettlement(status: AsyncStatus, interrupted = false): WorkflowTerminalResolution | undefined {
+	if (status.state !== "complete" && status.state !== "failed") return undefined;
+	if (status.steps?.some((step) => {
+		const candidate = step as WorkflowStatusStep;
+		return candidate.status === "failed" && !candidate.interrupted;
+	})) return "failed-child";
+	if (interrupted || status.steps?.some((step) => {
+		const candidate = step as WorkflowStatusStep;
+		return candidate.status === "stopped" || candidate.stopped || candidate.interrupted || candidate.error === INTERRUPTED_DETACHED_CHILD;
+	})) return "interrupted-child";
+	return "settled-awaiting-resume";
+}
+
+export function workflowRecoveryActions(receipt: WorkflowReceipt | undefined): WorkflowRecoveryAction[] {
+	if (!receipt) return [];
+	return Object.values(receipt.entries).flatMap((entry) => entry.resumability.state === "resumable"
+		? [{ key: entry.key, call: "runs.run" as const, resume: { workflowRunId: receipt.workflowRunId, key: entry.key, latest: true as const }, taskRequired: true as const }]
+		: []);
+}
+
+export function workflowTerminalOutcomeForResult(result: { timedOut?: boolean; turnBudgetExceeded?: boolean; toolBudgetBlocked?: boolean }): WorkflowTerminalOutcome | undefined {
+	if (result.timedOut) return { state: "partial", reason: "timeout" };
+	if (result.turnBudgetExceeded || result.toolBudgetBlocked) return { state: "partial", reason: "budget_exhausted" };
+	return undefined;
+}
+
+export function workflowOutputPathMappingSummary(children: readonly unknown[]): string {
+	const mappings = children.flatMap((entry) => {
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) return [];
+		const child = entry as Partial<WorkflowPublicChild>;
+		return child.outputPathMapping
+			? [`'${child.workflowKey ?? "child"}': requested ${child.outputPathMapping.requestedPath} -> saved ${child.outputPathMapping.savedPath}`]
+			: [];
+	});
+	return mappings.length > 0 ? ` Output path mappings: ${mappings.join("; ")}.` : "";
+}
+
+export function planWorkflowSettlement(input: {
+	status: AsyncStatus;
+	summary: string;
+	children: WorkflowPublicChild[];
+	baseResult: Record<string, unknown>;
+	receipt?: WorkflowReceipt;
+	receiptPath?: string;
+	receiptPersistenceError?: string;
+	resolution?: WorkflowTerminalResolution;
+	terminalOutcome?: WorkflowTerminalOutcome;
+	now?: number;
+	eventMetadata?: Record<string, unknown>;
+}): WorkflowSettlementPlan {
+	const now = input.now ?? Date.now();
+	let status = withWorkflowChildren(cloneWorkflowStatus(input.status));
+	let summary = input.summary;
+	let receipt = input.receipt;
+	let resolution = input.resolution;
+	if (input.receiptPersistenceError) {
+		const diagnostic = `${EVIDENCE_PERSISTENCE_FAILED}: ${input.receiptPersistenceError}`;
+		status = withWorkflowChildren({ ...status, state: "failed", error: diagnostic, activityState: undefined, endedAt: now, lastUpdate: now });
+		summary = `${diagnostic} Available child evidence was preserved, but workflow completion was not accepted.`;
+		receipt = undefined;
+		if (!resolution) resolution = classifyWorkflowSettlement(status);
+	}
+	const recovery = workflowRecoveryActions(receipt);
+	if (receipt) {
+		receipt = {
+			...receipt,
+			state: status.state === "complete" ? "complete" : status.state === "paused" ? "paused" : status.state === "stopped" ? "stopped" : "failed",
+			workflowChildren: status.workflowChildren,
+			...(resolution ? { workflowResolution: resolution, recovery } : {}),
+		};
+	}
+	const publicResult: Record<string, unknown> = {
+		...input.baseResult,
+		success: status.state === "complete",
+		state: status.state,
+		summary,
+		error: status.state === "complete" ? undefined : status.error ?? summary,
+		stopped: status.stopped ? true : undefined,
+		activityState: status.activityState,
+		workflowChildren: status.workflowChildren,
+		results: input.children,
+		...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}),
+		...(resolution ? { workflowResolution: resolution, recovery } : {}),
+		...(receipt && input.receiptPath ? { workflowReceipt: { path: input.receiptPath, receipt } } : {}),
+		timestamp: now,
+	};
+	const terminal = status.state === "complete" || status.state === "failed" || status.state === "partial" || status.state === "stopped";
+	const completionEvent = terminal ? {
+		type: "subagent.workflow.completed",
+		state: status.state,
+		...(resolution ? { workflowResolution: resolution } : {}),
+		...(input.terminalOutcome ? { terminalOutcome: input.terminalOutcome } : {}),
+		...(status.error ? { error: status.error } : {}),
+		...(status.activityState ? { activityState: status.activityState } : {}),
+		...input.eventMetadata,
+	} : undefined;
+	return { status, publicResult, receipt, recovery, completionEvent };
+}

package/src/runs/shared/turn-budget.ts

@@ -1,98 +0,0 @@
-import type { ResolvedTurnBudget, TurnBudgetState } from "../../shared/types.ts";
-
-export const DEFAULT_TURN_BUDGET_GRACE_TURNS = 1;
-
-export function resolveTurnBudgetConfig(
-	raw: unknown,
-	label = "turnBudget",
-): { turnBudget?: ResolvedTurnBudget; error?: string } {
-	if (raw === undefined) return {};
-	if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-		return { error: `${label} must be an object with maxTurns and optional graceTurns.` };
-	}
-	const unknownField = Object.keys(raw).find((key) => key !== "maxTurns" && key !== "graceTurns");
-	if (unknownField) return { error: `${label}.${unknownField} is not supported.` };
-	const budget = raw as { maxTurns?: unknown; graceTurns?: unknown };
-	if (typeof budget.maxTurns !== "number" || !Number.isInteger(budget.maxTurns) || budget.maxTurns < 1) {
-		return { error: `${label}.maxTurns must be an integer >= 1.` };
-	}
-	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
-	if (typeof graceTurns !== "number" || !Number.isInteger(graceTurns) || graceTurns < 0) {
-		return { error: `${label}.graceTurns must be an integer >= 0.` };
-	}
-	return { turnBudget: { maxTurns: budget.maxTurns, graceTurns } };
-}
-
-export function appendTurnBudgetSystemPrompt(systemPrompt: string, budget: { maxTurns: number; graceTurns?: number } | undefined): string {
-	if (!budget) return systemPrompt;
-	const graceTurns = budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS;
-	const grace = graceTurns === 1 ? "1 additional assistant turn" : `${graceTurns} additional assistant turns`;
-	const block = [
-		"## Turn budget",
-		`This child run has a soft budget of ${budget.maxTurns} assistant turn${budget.maxTurns === 1 ? "" : "s"}.`,
-		`After that, ${grace} may be allowed only for a final wrap-up.`,
-		"When you approach or reach the soft budget, stop starting new tool work and return the final answer immediately.",
-		"This runner uses process-mode execution, so live steering after launch may be unavailable; treat this instruction as the wrap-up request.",
-		"If you continue past the soft budget plus grace turns, the supervisor may abort the process and return only partial output.",
-	].join("\n");
-	return systemPrompt.trim() ? `${systemPrompt.trim()}\n\n${block}` : block;
-}
-
-export function turnBudgetSoftNote(budget: ResolvedTurnBudget, turnCount: number): string {
-	return `Turn budget wrap-up was requested after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns}, grace ${budget.graceTurns}). Process-mode live steering is unavailable, so the child was warned at launch to wrap up by this budget. Output may be partial.`;
-}
-
-export function turnBudgetExceededMessage(budget: ResolvedTurnBudget, turnCount: number): string {
-	return `Subagent exceeded turn budget after ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}).`;
-}
-
-export function turnBudgetDeferredNote(budget: ResolvedTurnBudget, turnCount: number): string {
-	return `Turn-budget termination was deferred at ${turnCount} assistant turn${turnCount === 1 ? "" : "s"} (soft limit ${budget.maxTurns} + grace ${budget.graceTurns}) because the assistant started tool work. The run ended before another safe assistant boundary; output may be partial.`;
-}
-
-export function formatTurnBudgetOutput(message: string, output: string): string {
-	return output.trim()
-		? `${message}\n\nPartial output before turn-budget abort:\n${output}`
-		: message;
-}
-
-export function initialTurnBudgetState(budget: { maxTurns: number; graceTurns?: number }): TurnBudgetState {
-	return { maxTurns: budget.maxTurns, graceTurns: budget.graceTurns ?? DEFAULT_TURN_BUDGET_GRACE_TURNS, outcome: "within-budget", turnCount: 0 };
-}
-
-export function turnBudgetState(budget: ResolvedTurnBudget, turnCount: number, exceeded: boolean): TurnBudgetState {
-	return {
-		...budget,
-		turnCount,
-		outcome: exceeded ? "exceeded" : "wrap-up-requested",
-		wrapUpRequestedAtTurn: budget.maxTurns,
-		...(exceeded ? { exceededAtTurn: turnCount } : {}),
-	};
-}
-
-export function turnBudgetDeferredState(
-	budget: ResolvedTurnBudget,
-	turnCount: number,
-	terminationDeferredAtTurn = turnCount,
-): TurnBudgetState {
-	return {
-		...budget,
-		turnCount,
-		outcome: "termination-deferred",
-		wrapUpRequestedAtTurn: budget.maxTurns,
-		terminationDeferredAtTurn,
-	};
-}
-
-export function turnBudgetDecision(
-	budget: ResolvedTurnBudget,
-	turnCount: number,
-	terminalAssistantStop: boolean,
-	toolWorkActiveOrStarting: boolean,
-	enforceHardLimit = false,
-): "continue" | "defer" | "abort" {
-	const hardLimit = budget.maxTurns + budget.graceTurns;
-	if (terminalAssistantStop || turnCount < hardLimit) return "continue";
-	if (toolWorkActiveOrStarting && !enforceHardLimit) return "defer";
-	return "abort";
-}