pi-subagents 0.65.1 → 0.67.0

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

@@ -214,14 +214,13 @@ function matchesId(run: AsyncRunSummary, id: string): boolean {
 }
 
 function activeDetachedForegroundRuns(params: SubagentWaitParams, deps: SubagentWaitDeps): ForegroundResumeRun[] {
-	if (!params.id || !deps.state.foregroundRuns) return [];
 	const sessionId = deps.state.currentSessionId;
-	if (!sessionId) return [];
-	return [...deps.state.foregroundRuns.values()].filter((run) =>
-		(run.runId === params.id || run.runId.startsWith(params.id!))
-		&& run.sessionId === sessionId
-		&& run.children.some((child) => child.status === "detached")
+	if (!sessionId || !deps.state.foregroundRuns) return [];
+	const runs = [...deps.state.foregroundRuns.values()].filter((run) =>
+		run.sessionId === sessionId && run.children.some((child) => child.status === "detached")
 	);
+	if (params.id) return runs.filter((run) => run.runId === params.id || run.runId.startsWith(params.id!));
+	return params.all === true ? runs : [];
 }
 
 function summarizeForegroundChildren(run: ForegroundResumeRun, indices: Set<number>): string {
@@ -337,6 +336,9 @@ function completionUsage(completions: WaitCompletion[] | undefined): Usage | und
 
 function result(text: string, isError = false, completions?: WaitCompletion[]): AgentToolResult<Details> {
 	const usage = completionUsage(completions);
+	for (const completion of completions ?? []) {
+		if (completion.workflowReceiptPath) text += `\nWorkflow receipt [${completion.runId}]: ${completion.workflowReceiptPath}`;
+	}
 	return {
 		content: [{ type: "text", text }],
 		...(isError ? { isError: true } : {}),
@@ -531,6 +533,36 @@ async function waitForDetachedForegroundRun(
 	}
 }
 
+async function waitForSessionDetachedForegroundRuns(
+	runs: ForegroundResumeRun[],
+	signal: AbortSignal | undefined,
+	deps: SubagentWaitDeps,
+	startedAt: number,
+	now: () => number,
+	pollIntervalMs: number,
+	timeoutMs: number,
+): Promise<AgentToolResult<Details>> {
+	const texts: string[] = [];
+	for (const run of runs) {
+		const one = await waitForDetachedForegroundRun(run, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
+		if (one.isError) return one;
+		if (one.details.wait?.reason === "window_elapsed") {
+			const activeRunIds = runs.filter((initial) => {
+				const current = deps.state.foregroundRuns?.get(initial.runId);
+				if (!current || current.sessionId !== initial.sessionId) return false;
+				return initial.children.some((child) => child.status === "detached"
+						&& current.children.some((candidate) => candidate.index === child.index && candidate.status === "detached"));
+			}).map((activeRun) => activeRun.runId);
+			return windowElapsedResult(
+				one.content.map((part) => part.type === "text" ? part.text : "").join("\n"),
+				activeRunIds,
+			);
+		}
+		texts.push(one.content.map((part) => part.type === "text" ? part.text : "").join("\n").trim());
+	}
+	return result(texts.filter(Boolean).join("\n") || `Waited ${formatDuration(now() - startedAt)} for remembered detached foreground run(s); done.`);
+}
+
 /**
  * Block until the targeted async or remembered detached foreground run finishes,
  * the timeout elapses, or the turn is aborted. Resolves with a short
@@ -567,7 +599,10 @@ export async function waitForSubagents(
 	let providerSnapshot: BackgroundWorkSnapshot;
 	try {
 		active = activeRunsForSession(params, deps);
-		foreground = activeDetachedForegroundRuns(params, deps);
+		foreground = activeDetachedForegroundRuns(params, deps).map((run) => ({
+			...run,
+			children: run.children.map((child) => ({ ...child })),
+		}));
 		providerSnapshot = params.id ? { providers: [], items: [] } : backgroundWorkForSession(deps, startedAt);
 	} catch (error) {
 		return result(error instanceof Error ? error.message : String(error), true);
@@ -603,6 +638,9 @@ export async function waitForSubagents(
 
 	let providerActive = providerSnapshot.items;
 	if (active.length === 0 && providerActive.length === 0) {
+		if (waitForAll && !params.id && foreground.length > 0) {
+			return waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs);
+		}
 		return result(params.id
 			? `No active run matched "${params.id}". Nothing to wait for.`
 			: "No active async runs or registered provider work in this session. Nothing to wait for.");
@@ -694,6 +732,14 @@ export async function waitForSubagents(
 	const recoveryNote = formatCompletionRecovery(completions);
 
 	if (waitForAll) {
+		const foregroundResult = !params.id && foreground.length > 0 && relevantAttention.length === 0
+			? await waitForSessionDetachedForegroundRuns(foreground, signal, deps, startedAt, now, pollIntervalMs, timeoutMs)
+			: undefined;
+		if (foregroundResult?.isError) return foregroundResult;
+		if (foregroundResult?.details.wait?.reason === "window_elapsed") return foregroundResult;
+		const foregroundNote = foregroundResult
+			? `\n${foregroundResult.content.map((part) => part.type === "text" ? part.text : "").join("\n")}`
+			: "";
 		const scope = params.id
 			? `run "${params.id}"`
 			: initialProviderIds.size === 0
@@ -701,7 +747,7 @@ export async function waitForSubagents(
 				: `${initialAsyncIds.size} async run(s) and ${initialProviderIds.size} provider item(s)`;
 		const status = relevantAttention.length > 0 ? "attention required" : "done";
 		return result(
-			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
+			`Waited ${elapsed} for ${scope}; ${status}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote}${foregroundNote} Completion/control events have been observed; inspect status if a notification is not visible yet.`,
 			(deps.failOnFailedRuns === true && failedAsyncCount > 0) || (deps.failOnAttention === true && relevantAttention.length > 0),
 			completions,
 		);

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

@@ -96,6 +96,9 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 		})
 		: undefined;
 	const agent = asNonEmptyString(data.agent);
+	const receipt = data.workflowReceipt;
+	const workflowReceiptPath = receipt && typeof receipt === "object" && !Array.isArray(receipt)
+		? asNonEmptyString((receipt as Record<string, unknown>).path) : undefined;
 	const mode = asNonEmptyString(data.mode);
 	const state = asNonEmptyString(data.state);
 	const workflowChildren = parseWorkflowChildSummary(data.workflowChildren);
@@ -104,6 +107,7 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 		runId,
 		...(agent ? { agent } : {}),
 		...(mode ? { mode } : {}),
+		...(workflowReceiptPath ? { workflowReceiptPath } : {}),
 		...(state ? { state } : {}),
 		...(typeof data.success === "boolean" ? { success: data.success } : {}),
 		...(results && results.length > 0 ? { results } : {}),

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

@@ -17,7 +17,7 @@ export function registerWaitTool(
 Ordinary async subagent runs already notify this session natively when they complete or need attention. In an interactive chat, return control instead of calling this merely to wait. Use this tool for provider jobs, remembered detached foreground runs, or other background work without a native notification path. Headless runs auto-drain current-session subagent work at agent_end; use this tool only when the current turn must receive non-notifying background work results.
 
 • { } — return when the first initially active async run or registered provider item finishes, or when a subagent needs attention.
-• { all: true } — wait for every async run and provider item that was active when the call began.
+• { all: true } — wait for every async run, provider item, and remembered detached foreground descendant that was active when the call began.
 • { id: "..." } — wait for one async or remembered detached foreground subagent run (id or prefix).
 • { id: "...", nonBlocking: true } — resolve the prefix once, persist an exact-run wake subscription, and return immediately. Use this for detached work without native completion delivery; the originating interactive session wakes on completion, failure, attention, reconciliation failure, or timeout.
 • { stopOnAttention: false } — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.

package/src/runs/foreground/async-steering-action.ts

@@ -3,13 +3,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import type { AsyncStatus, Details, SubagentState, ToolBudgetConfig } from "../../shared/types.ts";
+import type { AsyncStatus, Details, SteerActionResult, SubagentState, ToolBudgetConfig } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { deliverInterruptRequest, queueRevivalBrief, requestAsyncSteer, type SteerDeliveryMode, type SteerRequest } from "../background/control-channel.ts";
 import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
 import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
 import { actionResultFromSteeringStatus, claimSteeringRecovery, createSteeringStatus, recordSteeringRequest, remainingSteeringRecoveryLimits, steeringReceipt, updateSteeringTarget, waitForSteeringAction } from "../background/steering.ts";
 
+function steerTargetsAccepted(result: Pick<SteerActionResult, "targets"> | undefined): boolean {
+	const targets = result?.targets ?? [];
+	return targets.length > 0 && targets.every((target) => target.state === "queued" || target.state === "delivered");
+}
+
 export function canQueueRetainedAsyncFollowUp(status: AsyncStatus, index?: number): boolean {
 	const steps = status.steps ?? [];
 	return status.state === "complete"
@@ -26,6 +31,7 @@ export async function steerAsyncRun(input: {
 	message: string;
 	mode?: SteerDeliveryMode;
 	index?: number;
+	findPendingAsks?: (target: { runId: string; agent: string; childIndex: number }) => string[];
 	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
 	location: { asyncDir: string | null };
 	signal?: AbortSignal;
@@ -44,6 +50,24 @@ export async function steerAsyncRun(input: {
 		};
 	}
 	const asyncDir = input.location.asyncDir;
+	const snapshot = input.findPendingAsks ? readStatus(asyncDir) : null;
+	if (snapshot?.mode === "single"
+		&& (!input.state.currentSessionId || snapshot.sessionId === input.state.currentSessionId)
+		&& (snapshot.state === "running" || snapshot.state === "queued")
+		&& snapshot.steps?.length === 1 && (input.index === undefined || input.index === 0)
+		&& (snapshot.steps[0]?.status === "running" || snapshot.steps[0]?.status === "pending")) {
+		const asks = input.findPendingAsks?.({ runId: snapshot.runId, agent: snapshot.steps[0].agent, childIndex: 0 }) ?? [];
+		if (asks.length > 0) {
+			const replies = asks.map(replyTo => `subagent_supervisor(${JSON.stringify({ action: "reply", replyTo, message: "<explicit answer>" })})`).join("\n");
+			return {
+				content: [{ type: "text", text: `Steering not delivered or queued: async run ${snapshot.runId} is blocked on ${asks.length === 1 ? "a pending supervisor ask" : "ambiguous pending supervisor asks"}. No reply or recovery was attempted. Reply explicitly${asks.length > 1 ? " to the intended request ID" : ""}:\n${replies}` }],
+				isError: true,
+				details: { mode: "management", results: [] },
+			};
+		}
+	}
+	// The read-only snapshot precedes even stale-run reconciliation. An ask arriving
+	// later does not make a runner acknowledgement proof of consumption or unblocking.
 	const status = reconcileAsyncRun(asyncDir, { kill: input.kill }).status;
 	if (input.state.currentSessionId && status?.sessionId !== input.state.currentSessionId) {
 		return {
@@ -151,9 +175,11 @@ export async function steerAsyncRun(input: {
 	}
 	const finalStatus = readStatus(asyncDir);
 	const finalResult = finalStatus?.steering ? actionResultFromSteeringStatus(finalStatus.steering, status.runId, requestId) : undefined;
-	if (finalResult?.state === "delivered") {
-		return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: finalResult } };
-	}
+	const acceptedReply = (accepted: SteerActionResult): AgentToolResult<Details> => {
+		const acceptedState = accepted.state === "delivered" ? "delivered" : "queued";
+		return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering ${acceptedState} for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: accepted } };
+	};
+	if (finalResult && steerTargetsAccepted(finalResult)) return acceptedReply(finalResult);
 	const running = (finalStatus?.steps ?? status.steps ?? []).filter((step) => step.status === "running");
 	const recoveryAllowed = (input.mode ?? "steer") === "steer" && status.mode === "single" && status.isNested !== true && running.length === 1 && Boolean(finalStatus?.steering) && (input.index === undefined || input.index === 0);
 	if (recoveryAllowed && finalResult?.state !== "scheduled" && input.recover) {
@@ -167,17 +193,21 @@ export async function steerAsyncRun(input: {
 		try {
 			const latest = readStatus(asyncDir);
 			const latestResult = latest?.steering ? actionResultFromSteeringStatus(latest.steering, status.runId, requestId) : undefined;
-			if (latestResult?.state === "delivered") return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: latestResult } };
+			if (latestResult && steerTargetsAccepted(latestResult)) return acceptedReply(latestResult);
 			const committedAt = Date.now();
 			input.onBeforeRecoveryClaim?.(requestId, committedAt);
 			const { claimPath, markerPath } = claimSteeringRecovery(asyncDir, { requestId, sourceRunId: status.runId, committedAt });
 			input.onRecoveryCommitted?.(requestId, committedAt);
 			const preCommitStatus = readStatus(asyncDir);
 			const preCommitResult = preCommitStatus?.steering ? actionResultFromSteeringStatus(preCommitStatus.steering, status.runId, requestId) : undefined;
-			if (preCommitResult?.state === "delivered" && preCommitResult.targets.every((target) => target.deliveredAt !== undefined && target.deliveredAt <= committedAt)) {
+			if (
+				preCommitResult
+				&& preCommitResult.targets.length > 0
+				&& preCommitResult.targets.every((target) => target.state === "queued" || (target.deliveredAt !== undefined && target.deliveredAt <= committedAt))
+			) {
 				fs.rmSync(markerPath, { force: true });
 				fs.rmSync(claimPath, { force: true });
-				return { content: [{ type: "text", text: steeringReceipt(input.message, `Steering delivered for async run ${status.runId} (request ${requestId}).`) }], details: { mode: "management", results: [], steering: preCommitResult } };
+				return acceptedReply(preCommitResult);
 			}
 			try {
 				deliverInterruptRequest({ asyncDir, source: "steering-recovery" });