pi-subagents 0.63.0 → 0.65.0

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

@@ -1,20 +1,10 @@
 import { randomUUID } from "node:crypto";
-import * as fs from "node:fs";
 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 } from "../background/steering.ts";
-import {
-	consumeSteerAckFromDir,
-	readSteerCapability,
-	steerAcksDir,
-	steerCapabilityPath,
-	stepSteerInboxDir,
-	writeSteerRequestToExistingDir,
-	type SteerDeliveryMode,
-	type SteerRequest,
-} from "../background/control-channel.ts";
+import type { SteerDeliveryMode } from "../background/control-channel.ts";
 
 export interface WorkflowForegroundSteeringTarget {
 	control: ForegroundRunControl;
@@ -40,7 +30,6 @@ function activeWorkflowError(state: SubagentState, workflowRunId: string, asyncD
 function controlIsLiveInWorkflow(control: ForegroundRunControl, workflowRunId: string, sessionId: string): boolean {
 	return control.parentWorkflowRunId === workflowRunId
 		&& control.sessionId === sessionId
-		&& Boolean(control.workflowSteeringDir)
 		&& (control.activeChildren?.size ?? 0) > 0;
 }
 
@@ -77,17 +66,18 @@ function managementError(message: string): AgentToolResult<Details> {
 	return { content: [{ type: "text", text: message }], isError: true, details: { mode: "management", results: [] } };
 }
 
+/**
+ * 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;
-	signal?: AbortSignal;
-	ackTimeoutMs?: number;
 }): Promise<AgentToolResult<Details>> {
 	const { control, sourceRunId } = input.target;
-	const routeDir = control.workflowSteeringDir;
-	if (!routeDir || !fs.existsSync(routeDir)) return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
 	const activeIndexes = [...(control.activeChildren?.keys() ?? [])].sort((left, right) => left - right);
 	const index = input.index ?? (activeIndexes.length === 1 ? activeIndexes[0] : undefined);
 	if (index === undefined) {
@@ -95,94 +85,30 @@ export async function steerWorkflowForegroundTarget(input: {
 			? `Foreground run '${control.runId}' has no live child session.`
 			: `Foreground run '${control.runId}' has ${activeIndexes.length} live child sessions; provide index.`);
 	}
-	if (!activeIndexes.includes(index)) return managementError(`Foreground run '${control.runId}' child ${index} is not live.`);
-	const capability = readSteerCapability(routeDir, index);
-	if (capability?.supported === false) return managementError(`Foreground run '${control.runId}' child ${index} does not support steering.`);
+	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 request: SteerRequest = {
-		type: "steer",
-		id: randomUUID(),
-		ts: Date.now(),
-		message: input.message.trim(),
-		...(input.mode && input.mode !== "steer" ? { mode: input.mode } : {}),
-		targetIndex: index,
-		source: "steer-action",
-	};
-	try {
-		writeSteerRequestToExistingDir(stepSteerInboxDir(routeDir, index), request);
-	} catch (error) {
-		if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") {
-			return managementError(`Foreground run '${control.runId}' has no live workflow steering route.`);
-		}
-		return managementError(`Failed to queue steering for foreground run ${control.runId}: ${error instanceof Error ? error.message : String(error)}`);
-	}
-
-	const deadline = Date.now() + (input.ackTimeoutMs ?? 3_000);
-	let ack;
-	let routeRemoved = false;
-	while (Date.now() <= deadline) {
-		ack = consumeSteerAckFromDir(steerAcksDir(routeDir, index), request.id);
-		if (ack || input.signal?.aborted) break;
-		if (!fs.existsSync(routeDir)) {
-			routeRemoved = true;
-			break;
-		}
-		await new Promise<void>((resolve) => setTimeout(resolve, Math.min(50, Math.max(1, deadline - Date.now()))));
-	}
-	if (routeRemoved || (!ack && !input.signal?.aborted && !fs.existsSync(routeDir))) {
-		return managementError(`Foreground run '${control.runId}' has no live child session.`);
-	}
-	const target = ack?.state === "delivered"
-		? { index, state: "delivered" as const, deliveredAt: ack.ts }
-		: ack?.state === "queued"
+	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 }
-			: ack?.state === "failed"
-				? { index, state: "failed" as const, reason: ack.message }
-				: { index, state: "pending" as const };
+			: { index, state: "failed" as const, reason: outcome.reason };
 	const steering = {
-		requestId: request.id,
-		state: ack?.state === "delivered" ? "delivered" as const : ack?.state === "failed" ? "failed" as const : "pending" as const,
-		deliveryStatus: ack?.state === "delivered" ? "delivered" as const : "queued" as const,
+		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 (input.signal?.aborted) {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering pending for foreground run ${control.runId} (request ${request.id}); caller aborted before acknowledgment.`) }], details: { mode: "management", results: [], steering } };
-	}
-	if (ack?.state === "delivered") {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering delivered for foreground run ${control.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering } };
-	}
-	if (ack?.state === "queued") {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering queued for foreground run ${control.runId} (request ${request.id}).`) }], details: { mode: "management", results: [], steering } };
+	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 (ack?.state === "failed") {
-		return { content: [{ type: "text", text: steeringReceipt(request.message, `Steering failed for foreground run ${control.runId} (request ${request.id}): ${ack.message}`) }], isError: true, 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(request.message, `Steering pending for foreground run ${control.runId} (request ${request.id}); no acknowledgment was received.`) }], details: { mode: "management", results: [], steering } };
-}
-
-export function workflowForegroundSteeringDir(asyncDirRoot: string, workflowRunId: string, childRunId: string): string {
-	return path.join(asyncDirRoot, workflowRunId, "control", "workflow-foreground", childRunId);
-}
-
-export function removeWorkflowForegroundSteeringRoute(control: ForegroundRunControl): void {
-	if (!control.workflowSteeringDir) return;
-	try {
-		fs.rmSync(control.workflowSteeringDir, { recursive: true, force: true });
-	} catch (error) {
-		console.warn(`[pi-subagents] Failed to remove workflow foreground steering route '${control.workflowSteeringDir}': ${error instanceof Error ? error.message : String(error)}`);
-	}
-}
-
-export function workflowForegroundSteeringLaunchOptions(control: ForegroundRunControl | undefined, index: number): Pick<import("../../shared/types.ts").RunSyncOptions, "steerInboxDir" | "steerCapabilityPath" | "steerAckDir"> {
-	if (!control?.workflowSteeringDir) return {};
-	const steerInboxDir = stepSteerInboxDir(control.workflowSteeringDir, index);
-	const steerAckDir = steerAcksDir(control.workflowSteeringDir, index);
-	fs.mkdirSync(steerInboxDir, { recursive: true });
-	fs.mkdirSync(steerAckDir, { recursive: true });
-	return {
-		steerInboxDir,
-		steerCapabilityPath: steerCapabilityPath(control.workflowSteeringDir, index),
-		steerAckDir,
-	};
+	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

@@ -101,9 +101,9 @@ export function planAbortRecovery(input: {
 	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");
-	// A compaction abort can leave the child process open until the runner's
-	// terminal drain sends SIGTERM. The compaction + settlement markers make
-	// that cleanup signal non-authoritative; explicit stop/interrupt still wins.
+	// 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");

package/src/runs/shared/acceptance.ts

@@ -21,7 +21,9 @@ import type {
 	ResolvedAcceptanceGate,
 	SingleResult,
 	SubagentRunMode,
+	ChildWatchdogProgress,
 } from "../../shared/types.ts";
+import { unresolvedChildWatchdogBlockers } from "../../watchdog/child-status.ts";
 import { isAgentContractV1 } from "./agent-contract.ts";
 import { classifyTaskMutationIntent, stripSeverityCompounds, taskMayMutate } from "./task-intent.ts";
 
@@ -1360,6 +1362,7 @@ export async function evaluateAcceptance(input: {
 	reportOptional?: boolean;
 	artifactsDir?: string;
 	runId?: string;
+	watchdog?: ChildWatchdogProgress;
 }): Promise<AcceptanceLedger> {
 	const acceptance = input.acceptance;
 	const initialStatus = acceptance.level === "none" ? "not-required" : "claimed";
@@ -1375,6 +1378,13 @@ export async function evaluateAcceptance(input: {
 	};
 	if (acceptance.level === "none") return ledger;
 
+	if (input.watchdog) {
+		const unresolved = unresolvedChildWatchdogBlockers(input.watchdog);
+		ledger.runtimeChecks.push(unresolved.length
+			? { id: "watchdog-blocker", status: "failed", message: `Unresolved watchdog blocker: ${unresolved[0]!.summary}` }
+			: { id: "watchdog-blocker", status: "passed", message: "No unresolved watchdog blockers." });
+	}
+
 	const parsed: AcceptanceReportParseResult = input.reportError
 		? { error: input.reportError }
 		: input.report !== undefined

package/src/runs/shared/async-status-projection.ts

@@ -2,6 +2,7 @@ import { sanitizeDisplayText, truncateDisplayText } from "../../shared/display-t
 import { formatModelThinking } from "../../shared/formatters.ts";
 import type { AsyncJobState, AsyncJobStep, HostStepFreshnessV1, HostStepMonitorKind, HostStepNodeV1, HostStepState, HostStepVerdict, NestedRunSummary, NestedStepSummary, SubagentRunMode, WorkflowGraphSnapshot, WorkflowPreflightLaneV1, WorkflowPreflightV1 } from "../../shared/types.ts";
 import { HOST_STEP_MAX_COUNT, HOST_STEP_MAX_DETAIL_CHARS, HOST_STEP_MAX_LABEL_CHARS, HOST_STEP_MAX_PROVIDER_CHARS, HOST_STEP_MAX_REASON_CHARS, HOST_STEP_MAX_REF_CHARS, HOST_STEP_MAX_ROLE_CHARS, HOST_STEP_MAX_TARGET_CHARS, hostStepReportName, parseHostStepNode, validHostStepNodes } from "./host-step-status.ts";
+import { workflowPreflightLaneForRuntimeKey } from "../../workflows/workflow-preflight.ts";
 import { workflowGraphStageNodes } from "./workflow-graph.ts";
 
 export const ASYNC_STATUS_SNAPSHOT_KIND = "pi-subagents.async-status-snapshot";
@@ -472,7 +473,7 @@ function projectWorkflowGraphRow(node: WorkflowGraphSnapshot["nodes"][number], p
 	};
 }
 
-/** Project loaded workflow child facts plus stored preflight hints into compact rows. */
+/** Project authoritative workflow facts into compact rows, annotated by preflight hints. */
 export function projectAsyncWorkflowRows(
 	steps: readonly AsyncJobStep[] | undefined,
 	hostStepsOrPreflight?: readonly HostStepNodeV1[] | WorkflowGraphSnapshot | WorkflowPreflightV1,
@@ -482,7 +483,8 @@ export function projectAsyncWorkflowRows(
 	const graph = isWorkflowGraph(hostStepsOrPreflight) ? hostStepsOrPreflight : undefined;
 	const hostSteps = isWorkflowPreflight(hostStepsOrPreflight) || graph ? undefined : hostStepsOrPreflight;
 	const loaded = steps ?? [];
-	const declared = new Map<string, WorkflowPreflightLaneV1>();
+	const preflightForKey = (key: string, groupKeys: readonly (string | undefined)[] = []): WorkflowPreflightLaneV1 | undefined =>
+		workflowPreflightLaneForRuntimeKey(preflight, key, groupKeys);
 	if (graph) {
 		const loadedIndexesByKey = new Map<string, number[]>();
 		for (const [index, step] of loaded.entries()) {
@@ -493,7 +495,6 @@ export function projectAsyncWorkflowRows(
 		}
 		const consumed = new Set<number>();
 		const childRows: AsyncStatusWorkflowRow[] = [];
-		for (const lane of preflight?.lanes ?? []) declared.set(lane.key, lane);
 		const graphStages = workflowGraphStageNodes(graph);
 		const graphKeys = new Set(graphStages.map((node) => node.id));
 		const graphPhaseByNodeId = new Map<string, string>();
@@ -502,60 +503,27 @@ export function projectAsyncWorkflowRows(
 				if (graphKeys.has(nodeId) && !graphPhaseByNodeId.has(nodeId)) graphPhaseByNodeId.set(nodeId, phase.title);
 			}
 		}
-		const graphLaneKeys = new Set(graphPhaseByNodeId.values());
-		const preflightForNode = (node: WorkflowGraphSnapshot["nodes"][number]): WorkflowPreflightLaneV1 | undefined => {
-			const phaseTitle = graphPhaseByNodeId.get(node.id);
-			return declared.get(node.id) ?? (node.phase ? declared.get(node.phase) : undefined) ?? (phaseTitle ? declared.get(phaseTitle) : undefined);
-		};
 		for (const node of graphStages) {
+			const lane = preflightForKey(node.id, [node.phase, graphPhaseByNodeId.get(node.id)]);
 			const indexes = (loadedIndexesByKey.get(node.id) ?? []).filter((index) => !consumed.has(index));
-			if (indexes.length > 0) {
-				for (const index of indexes) {
-					consumed.add(index);
-					childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, preflightForNode(node)));
-				}
-			} else {
-				childRows.push(projectWorkflowGraphRow(node, preflightForNode(node)));
-			}
-		}
-		for (const lane of preflight?.lanes ?? []) {
-			if (graphKeys.has(lane.key) || graphLaneKeys.has(lane.key)) continue;
-			const indexes = (loadedIndexesByKey.get(lane.key) ?? []).filter((index) => !consumed.has(index));
 			if (indexes.length > 0) {
 				for (const index of indexes) {
 					consumed.add(index);
 					childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, lane));
 				}
 			} else {
-				childRows.push({ name: lane.key, state: "planned", preflight: lane });
+				childRows.push(projectWorkflowGraphRow(node, lane));
 			}
 		}
 		for (const [index, step] of loaded.entries()) {
-			if (!consumed.has(index)) childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? declared.get(step.workflowKey) : undefined));
+			if (!consumed.has(index)) childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? preflightForKey(step.workflowKey, [step.phase]) : undefined));
 		}
 		return [...childRows, ...validHostStepList(graph).map(hostStepRow)];
 	}
