pi-subagents 0.53.0 → 0.55.0

package/src/runs/background/control-channel.ts

@@ -55,6 +55,8 @@ export interface StopRequest {
 	ts?: number;
 	source?: string;
 	reason?: string;
+	targetIndex?: number;
+	childId?: string;
 }
 
 export type SteerDeliveryMode = "steer" | "follow_up" | "auto";
@@ -92,6 +94,7 @@ export interface SteerAck {
 }
 
 const STEER_REQUESTS_DIR = "steer-requests";
+const STOP_REQUESTS_DIR = "stop-requests";
 const REVIVAL_BRIEFS_DIR = "revival-briefs";
 export const MAX_STEER_QUEUE_SIZE = 20;
 const STEER_TARGETS_DIR = "steer-targets";
@@ -121,6 +124,11 @@ export function stopRequestPath(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), "stop.json");
 }
 
+/** Directory of parent-to-runner stop requests. */
+export function stopRequestsDir(asyncDir: string): string {
+	return path.join(controlInboxDir(asyncDir), STOP_REQUESTS_DIR);
+}
+
 /** Directory of parent-to-runner steering requests. */
 export function steerRequestsDir(asyncDir: string): string {
 	return path.join(controlInboxDir(asyncDir), STEER_REQUESTS_DIR);
@@ -164,13 +172,24 @@ export function steerAckPathFromDir(dir: string, requestId: string): string {
 }
 
 function assertChildIndex(index: number): void {
-	if (!Number.isInteger(index) || index < 0 || index > 1_000_000) throw new Error("steer child index must be a non-negative integer.");
+	if (!Number.isInteger(index) || index < 0 || index > 1_000_000) throw new Error("child index must be a non-negative integer.");
+}
+
+function validStopChildId(childId: unknown): childId is string {
+	return typeof childId === "string"
+		&& Boolean(childId.trim())
+		&& childId.length <= 256
+		&& !/[\r\n]/.test(childId);
 }
 
 function steerRequestFileName(request: SteerRequest): string {
 	return `${String(request.ts).padStart(13, "0")}-${Buffer.from(request.id).toString("base64url")}.json`;
 }
 
+function stopRequestFileName(request: StopRequest): string {
+	return `${String(request.ts ?? 0).padStart(13, "0")}-${randomUUID()}.json`;
+}
+
 function validSteerRequest(request: Partial<SteerRequest>): request is SteerRequest {
 	return request.type === "steer"
 		&& typeof request.id === "string"
@@ -279,8 +298,12 @@ export function requestAsyncStop(
 	payload: Omit<StopRequest, "type"> = {},
 	deps: { now?: () => number } = {},
 ): string {
-	const requestPath = stopRequestPath(asyncDir);
+	if (payload.targetIndex !== undefined) assertChildIndex(payload.targetIndex);
+	if (payload.childId !== undefined && !validStopChildId(payload.childId)) {
+		throw new Error("stop childId must be a non-empty string without newlines and at most 256 characters.");
+	}
 	const request: StopRequest = { ...payload, ts: payload.ts ?? deps.now?.() ?? Date.now(), type: "stop" };
+	const requestPath = path.join(stopRequestsDir(asyncDir), stopRequestFileName(request));
 	writeAtomicJson(requestPath, request);
 	return requestPath;
 }
@@ -521,16 +544,78 @@ export function consumeTimeoutRequest(
 
 export function consumeStopRequest(
 	asyncDir: string,
-	fsImpl: Pick<typeof fs, "existsSync" | "rmSync"> = fs,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs,
 ): boolean {
-	const requestPath = stopRequestPath(asyncDir);
-	if (!fsImpl.existsSync(requestPath)) return false;
+	return consumeStopRequestPayload(asyncDir, fsImpl) !== undefined;
+}
+
+function parseStopRequest(raw: unknown): StopRequest | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const parsed = raw as Partial<StopRequest>;
+	if (parsed.type !== "stop") return undefined;
+	if (Object.hasOwn(parsed, "targetIndex") && !(Number.isInteger(parsed.targetIndex) && parsed.targetIndex! >= 0 && parsed.targetIndex! <= 1_000_000)) return undefined;
+	if (Object.hasOwn(parsed, "childId") && !validStopChildId(parsed.childId)) return undefined;
+	return {
+		type: "stop",
+		...(typeof parsed.ts === "number" ? { ts: parsed.ts } : {}),
+		...(typeof parsed.source === "string" ? { source: parsed.source } : {}),
+		...(typeof parsed.reason === "string" ? { reason: parsed.reason } : {}),
+		...(parsed.targetIndex !== undefined ? { targetIndex: parsed.targetIndex } : {}),
+		...(validStopChildId(parsed.childId) ? { childId: parsed.childId } : {}),
+	};
+}
+
+function consumeStopRequestFile(
+	requestPath: string,
+	fsImpl: Pick<typeof fs, "rmSync" | "readFileSync">,
+): StopRequest | undefined {
+	let request: StopRequest | undefined;
+	try {
+		request = parseStopRequest(JSON.parse(fsImpl.readFileSync(requestPath, "utf-8")));
+	} catch {
+		request = undefined;
+	}
 	try {
 		fsImpl.rmSync(requestPath, { force: true, recursive: true });
 	} catch {
-		// Already removed by a concurrent check — still counts as consumed.
+		// Already removed by a concurrent check — do not execute it twice.
+		return undefined;
 	}
-	return true;
+	return request;
+}
+
+export function consumeStopRequestPayloads(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs,
+): StopRequest[] {
+	const dir = stopRequestsDir(asyncDir);
+	const requests: StopRequest[] = [];
+	if (fsImpl.existsSync(dir)) {
+		let entries: string[];
+		try {
+			entries = fsImpl.readdirSync(dir).filter((name) => name.endsWith(".json")).sort();
+		} catch {
+			entries = [];
+		}
+		for (const entry of entries) {
+			const request = consumeStopRequestFile(path.join(dir, entry), fsImpl);
+			if (request) requests.push(request);
+		}
+	}
+
+	const legacyPath = stopRequestPath(asyncDir);
+	if (fsImpl.existsSync(legacyPath)) {
+		const request = consumeStopRequestFile(legacyPath, fsImpl);
+		if (request) requests.push(request);
+	}
+	return requests.sort((left, right) => (left.ts ?? 0) - (right.ts ?? 0));
+}
+
+export function consumeStopRequestPayload(
+	asyncDir: string,
+	fsImpl: Pick<typeof fs, "existsSync" | "rmSync" | "readdirSync" | "readFileSync"> = fs,
+): StopRequest | undefined {
+	return consumeStopRequestPayloads(asyncDir, fsImpl)[0];
 }
 
 /** Parent side: write the authoritative portable interrupt request. */
@@ -560,8 +645,10 @@ export function deliverStopRequest(input: {
 	signal?: NodeJS.Signals;
 	now?: () => number;
 	source?: string;
+	targetIndex?: number;
+	childId?: string;
 }): void {
-	requestAsyncStop(input.asyncDir, input.source ? { source: input.source } : {}, { now: input.now });
+	requestAsyncStop(input.asyncDir, { ...(input.source ? { source: input.source } : {}), ...(input.targetIndex !== undefined ? { targetIndex: input.targetIndex } : {}), ...(input.childId ? { childId: input.childId } : {}) }, { now: input.now });
 }
 
 /**
@@ -575,7 +662,7 @@ export function watchAsyncControlInbox(
 	opts: {
 		onInterrupt: () => void;
 		onTimeout?: () => void;
-		onStop?: () => void;
+		onStop?: (request: StopRequest) => void;
 		onSteer?: (request: SteerRequest) => void;
 		onSteerCapability?: (capability: SteerCapability) => void;
 		onSteerAck?: (ack: SteerAck) => void;
@@ -599,7 +686,7 @@ export function watchAsyncControlInbox(
 	const check = (): void => {
 		if (disposed) return;
 		try {
-			if (consumeStopRequest(asyncDir, fsImpl)) opts.onStop?.();
+			for (const stopRequest of consumeStopRequestPayloads(asyncDir, fsImpl)) opts.onStop?.(stopRequest);
 			if (consumeTimeoutRequest(asyncDir, fsImpl)) opts.onTimeout?.();
 			if (consumeInterruptRequest(asyncDir, fsImpl)) opts.onInterrupt();
 			for (const request of consumeSteerRequests(asyncDir, fsImpl)) opts.onSteer?.(request);
@@ -651,6 +738,7 @@ export function watchAsyncControlInbox(
 	try {
 		if (shouldUseNativeFsWatch("runner-control-inbox", opts.platform)) {
 			watchDir(dir);
+			watchDir(stopRequestsDir(asyncDir), true);
 			watchDir(steerRequestsDir(asyncDir), true);
 			watchDir(steerCapabilitiesDir(asyncDir), true);
 			watchDir(path.join(dir, STEER_ACKS_DIR), true);

package/src/runs/background/notify.ts

@@ -24,6 +24,9 @@ export interface SubagentNotifyDetails {
 	taskInfo?: string;
 	resultPreview: string;
 	durationMs?: number;
+	workflowRunId?: string;
+	childRuns?: Array<{ runId: string; workflowKey?: string; agent?: string; status?: string }>;
+	reconciledFromDetachedChild?: string;
 	sessionLabel?: string;
 	sessionValue?: string;
 	handoffPath?: string;
@@ -40,12 +43,18 @@ export interface CompletionNotification {
 	summary?: string;
 	exitCode?: number;
 	state?: string;
+	mode?: string;
+	runId?: string | null;
+	reconciledFromDetachedChild?: string;
 	processSignal?: string | null;
 	interrupted?: boolean;
 	timedOut?: boolean;
 	stopped?: boolean;
 	turnBudgetExceeded?: boolean;
 	results?: Array<{
+		runId?: string;
+		workflowKey?: string;
+		agent?: string;
 		status?: string;
 		success?: boolean;
 		exitCode?: number | null;
@@ -94,8 +103,23 @@ function formatSessionLine(details: SubagentNotifyDetails): string | undefined {
 	return details.sessionLabel ? `${details.sessionLabel}: ${details.sessionValue}` : details.sessionValue;
 }
 
+function formatChildRun(child: { runId: string; workflowKey?: string; agent?: string; status?: string }): string {
+	const label = child.workflowKey ?? child.agent;
+	const status = child.status ? ` (${child.status})` : "";
+	return `${label ? `${label}=` : ""}${child.runId}${status}`;
+}
+
+function formatCorrelationLines(details: SubagentNotifyDetails): string[] {
+	return [
+		details.workflowRunId ? `Workflow run: ${details.workflowRunId}` : undefined,
+		details.childRuns?.length ? `Child runs: ${details.childRuns.map(formatChildRun).join(", ")}` : undefined,
+		details.reconciledFromDetachedChild ? `Reconciled detached child: ${details.reconciledFromDetachedChild}` : undefined,
+	].filter((line): line is string => line !== undefined);
+}
+
 export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 	const sessionLine = formatSessionLine(details);
+	const correlationLines = formatCorrelationLines(details);
 	const taskKind = details.source === "foreground" ? "Detached foreground task" : "Background task";
 	const scheduleLine = details.scheduleOrigin
 		? `Scheduled run from **${details.scheduleOrigin.name ?? details.scheduleOrigin.id}** (schedule ${details.scheduleOrigin.id}).`
@@ -108,6 +132,8 @@ export function formatSingleCompletion(details: SubagentNotifyDetails): string {
 		details.resultPreview.trim() ? details.resultPreview : "(no output)",
 		details.handoffPath ? "" : undefined,
 		details.handoffPath ? `Parallel handoff: ${details.handoffPath}` : undefined,
+		correlationLines.length && !details.handoffPath ? "" : undefined,
+		...correlationLines,
 		sessionLine ? "" : undefined,
 		sessionLine,
 	]
@@ -139,11 +165,27 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 	}
 	const sessionLine = sessionIndex >= 0 ? body[sessionIndex] : undefined;
 	const handoffIndex = body.findIndex((line) => line.startsWith("Parallel handoff: "));
-	const metadataIndexes = [sessionIndex, handoffIndex].filter((index) => index >= 0);
+	const workflowRunIndex = body.findIndex((line) => line.startsWith("Workflow run: "));
+	const childRunsIndex = body.findIndex((line) => line.startsWith("Child runs: "));
+	const reconciledIndex = body.findIndex((line) => line.startsWith("Reconciled detached child: "));
+	const metadataIndexes = [sessionIndex, handoffIndex, workflowRunIndex, childRunsIndex, reconciledIndex].filter((index) => index >= 0);
 	const firstMetadataIndex = metadataIndexes.length ? Math.min(...metadataIndexes) : body.length;
 	const resultEnd = firstMetadataIndex > 0 && body[firstMetadataIndex - 1]?.trim() === "" ? firstMetadataIndex - 1 : firstMetadataIndex;
 	const resultPreview = body.slice(0, resultEnd).join("\n").trim() || "(no output)";
 	const handoffPath = handoffIndex >= 0 ? body[handoffIndex]!.slice("Parallel handoff: ".length).trim() : undefined;
+	const workflowRunId = workflowRunIndex >= 0 ? body[workflowRunIndex]!.slice("Workflow run: ".length).trim() : undefined;
+	const childRuns = childRunsIndex >= 0
+		? body[childRunsIndex]!.slice("Child runs: ".length).split(", ").map((part) => {
+			const trimmed = part.trim();
+			const statusMatch = trimmed.match(/^(.*?)(?: \(([^)]*)\))?$/);
+			const raw = statusMatch?.[1] ?? trimmed;
+			const separator = raw.indexOf("=");
+			return separator >= 0
+				? { workflowKey: raw.slice(0, separator), runId: raw.slice(separator + 1), ...(statusMatch?.[2] ? { status: statusMatch[2] } : {}) }
+				: { runId: raw, ...(statusMatch?.[2] ? { status: statusMatch[2] } : {}) };
+		}).filter((child) => child.runId)
+		: undefined;
+	const reconciledFromDetachedChild = reconciledIndex >= 0 ? body[reconciledIndex]!.slice("Reconciled detached child: ".length).trim() : undefined;
 	let sessionLabel: string | undefined;
 	let sessionValue: string | undefined;
 	if (sessionLine) {
@@ -159,6 +201,9 @@ export function parseSubagentNotifyContent(content: string): SubagentNotifyDetai
 		...(parsedScheduleOrigin ? { scheduleOrigin: parsedScheduleOrigin } : {}),
 		resultPreview,
 		...(handoffPath ? { handoffPath } : {}),
+		...(workflowRunId ? { workflowRunId } : {}),
+		...(childRuns?.length ? { childRuns } : {}),
+		...(reconciledFromDetachedChild ? { reconciledFromDetachedChild } : {}),
 		...(sessionLabel && sessionValue ? { sessionLabel, sessionValue } : {}),
 	};
 }
@@ -173,6 +218,7 @@ export function formatGroupedCompletion(details: SubagentNotifyDetails[]): strin
 		blocks.push(`${index + 1}. ${detail.agent}${detail.taskInfo ?? ""}${detail.scheduleOrigin ? ` — scheduled run from ${detail.scheduleOrigin.name ?? detail.scheduleOrigin.id} (schedule ${detail.scheduleOrigin.id})` : ""}`);
 		blocks.push(detail.resultPreview.trim() ? detail.resultPreview : "(no output)");
 		if (detail.handoffPath) blocks.push(`Parallel handoff: ${detail.handoffPath}`);
+		blocks.push(...formatCorrelationLines(detail));
 		if (sessionLine) blocks.push(sessionLine);
 		blocks.push("");
 	}
@@ -237,6 +283,18 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		? result.parallelHandoff as { path?: unknown }
 		: undefined;
 	const handoffPath = typeof parallelHandoff?.path === "string" ? parallelHandoff.path : undefined;
+	const rawRunId = typeof result.runId === "string" ? result.runId : typeof result.id === "string" ? result.id : undefined;
+	const workflowRunId = (result.mode === "workflow" || agent === "workflow") && rawRunId ? rawRunId : undefined;
+	const childRuns = result.results?.flatMap((child) => {
+		if (typeof child.runId !== "string" || !child.runId.trim()) return [];
+		return [{
+			runId: child.runId,
+			...(typeof child.workflowKey === "string" ? { workflowKey: child.workflowKey } : {}),
+			...(typeof child.agent === "string" ? { agent: child.agent } : {}),
+			...(typeof child.status === "string" ? { status: child.status } : {}),
+		}];
+	}) ?? [];
+	const reconciledFromDetachedChild = typeof result.reconciledFromDetachedChild === "string" ? result.reconciledFromDetachedChild : undefined;
 	const session =
 		result.shareUrl
 			? { label: "Session", value: result.shareUrl }
@@ -258,6 +316,9 @@ export function buildCompletionDetails(result: CompletionNotification): Subagent
 		resultPreview: summary,
 		...(typeof result.durationMs === "number" ? { durationMs: result.durationMs } : {}),
 		...(handoffPath ? { handoffPath } : {}),
+		...(workflowRunId ? { workflowRunId } : {}),
+		...(childRuns.length ? { childRuns } : {}),
+		...(reconciledFromDetachedChild ? { reconciledFromDetachedChild } : {}),
 		...(session ? { sessionLabel: session.label, sessionValue: session.value } : {}),
 	};
 }

package/src/runs/background/result-watcher.ts

@@ -57,7 +57,7 @@ type ResultWatcherDeps = {
 	coalesceDelayMs?: number;
 	/** Returns true while a durable completion source needs periodic delivery checks. */
 	hasDeliveryDemand?: () => boolean;
-	/** Control how slow result-index scans are logged. Defaults to \"all\". */
+	/** Control how slow result-index scans are logged. Defaults to \"activity\". */
 	resultScanLogging?: "all" | "activity" | "off";
 	platform?: NodeJS.Platform;
 };
@@ -606,12 +606,13 @@ export function createResultWatcher(
 	const logScanStats = (stats: ResultScanStats) => {
 		const elapsed = Date.now() - stats.startedAt;
 		if (elapsed < SLOW_RESULT_SCAN_MS) return;
-		if (deps.resultScanLogging === "off") return;
+		const resultScanLogging = deps.resultScanLogging ?? "activity";
+		if (resultScanLogging === "off") return;
 		// A scan that inspected and scheduled nothing is a quiet no-op (e.g. the
 		// healthy periodic rescan while no async runs are pending). Under
 		// "activity", skip it so empty scans do not burn context tokens in the
 		// session transcript.
-		if (deps.resultScanLogging === "activity" && stats.files === 0 && stats.scheduled === 0) return;
+		if (resultScanLogging === "activity" && stats.files === 0 && stats.scheduled === 0) return;
 		console.error(`Subagent result scan inspected ${stats.files} indexed result file(s), scheduled ${stats.scheduled} in ${elapsed}ms (${resultsDir}).`);
 	};
 	const indexedResultCandidates = (observed: ReadonlySet<string>): string[] => {

package/src/runs/background/run-status.ts

@@ -22,6 +22,7 @@ import { attachRootChildrenToSteps, findNestedRouteForRootId, projectNestedRegis
 import { readMissionBinding } from "../../missions/lifecycle.ts";
 import { formatWorkflowJsonPreview } from "../../workflows/scripted-workflow.ts";
 import { formatRunFanoutBudget, getRunFanoutBudgetSnapshot, readRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
+import { getExternalJobProvider } from "../../api/external-job-provider.ts";
 
 interface RunStatusParams {
 	action?: string;
@@ -161,6 +162,14 @@ function formatSteeringSummary(input: { steering?: SteeringStatus }): string | u
 	return `${steering.requested} requested, ${steering.scheduled} scheduled, ${steering.pending} pending, ${steering.delivered} delivered, ${steering.failed} failed, ${steering.recovered} recovered${lateAcknowledgments ? `, ${lateAcknowledgments} late acknowledged` : ""}`;
 }
 
+function externalJobFollowUpSupported(provider: string): boolean {
+	try {
+		return typeof getExternalJobProvider(provider)?.followUp === "function";
+	} catch {
+		return false;
+	}
+}
+
 function rememberedForegroundChildOutput(child: ForegroundResumeRun["children"][number]): string {
 	const outputPath = child.artifactPaths?.outputPath ?? child.savedOutputPath;
 	if (outputPath && fs.existsSync(outputPath)) {
@@ -513,6 +522,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 					&& Boolean(control.workflowSteeringDir && fs.existsSync(control.workflowSteeringDir))
 					&& (control.activeChildren?.size ?? 0) > 0)
 				: [];
+			let hasExternalJobFollowUpHint = false;
 			for (const [index, step] of (status.steps ?? []).entries()) {
 				const stepActivityText = step.status === "running" ? formatActivityLabel(step.lastActivityAt, step.activityState) : undefined;
 				const modelThinking = formatModelThinking(step.model, step.thinking);
@@ -535,6 +545,10 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 					if (step.externalJob?.state) lines.push(`  Provider state: ${step.externalJob.state}`);
 					if (step.externalJob?.conversationUrl) lines.push(`  Conversation: ${step.externalJob.conversationUrl}`);
 					if (step.externalJob?.resultArtifactPath) lines.push(`  Result artifact: ${step.externalJob.resultArtifactPath}`);
+					if ((step.status === "complete" || step.status === "completed") && step.externalJob?.state === "completed" && step.externalJob.providerJobId && externalJobFollowUpSupported(step.runner.provider)) {
+						hasExternalJobFollowUpHint = true;
+						lines.push(`  Follow-up: subagent({ action: "resume", id: "${status.runId}", index: ${index}, message: "..." })`);
+					}
 				}
 				lines.push(...formatNestedRunStatusLines(step.children, { indent: "  ", commandHints: true, maxLines: 20 }));
 				const stepOutputPath = path.join(asyncDir, `output-${index}.log`);
@@ -563,7 +577,7 @@ export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDe
 			if (status.state === "running" && !allExternal && status.mode !== "workflow") lines.push(`Steer running child: subagent({ action: "steer", id: "${status.runId}", message: "..." })`);
 			if (status.state !== "running") {
 				lines.push(allExternal
-					? "Resume: unavailable; external runners do not persist Pi sessions."
+					? hasExternalJobFollowUpHint ? "Resume: use the external-job follow-up hint above." : "Resume: unavailable; external runners do not persist Pi sessions."
 					: formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile, { stopped: status.state === "stopped" || status.stopped === true }));
 			}
 			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);

package/src/runs/background/stale-run-reconciler.ts

@@ -97,6 +97,7 @@ interface ResultChildOutcome {
 	thinking?: string;
 	attemptedModels?: string[];
 	modelAttempts?: NonNullable<AsyncStatus["steps"]>[number]["modelAttempts"];
+	contextOverflow?: boolean;
 }
 
 interface ResultRepairData {
@@ -163,6 +164,7 @@ function terminalStatusFromResult(status: AsyncStatus, resultPath: string, now:
 			thinking,
 			attemptedModels: child?.attemptedModels ?? step.attemptedModels,
 			modelAttempts: child?.modelAttempts ?? step.modelAttempts,
+			contextOverflow: child?.contextOverflow ?? step.contextOverflow,
 		};
 	});
 	const terminalStatus: AsyncStatus = {
@@ -258,6 +260,7 @@ function buildFailedRepair(status: AsyncStatus, asyncDir: string, now: number, r
 				model: step.model,
 				attemptedModels: step.attemptedModels,
 				modelAttempts: step.modelAttempts,
+				contextOverflow: step.contextOverflow,
 				sessionFile: step.sessionFile,
 			})),
 			exitCode: 1,