pi-subagents 0.58.0 → 0.60.0

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

@@ -58,12 +58,15 @@ import {
 	type Details,
 	type ForegroundResumeRun,
 	type SubagentState,
+	type Usage,
 	type WaitCompletion,
 } from "../../shared/types.ts";
 import { formatDuration, shortenPath } from "../../shared/formatters.ts";
+import { toAgentToolUsage } from "../../shared/utils.ts";
 import { collectWaitCompletions } from "./wait-completions.ts";
 import { formatResumeFirstFailedRunsNote } from "./resume-guidance.ts";
-export { WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
+import { formatTimeoutRecoveryLines } from "../shared/mutation-evidence.ts";
+export { WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV, WAIT_TOOL_ENABLED_ENV, resolveWaitToolConfig, type ResolvedWaitToolConfig } from "./wait-config.ts";
 
 /** States that mean a run is still in flight (not yet resolved). */
 const ACTIVE_STATES: ReadonlyArray<AsyncRunSummary["state"]> = ["queued", "running"];
@@ -84,7 +87,7 @@ export interface SubagentWaitParams {
 	 * targets a single run.
 	 */
 	all?: boolean;
-	/** Give up after this many milliseconds. Defaults to 30 minutes. */
+	/** Give up after this many milliseconds. Defaults to waitTool.defaultTimeoutMs, then 30 minutes. */
 	timeoutMs?: number;
 	/** False keeps a blocking wait open through idle attention; supervisor/contact requests still stop the wait. */
 	stopOnAttention?: boolean;
@@ -106,6 +109,8 @@ export interface SubagentWaitDeps {
 	pollIntervalMs?: number;
 	/** False makes the tool return immediately without blocking active async runs. */
 	enabled?: boolean;
+	/** Configured blocking window used when the call omits timeoutMs. */
+	defaultTimeoutMs?: number;
 	/** Injectable sleep for tests. */
 	sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 	/** Internal auto-drain mode waits through needs-attention states. */
@@ -312,10 +317,31 @@ function summarizeTerminalRuns(runs: AsyncRunSummary[], providerFinishedCount =
 	return parts.join(", ");
 }
 
+function completionUsage(completions: WaitCompletion[] | undefined): Usage | undefined {
+	if (!completions?.length) return undefined;
+	const usage: Usage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	let projected = false;
+	for (const completion of completions) {
+		for (const child of completion.results ?? []) {
+			if (!child.usage || (child.usage.input === 0 && child.usage.output === 0 && child.usage.cacheRead === 0 && child.usage.cacheWrite === 0 && child.usage.cost === 0 && child.usage.turns === 0)) continue;
+			projected = true;
+			usage.input += child.usage.input;
+			usage.output += child.usage.output;
+			usage.cacheRead += child.usage.cacheRead;
+			usage.cacheWrite += child.usage.cacheWrite;
+			usage.cost += child.usage.cost;
+			usage.turns += child.usage.turns;
+		}
+	}
+	return projected ? usage : undefined;
+}
+
 function result(text: string, isError = false, completions?: WaitCompletion[]): AgentToolResult<Details> {
+	const usage = completionUsage(completions);
 	return {
 		content: [{ type: "text", text }],
 		...(isError ? { isError: true } : {}),
+		...(usage ? { usage: toAgentToolUsage(usage) } : {}),
 		details: {
 			mode: "management",
 			results: [],
@@ -324,6 +350,32 @@ function result(text: string, isError = false, completions?: WaitCompletion[]):
 	};
 }
 
+function formatCompletionRecovery(completions: WaitCompletion[] | undefined): string {
+	const lines = (completions ?? []).flatMap((completion) =>
+		(completion.results ?? []).flatMap((child) => formatTimeoutRecoveryLines(child.timeoutRecovery)));
+	return lines.length > 0 ? `\n${lines.join("\n")}` : "";
+}
+
+function windowElapsedResult(
+	text: string,
+	activeRunIds: string[],
+	activeProviderItems: readonly RegisteredBackgroundWorkItem[] = [],
+): AgentToolResult<Details> {
+	return {
+		content: [{ type: "text", text }],
+		details: {
+			mode: "management",
+			results: [],
+			wait: {
+				reason: "window_elapsed",
+				timedOut: true,
+				activeRunIds,
+				activeProviderItems: activeProviderItems.map(({ provider, id }) => ({ provider, id })),
+			},
+		},
+	};
+}
+
 /** Build the live status shown while async work keeps subagent_wait blocked. */
 function asyncWaitUpdate(runs: AsyncRunSummary[], providerCount: number, elapsedMs: number): AgentToolResult<Details> {
 	const activity = runs.flatMap((run) => {
@@ -471,9 +523,9 @@ async function waitForDetachedForegroundRun(
 			return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Remembered foreground run "${run.runId}" remains detached. Reply to any pending supervisor request before resuming or launching a replacement.`, true);
 		}
 		if (now() - startedAt >= timeoutMs) {
-			return result(
-				`Wait timed out after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call subagent_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
-				true,
+			return windowElapsedResult(
+				`Wait window elapsed after ${formatDuration(timeoutMs)} with remembered foreground run "${run.runId}" still detached. Reply to any pending supervisor request, then call subagent_wait({ id: "${run.runId}" }) again or inspect status; do not resume or launch a replacement while it remains detached.`,
+				[run.runId],
 			);
 		}
 		await waitForWake(pollIntervalMs, signal, deps);
@@ -499,7 +551,9 @@ export async function waitForSubagents(
 
 	const now = deps.now ?? Date.now;
 	const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
-	const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0 ? params.timeoutMs : DEFAULT_TIMEOUT_MS;
+	const timeoutMs = params.timeoutMs !== undefined && params.timeoutMs > 0
+		? params.timeoutMs
+		: deps.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
 	const startedAt = now();
 	const waitForAll = params.id ? true : params.all === true;
 	if (params.nonBlocking && !params.id) {
@@ -586,9 +640,10 @@ export async function waitForSubagents(
 			return result(`Wait aborted after ${formatDuration(now() - startedAt)}. Still active: ${stillActive}.`, true);
 		}
 		if (now() - startedAt >= timeoutMs) {
-			return result(
-				`Wait timed out after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call subagent_wait again or inspect subagent status.`,
-				true,
+			return windowElapsedResult(
+				`Wait window elapsed after ${formatDuration(timeoutMs)} with ${activeInitialRuns.length} async run(s) and ${activeInitialProviderItems.length} provider item(s) still active: ${stillActive}. The work keeps going; call subagent_wait again or inspect subagent status.`,
+				activeInitialRuns.map((run) => run.id),
+				activeInitialProviderItems,
 			);
 		}
 		try {
@@ -618,7 +673,7 @@ export async function waitForSubagents(
 		const allNow = runsForIds(initialAsyncIds, deps);
 		const terminal = allNow.filter((run) => !ACTIVE_STATES.includes(run.state) && initialAsyncIds.has(run.id));
 		finishedAsyncCount = terminal.length;
-		failedAsyncCount = terminal.filter((run) => run.state === "failed").length;
+		failedAsyncCount = terminal.filter((run) => run.state === "failed" || run.state === "partial").length;
 		terminalSummary = summarizeTerminalRuns(terminal, providerFinishedCount);
 		resumeGuidance = formatResumeFirstFailedRunsNote(terminal);
 		completions = collectWaitCompletions(terminal, deps.state, deps.resultsDir ?? DIRS.results);
@@ -637,6 +692,7 @@ export async function waitForSubagents(
 		+ providerActive.filter((item) => initialProviderIds.has(backgroundWorkIdentity(item))).length;
 	const elapsed = formatDuration(now() - startedAt);
 	const outcome = terminalSummary ? ` Outcome: ${terminalSummary}.` : "";
+	const recoveryNote = formatCompletionRecovery(completions);
 
 	if (waitForAll) {
 		const scope = params.id
@@ -646,7 +702,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}${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} 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,
 		);
@@ -663,7 +719,7 @@ export async function waitForSubagents(
 		? `${relevantAttention.length} of ${initialCount} ${subject} need attention`
 		: `${finishedCount} of ${initialCount} ${subject} finished`;
 	return result(
-		`Waited ${elapsed}; ${progress}.${outcome}${resumeGuidance}${attentionNote}${remainder} Relevant completion/control events have been observed; inspect status if a notification is not visible yet.`,
+		`Waited ${elapsed}; ${progress}.${outcome}${recoveryNote}${resumeGuidance}${attentionNote}${remainder} Relevant 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/terminal-run-index.ts

@@ -18,7 +18,7 @@ interface TerminalRunIndexEntry {
 }
 
 function isTerminalState(state: AsyncStatus["state"]): boolean {
-	return state === "complete" || state === "failed" || state === "paused" || state === "stopped" || state === "rejected";
+	return state === "complete" || state === "failed" || state === "partial" || state === "paused" || state === "stopped" || state === "rejected";
 }
 
 function indexRoot(asyncDirRoot: string): string {

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

@@ -1,14 +1,32 @@
 import * as fs from "node:fs";
-import type { ArtifactPaths, SubagentState, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
+import type { ArtifactPaths, SubagentState, Usage, WaitCompletion, WaitCompletionChild } from "../../shared/types.ts";
 import type { AsyncRunSummary } from "./async-status.ts";
 import { readCompletionReplay, writeCompletionReplay } from "./completion-replay.ts";
 import { fallbackResultPayloadPathForSessionRun, resultFilePath, resultPayloadPathForSessionRun } from "./result-files.ts";
 import { parseWorkflowChildSummary } from "../../workflows/workflow-child-summary.ts";
+import { projectTimeoutRecovery } from "../shared/mutation-evidence.ts";
 
 function asNonEmptyString(value: unknown): string | undefined {
 	return typeof value === "string" && value ? value : undefined;
 }
 
+function nonNegativeNumber(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+function projectedUsage(value: unknown): Usage | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const input = nonNegativeNumber(record.input);
+	const output = nonNegativeNumber(record.output);
+	const cacheRead = nonNegativeNumber(record.cacheRead);
+	const cacheWrite = nonNegativeNumber(record.cacheWrite);
+	const cost = nonNegativeNumber(record.cost);
+	const turns = nonNegativeNumber(record.turns);
+	if (input === undefined || output === undefined || cacheRead === undefined || cacheWrite === undefined || cost === undefined || turns === undefined || !Number.isSafeInteger(turns)) return undefined;
+	return { input, output, cacheRead, cacheWrite, cost, turns };
+}
+
 function errorCode(error: unknown): string | undefined {
 	return typeof error === "object" && error !== null && "code" in error
 		? (error as NodeJS.ErrnoException).code
@@ -43,18 +61,24 @@ export function toWaitCompletion(data: Record<string, unknown>, runId: string):
 				: undefined;
 			const agent = asNonEmptyString(child.agent);
 			const childRunId = asNonEmptyString(child.runId);
+			const usage = projectedUsage(child.usage);
+			const sessionFile = asNonEmptyString(child.sessionFile);
 			const error = asNonEmptyString(child.error);
 			const model = asNonEmptyString(child.model);
 			const contextOverflow = child.contextOverflow === true;
+			const timeoutRecovery = projectTimeoutRecovery(child.timeoutRecovery);
 			return [{
 				...(agent ? { agent } : {}),
 				...(childRunId ? { runId: childRunId } : {}),
+				...(usage ? { usage } : {}),
+				...(sessionFile ? { sessionFile } : {}),
 				...(typeof child.success === "boolean" ? { success: child.success } : {}),
 				...(outputState ? { outputState } : {}),
 				...(error ? { error } : {}),
 				...(model ? { model } : {}),
 				...(contextOverflow ? { contextOverflow: true } : {}),
 				...(artifactPaths ? { artifactPaths } : {}),
+				...(timeoutRecovery ? { timeoutRecovery } : {}),
 			}];
 		})
 		: undefined;

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

@@ -1,9 +1,11 @@
 import type { WaitToolConfig } from "../../shared/types.ts";
 
 export const WAIT_TOOL_ENABLED_ENV = "PI_SUBAGENT_WAIT_TOOL_ENABLED";
+export const WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV = "PI_SUBAGENT_WAIT_TOOL_DEFAULT_TIMEOUT_MS";
 
 export interface ResolvedWaitToolConfig {
 	enabled: boolean;
+	defaultTimeoutMs?: number;
 }
 
 const TRUE_VALUES = new Set(["1", "true", "yes", "on", "enabled"]);
@@ -17,20 +19,32 @@ function environmentValue(value: string | undefined): boolean | undefined {
 	throw new Error(`${WAIT_TOOL_ENABLED_ENV} must be one of true/false, 1/0, yes/no, on/off, or enabled/disabled.`);
 }
 
-function configuredValue(config: unknown): boolean | undefined {
-	if (config === undefined) return undefined;
-	if (typeof config === "boolean") return config;
+function environmentDefaultTimeoutMs(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number(value);
+	if (!Number.isInteger(parsed) || parsed < 1) throw new Error(`${WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV} must be a positive integer.`);
+	return parsed;
+}
+
+function configuredValue(config: unknown): { enabled?: boolean; defaultTimeoutMs?: number } {
+	if (config === undefined) return {};
+	if (typeof config === "boolean") return { enabled: config };
 	if (!config || typeof config !== "object" || Array.isArray(config)) {
-		throw new Error("config.waitTool must be a boolean or an object with optional enabled boolean.");
+		throw new Error("config.waitTool must be a boolean or an object with optional enabled and defaultTimeoutMs values.");
+	}
+	const { enabled, defaultTimeoutMs } = config as { enabled?: unknown; defaultTimeoutMs?: unknown };
+	if (enabled !== undefined && typeof enabled !== "boolean") throw new Error("config.waitTool.enabled must be a boolean.");
+	if (defaultTimeoutMs !== undefined && (!Number.isInteger(defaultTimeoutMs) || (defaultTimeoutMs as number) < 1)) {
+		throw new Error("config.waitTool.defaultTimeoutMs must be a positive integer.");
 	}
-	const enabled = (config as { enabled?: unknown }).enabled;
-	if (enabled === undefined) return undefined;
-	if (typeof enabled !== "boolean") throw new Error("config.waitTool.enabled must be a boolean.");
-	return enabled;
+	return { enabled, ...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs: defaultTimeoutMs as number } : {}) };
 }
 
 export function resolveWaitToolConfig(config?: WaitToolConfig, env: Record<string, string | undefined> = process.env): ResolvedWaitToolConfig {
+	const configured = configuredValue(config);
+	const envDefaultTimeoutMs = environmentDefaultTimeoutMs(env[WAIT_TOOL_DEFAULT_TIMEOUT_MS_ENV]);
 	return {
-		enabled: environmentValue(env[WAIT_TOOL_ENABLED_ENV]) ?? configuredValue(config) ?? true,
+		enabled: environmentValue(env[WAIT_TOOL_ENABLED_ENV]) ?? configured.enabled ?? true,
+		...(envDefaultTimeoutMs ?? configured.defaultTimeoutMs !== undefined ? { defaultTimeoutMs: envDefaultTimeoutMs ?? configured.defaultTimeoutMs } : {}),
 	};
 }

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

@@ -5,7 +5,13 @@ import { resolveWaitToolConfig, waitForSubagents } from "./subagent-wait.ts";
 import type { WaitSubscriptionManager } from "./wait-subscriptions.ts";
 import { finalizeToolResult } from "../../extension/tool-result.ts";
 
-export function registerWaitTool(pi: ExtensionAPI, state: SubagentState, enabled = resolveWaitToolConfig().enabled, subscriptions?: Pick<WaitSubscriptionManager, "arm">): void {
+export function registerWaitTool(
+	pi: ExtensionAPI,
+	state: SubagentState,
+	enabled = resolveWaitToolConfig().enabled,
+	subscriptions?: Pick<WaitSubscriptionManager, "arm">,
+	defaultTimeoutMs?: number,
+): void {
 	const tool: ToolDefinition<typeof SubagentWaitParams, Details> = {
 		name: "subagent_wait",
 		label: "Subagent Wait",
@@ -18,7 +24,7 @@ In an interactive chat, do not call this merely to wait: return control to the u
 • { 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. 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.
-• { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running.
+• { timeoutMs: 600000 } — stop waiting after N ms; active work keeps running. Omitted values use waitTool.defaultTimeoutMs, then 30 minutes. Window expiry returns a non-error window_elapsed result with active work identities.
 
 Non-blocking subscriptions are visible in subagent status and differ from disabling waitTool: waitTool.enabled=false returns immediately without registering any future wake. Provider jobs are session-scoped and identified exactly, so replacing one job with another cannot hide a completion. Provider extensions must be explicitly loaded in this process. In a child agent, keep \`subagent_wait\` in the child tool allowlist and load each provider through the agent's extensions or subagentOnlyExtensions; this tool never loads providers or grants tools itself.${enabled ? "" : "\n\nConfigured behavior: subagent_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`,
 		parameters: SubagentWaitParams,
@@ -27,6 +33,7 @@ Non-blocking subscriptions are visible in subagent status and differ from disabl
 				state,
 				events: pi.events,
 				enabled,
+				...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
 				onUpdate,
 				...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
 			}));

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

@@ -3,7 +3,7 @@ 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, TurnBudgetConfig } from "../../shared/types.ts";
+import type { AsyncStatus, Details, SubagentState, ToolBudgetConfig } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { consumeSteerAcks, deliverInterruptRequest, queueRevivalBrief, requestAsyncSteer, type SteerDeliveryMode, type SteerRequest } from "../background/control-channel.ts";
 import { resolveAsyncResumeTarget } from "../background/async-resume.ts";
@@ -34,7 +34,7 @@ export async function steerAsyncRun(input: {
 	onRequestQueued?: (requestPath: string) => void;
 	onBeforeRecoveryClaim?: (requestId: string, committedAt: number) => void;
 	onRecoveryCommitted?: (requestId: string, committedAt: number) => void;
-	recover?: (limits: { timeoutMs?: number; absoluteDeadlineAt?: number; turnBudget?: TurnBudgetConfig; toolBudget?: ToolBudgetConfig }) => Promise<AgentToolResult<Details>>;
+	recover?: (limits: { timeoutMs?: number; absoluteDeadlineAt?: number; toolBudget?: ToolBudgetConfig }) => Promise<AgentToolResult<Details>>;
 }): Promise<AgentToolResult<Details>> {
 	if (!input.location.asyncDir) {
 		return {