pi-subagents 0.68.0 → 0.70.0

package/src/runs/foreground/workflow-detach-reconcile.ts

@@ -1,304 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import { getSingleResultOutput, readStatus } from "../../shared/utils.ts";
-import {
-	DIRS,
-	SUBAGENT_ASYNC_COMPLETE_EVENT,
-	type AsyncStatus,
-	type IntercomEventBus,
-	type SingleResult,
-	type SubagentState,
-	type WorkflowTerminalResolution,
-} from "../../shared/types.ts";
-import { updateActiveRunIndex } from "../background/active-run-index.ts";
-import { resultFilePath, writeAsyncResultFile } from "../background/result-files.ts";
-import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
-import { externalCliReceiptMetadata, normalizeExternalCliRunnerStatus } from "../shared/external-cli-contract.ts";
-import { outputPathMappingFromTask } from "../shared/single-output.ts";
-import { readWorkflowReceipt, workflowReceiptPath, writeWorkflowReceipt, type WorkflowReceipt } from "../../workflows/workflow-receipt.ts";
-import {
-	applyDetachedChildSettlement,
-	classifyWorkflowSettlement,
-	findWorkflowSettlementStep,
-	planWorkflowSettlement,
-	promoteSettledPausedWorkflow,
-	workflowOutputPathMappingSummary,
-	workflowRecoveryActions,
-	workflowTerminalOutcomeForResult,
-	type WorkflowPublicChild,
-	type WorkflowStatusStep,
-} from "../../workflows/workflow-settlement.ts";
-
-export function applyDetachedChildToPausedWorkflow(
-	status: AsyncStatus,
-	input: { childRunId: string; result: Pick<SingleResult, "exitCode" | "error" | "interrupted" | "sessionFile" | "sessionName" | "stopped">; workflowKey?: string },
-): AsyncStatus | undefined {
-	return applyDetachedChildSettlement(status, input);
-}
-
-export function promotePausedWorkflowIfSettled(status: AsyncStatus): AsyncStatus | undefined {
-	return promoteSettledPausedWorkflow(status);
-}
-
-function usageWithValue(usage: SingleResult["usage"] | undefined): SingleResult["usage"] | undefined {
-	return usage && (usage.input !== 0 || usage.output !== 0 || usage.cacheRead !== 0 || usage.cacheWrite !== 0 || usage.cost !== 0 || usage.turns !== 0)
-		? usage
-		: undefined;
-}
-
-function workflowResultChildren(status: AsyncStatus, childRunId: string, result: SingleResult, existingResults: unknown, receipt?: WorkflowReceipt): unknown {
-	const output = getSingleResultOutput(result);
-	const outputReference = result.savedOutputPath ?? result.outputReference?.path;
-	const outputPathMapping = outputPathMappingFromTask(result.task, outputReference);
-	const terminalOutcome = workflowTerminalOutcomeForResult(result);
-	const usage = usageWithValue(result.usage);
-	if (Array.isArray(existingResults)) {
-		return existingResults.map((entry) => {
-			if (!entry || typeof entry !== "object" || Array.isArray(entry)) return entry;
-			const child = entry as Record<string, unknown>;
-			if (child.runId !== childRunId) return child;
-			return {
-				...child,
-				success: result.exitCode === 0 && !result.error && !result.interrupted,
-				output,
-				outputState: output.trim() ? "present" : "absent",
-				detached: undefined,
-				...(usage ? { usage } : {}),
-				...(outputReference ? { outputReference } : {}),
-				...(outputPathMapping ? { outputPathMapping } : {}),
-				...(result.interrupted || result.stopped ? { interrupted: true } : {}),
-				...(result.stopped ? { stopped: true } : {}),
-				...(terminalOutcome ? { terminalOutcome } : {}),
-				...(result.sessionName ? { sessionName: result.sessionName } : {}),
-				...(result.sessionFile ? { sessionFile: result.sessionFile } : {}),
-				...(result.error ? { error: result.error } : {}),
-			};
-		});
-	}
-	return status.steps?.map((step: WorkflowStatusStep) => ({
-		workflowKey: step.workflowKey,
-		agent: step.agent,
-		...(step.sessionName ? { sessionName: step.sessionName } : {}),
-		runId: step.runId,
-		success: step.status === "completed" || step.status === "complete",
-		output: step.runId === childRunId ? output : "",
-		outputState: step.runId === childRunId && output.trim() ? "present" : "absent",
-		...(step.runId === childRunId ? { ...(usage ? { usage } : {}), ...(result.sessionFile ? { sessionFile: result.sessionFile } : {}) } : {}),
-		...(step.runId === childRunId && outputReference ? { outputReference } : step.workflowKey && receipt?.entries[step.workflowKey]?.outputReference ? { outputReference: receipt.entries[step.workflowKey]!.outputReference } : {}),
-		...(step.runId === childRunId && outputPathMapping ? { outputPathMapping } : step.outputPathMapping ? { outputPathMapping: step.outputPathMapping } : {}),
-		...(step.interrupted ? { interrupted: true } : {}),
-		...(step.runId === childRunId && terminalOutcome ? { terminalOutcome } : step.workflowKey && receipt?.entries[step.workflowKey]?.terminalOutcome ? { terminalOutcome: receipt.entries[step.workflowKey]!.terminalOutcome } : {}),
-		...(step.stopped ? { stopped: true } : {}),
-		...(step.error ? { error: step.error } : {}),
-	}));
-}
-
-function reconcileWorkflowReceipt(status: AsyncStatus, childRunId: string, result: SingleResult, asyncDir: string, resolution: WorkflowTerminalResolution | undefined): { receipt: WorkflowReceipt; path: string } | undefined {
-	const receiptRoot = path.dirname(asyncDir);
-	const receiptPath = workflowReceiptPath(receiptRoot, status.runId);
-	if (!fs.existsSync(receiptPath)) return undefined;
-	const receipt = readWorkflowReceipt(receiptRoot, status.runId);
-	const step = status.steps?.find((candidate) => candidate.runId === childRunId);
-	const key = step?.workflowKey;
-	if (!key) throw new Error(`Workflow receipt '${status.runId}' cannot identify detached child '${childRunId}' by stable key.`);
-	const entry = receipt.entries[key];
-	if (!entry) throw new Error(`Workflow receipt '${status.runId}' has no detached child key '${key}'.`);
-	let resumability: typeof entry.resumability;
-	try {
-		const target = resolveAsyncResumeTarget({ id: childRunId, dir: path.join(DIRS.async, childRunId) }, {}, { requireSessionFile: true, sessionId: status.sessionId });
-		resumability = target.kind === "revive" ? { state: "resumable" } : { state: "not-resumable", reason: "child is still running" };
-	} catch (error) {
-		resumability = { state: "not-resumable", reason: error instanceof Error ? error.message : String(error) };
-	}
-	const outputReference = result.savedOutputPath ?? result.outputReference?.path ?? entry.outputReference;
-	const childStatus = readStatus(path.join(DIRS.async, childRunId));
-	const externalStep = childStatus?.steps?.length === 1 && childStatus.steps[0]?.runner?.type === "external-cli" ? childStatus.steps[0] : undefined;
-	const externalRunner = normalizeExternalCliRunnerStatus(result.runner?.type === "external-cli" ? result.runner : externalStep?.runner);
-	const externalProcess = result.externalProcess ?? externalStep?.externalProcess;
-	const externalAdapter = externalRunner ? externalCliReceiptMetadata({ runner: externalRunner, externalProcess, outputReference }) : entry.externalAdapter;
-	const childTerminalOutcome = workflowTerminalOutcomeForResult(result) ?? entry.terminalOutcome;
-	if (externalAdapter) resumability = { state: "not-resumable", reason: externalAdapter.nonResumableReason };
-	const updatedEntry: WorkflowReceipt["entries"][string] = resumability.state === "resumable"
-		? {
-			...entry,
-			...(step.agent ? { agent: step.agent } : {}),
-			...(step.context ? { resolvedContext: step.context } : {}),
-			latestRunId: entry.latestRunId ?? childRunId,
-			resumability,
-			...(outputReference ? { outputReference } : {}),
-			...(childTerminalOutcome ? { terminalOutcome: childTerminalOutcome } : {}),
-			...(externalAdapter ? { externalAdapter } : {}),
-		}
-		: {
-			...entry,
-			...(step.agent ? { agent: step.agent } : {}),
-			...(step.context ? { resolvedContext: step.context } : {}),
-			resumability,
-			...(outputReference ? { outputReference } : {}),
-			...(childTerminalOutcome ? { terminalOutcome: childTerminalOutcome } : {}),
-			...(externalAdapter ? { externalAdapter } : {}),
-		};
-	const next: WorkflowReceipt = {
-		...receipt,
-		state: status.state === "complete" ? "complete" : status.state === "stopped" ? "stopped" : status.state === "paused" ? "paused" : "failed",
-		entries: {
-			...receipt.entries,
-			[key]: updatedEntry,
-		},
-		workflowChildren: status.workflowChildren,
-		...(receipt.terminalOutcome ? { terminalOutcome: receipt.terminalOutcome } : {}),
-		...(resolution ? { workflowResolution: resolution } : {}),
-	};
-	if (resolution) next.recovery = workflowRecoveryActions(next);
-	else {
-		delete next.workflowResolution;
-		delete next.recovery;
-	}
-	return { receipt: next, path: writeWorkflowReceipt(asyncDir, next) };
-}
-
-function appendDetachedWorkflowEvent(asyncDir: string, event: Record<string, unknown>): void {
-	const eventsPath = path.join(asyncDir, "events.jsonl");
-	try {
-		fs.appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, "utf-8");
-	} catch (error) {
-		console.error(`Failed to append detached workflow event '${eventsPath}':`, error);
-	}
-}
-
-export function reconcileDetachedWorkflowChildCompletion(input: {
-	state: SubagentState;
-	workflowRunId: string;
-	childRunId: string;
-	result: SingleResult;
-	events?: IntercomEventBus;
-	workflowKey?: string;
-}): boolean {
-	const job = input.state.asyncJobs.get(input.workflowRunId);
-	const asyncDir = job?.asyncDir ?? path.join(DIRS.async, input.workflowRunId);
-	const status = readStatus(asyncDir);
-	if (!status) return false;
-	const matchingControls = input.workflowKey === undefined ? [] : [...(input.state.foregroundControls?.values() ?? [])].filter((control) =>
-		control.parentWorkflowRunId === input.workflowRunId && control.workflowKey === input.workflowKey
-	);
-	const confirmedLiveIdentity = matchingControls.length === 1 && matchingControls[0]?.runId === input.childRunId;
-	if (confirmedLiveIdentity) {
-		const candidates = status.steps?.filter((candidate) => candidate.workflowKey === input.workflowKey) ?? [];
-		const candidate = candidates.length === 1 ? candidates[0] : undefined;
-		if (candidate && candidate.runId === undefined && candidate.sessionFile === undefined
-			&& candidate.status === "paused" && candidate.activityState === "needs_attention") candidate.runId = input.childRunId;
-	}
-	const next = applyDetachedChildToPausedWorkflow(status, {
-		childRunId: input.childRunId,
-		result: input.result,
-		workflowKey: input.workflowKey,
-	});
-	if (!next) return false;
-	const outputReference = input.result.savedOutputPath ?? input.result.outputReference?.path;
-	const outputPathMapping = outputPathMappingFromTask(input.result.task, outputReference);
-	const settledStep = findWorkflowSettlementStep(next, input.childRunId);
-	if (settledStep && outputPathMapping) settledStep.outputPathMapping = outputPathMapping;
-	const resultPath = resultFilePath(DIRS.results, input.workflowRunId);
-	let existing: Record<string, unknown> | undefined;
-	try {
-		const parsed: unknown = JSON.parse(fs.readFileSync(resultPath, "utf-8"));
-		if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) existing = parsed as Record<string, unknown>;
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-	}
-	let receipt: WorkflowReceipt | undefined;
-	let receiptPath: string | undefined;
-	let receiptError: string | undefined;
-	const resolution = classifyWorkflowSettlement(next, input.result.interrupted);
-	try {
-		const publication = reconcileWorkflowReceipt(next, input.childRunId, input.result, asyncDir, resolution);
-		receipt = publication?.receipt;
-		receiptPath = publication?.path;
-	} catch (error) {
-		receiptError = `Failed to reconcile async workflow receipt: ${error instanceof Error ? error.message : String(error)}`;
-	}
-	const results = workflowResultChildren(next, input.childRunId, input.result, existing?.results, receipt) as WorkflowPublicChild[];
-	const recovery = workflowRecoveryActions(receipt);
-	const summary = `${resolution === "settled-awaiting-resume"
-		? `Workflow lanes settled after detached child ${input.childRunId} finished. JavaScript workflow continuation was not persisted.${recovery.length ? " Use the listed keyed recovery action to continue a child." : " No retained child is resumable."}`
-		: next.state === "complete"
-			? `Workflow completed after detached child ${input.childRunId} finished.`
-			: next.error ?? (typeof existing?.summary === "string" ? existing.summary : "Workflow failed.")}${workflowOutputPathMappingSummary(results)}`;
-	const plan = planWorkflowSettlement({
-		status: next,
-		summary,
-		children: results,
-		baseResult: {
-			...(existing ?? {}),
-			id: next.runId,
-			runId: next.runId,
-			toolCallId: next.toolCallId,
-			agent: "workflow",
-			mode: "workflow",
-			endedAt: next.endedAt,
-			workflow: next.workflow,
-			reconciledFromDetachedChild: input.childRunId,
-			asyncDir,
-			cwd: next.cwd,
-			sessionId: next.sessionId ?? (typeof existing?.sessionId === "string" ? existing.sessionId : undefined),
-			completionOwnerId: next.completionOwnerId,
-			...(next.scheduleOrigin ? { scheduleOrigin: next.scheduleOrigin } : {}),
-		},
-		receipt,
-		receiptPath,
-		receiptPersistenceError: receiptError,
-		resolution,
-		terminalOutcome: receipt?.terminalOutcome,
-		eventMetadata: { reconciledFromDetachedChild: input.childRunId },
-	});
-	writeAtomicJson(path.join(asyncDir, "status.json"), plan.status);
-	updateActiveRunIndex(asyncDir, plan.status.state, plan.status.toolCallId);
-	if (job) {
-		job.status = plan.status.state;
-		job.updatedAt = plan.status.lastUpdate;
-		job.activityState = plan.status.activityState;
-		job.steps = plan.status.steps?.map((step, index) => ({ ...step, index }));
-		job.workflow = plan.status.workflow;
-	}
-	writeAsyncResultFile(resultPath, plan.publicResult);
-	if (receiptError) {
-		appendDetachedWorkflowEvent(asyncDir, {
-			ts: Date.now(),
-			runId: input.workflowRunId,
-			type: "subagent.workflow.receipt_write_failed",
-			error: receiptError,
-			reconciledFromDetachedChild: input.childRunId,
-		});
-	}
-	if (plan.completionEvent) {
-		appendDetachedWorkflowEvent(asyncDir, {
-			ts: Date.now(),
-			runId: input.workflowRunId,
-			...plan.completionEvent,
-			recovery: plan.recovery,
-		});
-		input.events?.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, {
-			id: input.workflowRunId,
-			runId: input.workflowRunId,
-			source: "async",
-			mode: "workflow",
-			agent: "workflow",
-			success: plan.status.state === "complete",
-			state: plan.status.state,
-			...(plan.publicResult.workflowReceipt ? { workflowReceipt: plan.publicResult.workflowReceipt } : {}),
-			...(resolution ? { workflowResolution: resolution } : {}),
-			...(plan.receipt?.terminalOutcome ? { terminalOutcome: plan.receipt.terminalOutcome } : {}),
-			recovery: plan.recovery,
-			summary: typeof plan.publicResult.summary === "string" ? plan.publicResult.summary : plan.status.error,
-			reconciledFromDetachedChild: input.childRunId,
-			results,
-			sessionId: plan.status.sessionId,
-			completionOwnerId: plan.status.completionOwnerId,
-			...(plan.status.scheduleOrigin ? { scheduleOrigin: plan.status.scheduleOrigin } : {}),
-			timestamp: Date.now(),
-			triggerTurn: true,
-		});
-	}
-	return true;
-}