-	const loadedIndexByKey = new Map<string, number>();
-	for (const [index, step] of loaded.entries()) {
-		if (step.workflowKey !== undefined && !loadedIndexByKey.has(step.workflowKey)) loadedIndexByKey.set(step.workflowKey, index);
-	}
-	const consumed = new Set<number>();
-	const childRows: AsyncStatusWorkflowRow[] = [];
-	for (const lane of preflight?.lanes ?? []) {
-		declared.set(lane.key, lane);
-		const index = loadedIndexByKey.get(lane.key);
-		if (index === undefined) {
-			childRows.push({ name: lane.key, state: "planned", preflight: lane });
-			continue;
-		}
-		consumed.add(index);
-		childRows.push(projectLoadedWorkflowRow(loaded[index]!, index, lane));
-	}
-	for (const [index, step] of loaded.entries()) {
-		if (consumed.has(index)) continue;
-		childRows.push(projectLoadedWorkflowRow(step, index, step.workflowKey ? declared.get(step.workflowKey) : undefined));
-	}
-	return [...childRows, ...validHostStepList(hostSteps).map(hostStepRow)];
+	return [
+		...loaded.map((step, index) => projectLoadedWorkflowRow(step, index, step.workflowKey ? preflightForKey(step.workflowKey, [step.phase]) : undefined)),
+		...validHostStepList(hostSteps).map(hostStepRow),
+	];
 }
 
 function projectLoadedWorkflowRow(step: AsyncJobStep, index: number, preflight?: WorkflowPreflightLaneV1): AsyncStatusWorkflowRow {

package/src/runs/shared/capability-ceiling.ts

@@ -2,7 +2,6 @@ import { Buffer } from "node:buffer";
 
 export const SUBAGENT_CAPABILITY_CEILING_VERSION = 1 as const;
 export const SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY = "pi-subagents.capability-ceiling.v1";
-export const SUBAGENT_CAPABILITY_CEILING_ENV = "PI_SUBAGENT_CAPABILITY_CEILING_V1";
 
 export type SubagentCapabilityCeiling =
 	| { allowedTools: readonly string[]; allowedAgents?: readonly string[]; denyExtensions?: boolean }
@@ -167,7 +166,7 @@ export function resolveSubagentCapabilityCeiling(sessionId: string | undefined,
 }
 
 export function resolveCurrentSubagentCapabilityCeiling(sessionId: string | undefined): ResolvedSubagentCapabilityCeiling | undefined {
-	return resolveSubagentCapabilityCeiling(sessionId, decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]));
+	return resolveSubagentCapabilityCeiling(sessionId, undefined);
 }
 
 export function isAgentAllowedByCapabilityCeiling(agentName: string, ceiling: ResolvedSubagentCapabilityCeiling | undefined): boolean {

package/src/runs/shared/child-hooks.ts

@@ -0,0 +1,25 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerFanoutChildSubagentExtension from "../../extension/fanout-child.ts";
+import registerSubagentFastModeExtension from "./fast-mode-extension.ts";
+import registerSubagentPromptRuntime from "./subagent-prompt-runtime.ts";
+import type { ChildRuntimeConfig } from "./child-runtime-config.ts";
+
+/** Inline extension shape accepted by pi's resource loader (`extensionFactories`). */
+export interface ChildHookExtension {
+	name: string;
+	factory: (pi: ExtensionAPI) => void;
+}
+
+/**
+ * The child-side hooks pi-subagents installs in every child, keyed off the
+ * launch config. The registrations live in `subagent-prompt-runtime.ts`,
+ * `fast-mode-extension.ts`, and `fanout-child.ts`.
+ */
+export function createChildHooks(config: ChildRuntimeConfig): ChildHookExtension[] {
+	const hooks: ChildHookExtension[] = [
+		{ name: "pi-subagents:prompt-runtime", factory: (pi) => registerSubagentPromptRuntime(pi, config) },
+	];
+	if (config.fast) hooks.push({ name: "pi-subagents:fast-mode", factory: (pi) => registerSubagentFastModeExtension(pi) });
+	if (config.fanoutChild) hooks.push({ name: "pi-subagents:fanout-child", factory: (pi) => registerFanoutChildSubagentExtension(pi, config) });
+	return hooks;
+}

package/src/runs/shared/child-identity.ts

@@ -14,11 +14,11 @@ export type AsyncStatusChildResolution =
 	| { ok: false; code: "not_found" | "ambiguous"; message: string };
 
 export function asyncStatusChildIdentity(step: AsyncStatusStep, index: number): string {
-	return step.workflowKey ?? step.runId ?? `step:${index}`;
+	return asyncStatusChildIdentityCandidates(step, index)[0]!;
 }
 
 export function asyncStatusChildIdentityCandidates(step: AsyncStatusStep, index: number): string[] {
-	return [...new Set([step.workflowKey, step.runId, `step:${index}`].filter((value): value is string => typeof value === "string" && value.length > 0))];
+	return [...new Set([step.childId, step.workflowKey, step.runId, `step:${index}`].filter((value): value is string => typeof value === "string" && value.length > 0))];
 }
 
 export function resolveAsyncStatusChild(
@@ -49,3 +49,14 @@ export function resolveAsyncStatusChild(
 export function isStoppableAsyncStatusStep(step: AsyncStatusStep): boolean {
 	return step.status === "pending" || step.status === "running";
 }
+
+export function stopStoppableAsyncStatusChildren(
+	status: Pick<AsyncStatus, "steps">,
+	stopChild: ((childId: string, message?: string) => boolean) | undefined,
+	message: string,
+): void {
+	if (!stopChild) return;
+	for (const [index, step] of (status.steps ?? []).entries()) {
+		if (isStoppableAsyncStatusStep(step)) stopChild(asyncStatusChildIdentity(step, index), message);
+	}
+}