package/src/runs/foreground/workflow-foreground-steering.ts

@@ -1,169 +0,0 @@
-import { randomUUID } from "node:crypto";
-import * as path from "node:path";
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import type { Details, ForegroundRunControl, SubagentState } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.ts";
-import { steeringReceipt, waitForSteeringAction } from "../background/steering.ts";
-import { requestAsyncSteer, type SteerDeliveryMode } from "../background/control-channel.ts";
-import { currentCompletionOwnerId } from "../../shared/completion-owner.ts";
-import { workflowAsyncChildSteeringGuidance } from "../shared/workflow-async-child-guidance.ts";
-
-export interface WorkflowForegroundSteeringTarget {
-	control: ForegroundRunControl;
-	workflowRunId: string;
-	sourceRunId: string;
-}
-
-export type WorkflowForegroundSteeringResolution =
-	| { ok: true; target: WorkflowForegroundSteeringTarget }
-	| { ok: false; message: string };
-
-function activeWorkflowError(state: SubagentState, workflowRunId: string, asyncDirRoot: string): string | undefined {
-	if (!state.currentSessionId) return "Workflow steering requires an active parent session.";
-	if (!state.workflowControllers?.has(workflowRunId)) return `Workflow '${workflowRunId}' has no live foreground child.`;
-	const status = readStatus(path.join(asyncDirRoot, workflowRunId));
-	if (!status || status.mode !== "workflow" || (status.state !== "running" && status.state !== "queued")) {
-		return `Workflow '${workflowRunId}' has no live foreground child.`;
-	}
-	if (status.sessionId !== state.currentSessionId) return `Workflow '${workflowRunId}' was not found in the active session.`;
-	return undefined;
-}
-
-function controlIsLiveInWorkflow(control: ForegroundRunControl, workflowRunId: string, sessionId: string): boolean {
-	return control.parentWorkflowRunId === workflowRunId
-		&& control.sessionId === sessionId
-		&& (control.activeChildren?.size ?? 0) > 0;
-}
-
-export function resolveWorkflowForegroundSteeringTarget(input: {
-	state: SubagentState;
-	childRunId?: string;
-	workflowRunId?: string;
-	asyncDirRoot: string;
-}): WorkflowForegroundSteeringResolution {
-	const { state, childRunId, asyncDirRoot } = input;
-	if (childRunId) {
-		const control = state.foregroundControls.get(childRunId);
-		if (!control?.parentWorkflowRunId) return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child.` };
-		const workflowRunId = control.parentWorkflowRunId;
-		const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
-		if (workflowError) return { ok: false, message: workflowError };
-		if (!controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!)) {
-			return { ok: false, message: `Foreground run '${childRunId}' is not a live workflow-owned child in the active session.` };
-		}
-		return { ok: true, target: { control, workflowRunId, sourceRunId: childRunId } };
-	}
-
-	const workflowRunId = input.workflowRunId;
-	if (!workflowRunId) return { ok: false, message: "Workflow steering requires a workflow or child run id." };
-	const workflowError = activeWorkflowError(state, workflowRunId, asyncDirRoot);
-	if (workflowError) return { ok: false, message: workflowError };
-	const controls = [...state.foregroundControls.values()].filter((control) => controlIsLiveInWorkflow(control, workflowRunId, state.currentSessionId!));
-	if (controls.length === 0) return { ok: false, message: `Workflow '${workflowRunId}' has no live foreground child.` };
-	if (controls.length > 1) return { ok: false, message: `Workflow '${workflowRunId}' has ${controls.length} live foreground children; steer a child run id instead.` };
-	return { ok: true, target: { control: controls[0]!, workflowRunId, sourceRunId: workflowRunId } };
-}
-
-function managementError(message: string): AgentToolResult<Details> {
-	return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
-}
-
-/** Local controllers remain authoritative; recorded foreign ownership permits enqueue, not takeover or proof of liveness. */
-export async function steerWorkflowRun(input: {
-	state: SubagentState;
-	runId: string;
-	asyncDir: string;
-	message: string;
-	mode?: SteerDeliveryMode;
-	index?: number;
-	signal?: AbortSignal;
-	ackTimeoutMs?: number;
-}): Promise<AgentToolResult<Details>> {
-	const { state, runId, asyncDir } = input;
-	const status = readStatus(asyncDir);
-	if (!status || status.mode !== "workflow" || status.runId !== runId || path.basename(asyncDir) !== runId) {
-		return managementError(`Workflow '${runId}' does not match its resolved run directory.`);
-	}
-	if (state.workflowControllers?.has(runId)) {
-		const route = resolveWorkflowForegroundSteeringTarget({ state, workflowRunId: runId, asyncDirRoot: path.dirname(asyncDir) });
-		if (!route.ok) return managementError([route.message, ...workflowAsyncChildSteeringGuidance(status, state)].join("\n"));
-		return steerWorkflowForegroundTarget({ target: route.target, message: input.message, mode: input.mode, index: input.index });
-	}
-	if (!state.currentSessionId) return managementError("Workflow steering requires an active parent session.");
-	if (status.sessionId !== state.currentSessionId) return managementError(`Workflow '${runId}' was not found in the active session.`);
-	if (status.state !== "running" && status.state !== "queued") return managementError(`Workflow '${runId}' is not running or queued and cannot be steered.`);
-	if (typeof status.completionOwnerId !== "string" || !status.completionOwnerId.trim()
-		|| status.completionOwnerId === (state.completionOwnerId ?? currentCompletionOwnerId())
-		|| [...state.foregroundControls.values()].some((control) => control.parentWorkflowRunId === runId)) {
-		return managementError(`Workflow '${runId}' has no live foreground child and is not a recorded foreign workflow.`);
-	}
-	if (input.index !== undefined) {
-		const step = status.steps?.[input.index];
-		if (!Number.isInteger(input.index) || input.index < 0 || !step) return managementError(`Workflow '${runId}' index ${input.index} is out of range or invalid.`);
-		if (step.status !== "running" && step.status !== "pending") return managementError(`Workflow '${runId}' child ${input.index} is ${step.status} and cannot be steered.`);
-		if (typeof step.workflowKey !== "string" || !step.workflowKey.trim()) return managementError(`Workflow '${runId}' child ${input.index} has no projected workflow key.`);
-	}
-	const requestId = randomUUID();
-	try {
-		requestAsyncSteer(asyncDir, { id: requestId, message: input.message, mode: input.mode, ...(input.index !== undefined ? { targetIndex: input.index } : {}), source: "steer-action" });
-	} catch (error) {
-		return managementError(`Failed to queue steering for workflow ${runId}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-	// Only the owner writes the ledger. No acknowledgment leaves an honest, unaddressed queued receipt.
-	const steering = await waitForSteeringAction({ asyncDir, sourceRunId: runId, requestId, timeoutMs: input.ackTimeoutMs ?? 3_000, signal: input.signal })
-		?? { requestId, state: "pending" as const, deliveryStatus: "queued" as const, sourceRunId: runId, targets: input.index === undefined ? [] : [{ index: input.index, state: "pending" as const }] };
-	const failed = steering.state === "failed" || steering.state === "partial";
-	return {
-		content: [{ type: "text", text: steeringReceipt(input.message, `Steering ${failed ? steering.state : steering.deliveryStatus === "delivered" ? "delivered" : "queued"} for workflow ${runId} (request ${requestId}).`) }],
-		...(failed ? { isError: true } : {}),
-		details: { mode: "management", results: [], steering },
-	};
-}
-
-/**
- * Steer a live workflow-owned foreground child through its in-process session.
- * `steer` (and `auto`) interrupt the child at its next safe point; `follow_up`
- * queues the message until the current run settles.
- */
-export async function steerWorkflowForegroundTarget(input: {
-	target: WorkflowForegroundSteeringTarget;
-	message: string;
-	mode?: SteerDeliveryMode;
-	index?: number;
-}): Promise<AgentToolResult<Details>> {
-	const { control, sourceRunId } = input.target;
-	const activeIndexes = [...(control.activeChildren?.keys() ?? [])].sort((left, right) => left - right);
-	const index = input.index ?? (activeIndexes.length === 1 ? activeIndexes[0] : undefined);
-	if (index === undefined) {
-		return managementError(activeIndexes.length === 0
-			? `Foreground run '${control.runId}' has no live child session.`
-			: `Foreground run '${control.runId}' has ${activeIndexes.length} live child sessions; provide index.`);
-	}
-	const child = control.activeChildren?.get(index);
-	if (!child) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
-	if (!child.steer) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
-
-	const message = input.message.trim();
-	const requestId = randomUUID();
-
-	const outcome = await child.steer({ message, ...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}) });
-	const target = outcome.state === "delivered"
-		? { index, state: "delivered" as const, deliveredAt: Date.now() }
-		: outcome.state === "queued"
-			? { index, state: "queued" as const }
-			: { index, state: "failed" as const, reason: outcome.reason };
-	const steering = {
-		requestId,
-		state: outcome.state === "delivered" ? "delivered" as const : outcome.state === "failed" ? "failed" as const : "pending" as const,
-		deliveryStatus: outcome.state === "delivered" ? "delivered" as const : "queued" as const,
-		sourceRunId,
-		targets: [target],
-	};
-	if (outcome.state === "delivered") {
-		return { content: [{ type: "text", text: steeringReceipt(message, `Steering delivered for foreground run ${control.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering } };
-	}
-	if (outcome.state === "queued") {
-		return { content: [{ type: "text", text: steeringReceipt(message, `Steering queued for foreground run ${control.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering } };
-	}
-	return { content: [{ type: "text", text: steeringReceipt(message, `Steering failed for foreground run ${control.runId} (request ${requestId}): ${outcome.reason ?? "unknown error"}`) }], isError: true, details: { mode: "management", results: [], steering } };
-}

package/src/runs/shared/abort-recovery.ts

@@ -1,119 +0,0 @@
-import type { Message } from "@earendil-works/pi-ai";
-
-export const ABORT_RECOVERY_PROMPT = "The prior run ended from a provider/transport abort after useful progress. Continue from the current files and transcript. Do not restart. Fix any validation failure or write the required report. Finish with final output.";
-
-export type AbortRecoveryPlan =
-	| { action: "resume"; prompt: typeof ABORT_RECOVERY_PROMPT }
-	| { action: "settle"; reason: string; diagnostic?: string };
-
-const PROVIDER_ABORT_PATTERN = /(?:provider|transport|connection|stream|socket|request).*(?:abort|closed|reset|ended|terminated|error|fail)|(?:abort|closed|reset|ended|terminated|error|fail).*(?:provider|transport|connection|stream|socket|request)/i;
-const ABORT_ERROR_PATTERN = /\b(?:operation|request|response|stream|connection|transport|provider)?\s*(?:was\s+)?aborted\b/i;
-const TOOL_FAILURE_PREFIX = /^[\w.:@/-]+ failed (?:(?:\(exit \d+\):)|(?:with exit code \d+))(?:\s|$)/i;
-
-function isProviderAbortError(error: string): boolean {
-	return !TOOL_FAILURE_PREFIX.test(error.trim()) && (PROVIDER_ABORT_PATTERN.test(error) || ABORT_ERROR_PATTERN.test(error));
-}
-
-function record(value: unknown): Record<string, unknown> | undefined {
-	return value !== null && typeof value === "object" && !Array.isArray(value)
-		? value as Record<string, unknown>
-		: undefined;
-}
-
-function contentParts(message: Record<string, unknown>): unknown[] {
-	return Array.isArray(message.content) ? message.content : [];
-}
-
-function terminalAssistant(messages: readonly Message[]): { message?: Record<string, unknown>; index: number } {
-	for (let index = messages.length - 1; index >= 0; index--) {
-		const message = record(messages[index]);
-		if (message?.role === "assistant") return { message, index };
-	}
-	return { index: messages.length };
-}
-
-function zeroOutputUsage(message: Record<string, unknown>): boolean {
-	const usage = record(message.usage);
-	return usage !== undefined && (usage.output ?? usage.outputTokens ?? 0) === 0;
-}
-
-function hasUsefulProgress(messages: readonly Message[], terminalIndex: number): boolean {
-	for (let index = 0; index < terminalIndex; index++) {
-		const message = record(messages[index]);
-		if (!message) continue;
-		if (message.role === "assistant" && contentParts(message).length > 0) return true;
-		if (message.role === "toolResult" && message.isError !== true) return true;
-	}
-	return false;
-}
-
-function hasUnresolvedToolCall(messages: readonly Message[]): boolean {
-	const pending = new Set<string>();
-	for (const rawMessage of messages) {
-		const message = record(rawMessage);
-		if (!message) continue;
-		if (message.role === "assistant") {
-			for (const rawPart of contentParts(message)) {
-				const part = record(rawPart);
-				if (part?.type === "toolCall" && typeof part.id === "string" && part.id) pending.add(part.id);
-			}
-		} else if (message.role === "toolResult" && typeof message.toolCallId === "string") {
-			pending.delete(message.toolCallId);
-		}
-	}
-	return pending.size > 0;
-}
-
-export function planAbortRecovery(input: {
-	messages: readonly Message[];
-	error?: string;
-	processSignal?: string | null;
-	sessionAvailable: boolean;
-	alreadyResumed: boolean;
-	stopped?: boolean;
-	interrupted?: boolean;
-	timedOut?: boolean;
-	toolBudgetExhausted?: boolean;
-	usageBudgetExhausted?: boolean;
-	structuredOutputFailed?: boolean;
-	acceptanceFailed?: boolean;
-	currentTool?: string;
-	afterCompactionSettlement?: boolean;
-}): AbortRecoveryPlan {
-	const terminal = terminalAssistant(input.messages);
-	const message = terminal.message;
-	const terminalError = typeof message?.errorMessage === "string" ? message.errorMessage : undefined;
-	const emptyZeroUsageTerminal = message !== undefined
-		&& contentParts(message).length === 0
-		&& zeroOutputUsage(message);
-	const terminalAssistantAbort = message?.stopReason === "aborted"
-		|| (message?.stopReason === "error" && terminalError !== undefined && isProviderAbortError(terminalError));
-	const abortCandidate = emptyZeroUsageTerminal && terminalAssistantAbort;
-	const compactionAbortCandidate = input.afterCompactionSettlement === true && abortCandidate;
-	const settle = (reason: string): AbortRecoveryPlan => ({
-		action: "settle",
-		reason,
-		...(compactionAbortCandidate
-			? { diagnostic: `Compaction-induced child abort could not be resumed safely: ${reason}.` }
-			: {}),
-	});
-
-	if (input.alreadyResumed) return settle("resume already attempted");
-	if (!input.sessionAvailable) return settle("retained session unavailable");
-	if (input.stopped || input.interrupted) return settle("explicit stop or interrupt");
-	// An external-job runner reports a process signal when its terminal drain
-	// ends a child left open by a compaction abort. The compaction + settlement
-	// markers make that cleanup signal non-authoritative; explicit stop/interrupt still wins.
-	if (input.processSignal && !compactionAbortCandidate) return settle("process terminated by signal");
-	if (input.timedOut) return settle("elapsed timeout");
-	if (input.toolBudgetExhausted || input.usageBudgetExhausted) return settle("budget exhausted");
-	if (input.structuredOutputFailed) return settle("structured output failure");
-	if (input.acceptanceFailed) return settle("acceptance failure");
-	if (input.currentTool) return settle(`active tool '${input.currentTool.slice(0, 128)}' remains in flight`);
-	if (hasUnresolvedToolCall(input.messages)) return settle("unresolved tool call remains in transcript");
-	if (!input.afterCompactionSettlement) return settle("compaction settlement not verified");
-	if (!abortCandidate) return settle("terminal assistant abort evidence not verified");
-	const progressLimit = emptyZeroUsageTerminal ? terminal.index : input.messages.length;
-	if (!hasUsefulProgress(input.messages, progressLimit)) return settle("no useful prior progress");
-	return { action: "resume", prompt: ABORT_RECOVERY_PROMPT };
-}