pi-subagents 0.34.0 → 0.35.0

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

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { formatDuration, formatModelThinking, formatTokens, shortenPath } from "../../shared/formatters.ts";
 import { formatActivityLabel, formatParallelOutcome } from "../../shared/status-format.ts";
-import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type NestedRunSummary, type SubagentRunMode, type TokenUsage, type TurnBudgetState } from "../../shared/types.ts";
+import { type ActivityState, type AsyncJobStep, type AsyncParallelGroupStatus, type AsyncStatus, type CostSummary, type NestedRunSummary, type SteeringStatus, type SubagentRunMode, type TokenUsage, type TurnBudgetState } from "../../shared/types.ts";
 import { readStatus } from "../../shared/utils.ts";
 import { attachRootChildrenToSteps, buildNestedRouteIndex, type NestedRoute, projectNestedEvents } from "../shared/nested-events.ts";
 import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
@@ -27,8 +27,7 @@ interface AsyncRunStepSummary {
 	recentOutput?: string[];
 	turnCount?: number;
 	toolCount?: number;
-	steerCount?: number;
-	lastSteerAt?: number;
+	steering?: SteeringStatus;
 	durationMs?: number;
 	tokens?: TokenUsage;
 	totalCost?: CostSummary;
@@ -38,6 +37,7 @@ interface AsyncRunStepSummary {
 	attemptedModels?: string[];
 	error?: string;
 	timedOut?: boolean;
+	stopped?: boolean;
 	turnBudget?: TurnBudgetState;
 	turnBudgetExceeded?: boolean;
 	wrapUpRequested?: boolean;
@@ -48,7 +48,7 @@ export interface AsyncRunSummary {
 	id: string;
 	asyncDir: string;
 	sessionId?: string;
-	state: "queued" | "running" | "complete" | "failed" | "paused";
+	state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped";
 	error?: string;
 	activityState?: ActivityState;
 	lastActivityAt?: number;
@@ -57,8 +57,7 @@ export interface AsyncRunSummary {
 	currentPath?: string;
 	turnCount?: number;
 	toolCount?: number;
-	steerCount?: number;
-	lastSteerAt?: number;
+	steering?: SteeringStatus;
 	mode: SubagentRunMode;
 	cwd?: string;
 	startedAt: number;
@@ -67,6 +66,7 @@ export interface AsyncRunSummary {
 	timeoutMs?: number;
 	deadlineAt?: number;
 	timedOut?: boolean;
+	stopped?: boolean;
 	turnBudget?: TurnBudgetState;
 	turnBudgetExceeded?: boolean;
 	wrapUpRequested?: boolean;
@@ -178,8 +178,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.recentOutput ? { recentOutput: [...step.recentOutput] } : {}),
 			...(step.turnCount !== undefined ? { turnCount: step.turnCount } : {}),
 			...(step.toolCount !== undefined ? { toolCount: step.toolCount } : {}),
-			...(step.steerCount !== undefined ? { steerCount: step.steerCount } : {}),
-			...(step.lastSteerAt !== undefined ? { lastSteerAt: step.lastSteerAt } : {}),
+			...(step.steering ? { steering: step.steering } : {}),
 			...(step.durationMs !== undefined ? { durationMs: step.durationMs } : {}),
 			...(step.tokens ? { tokens: step.tokens } : {}),
 			...(step.totalCost ? { totalCost: step.totalCost } : {}),
@@ -189,6 +188,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 			...(step.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
 			...(step.error ? { error: step.error } : {}),
 			...(step.timedOut !== undefined ? { timedOut: step.timedOut } : {}),
+			...(step.stopped !== undefined ? { stopped: step.stopped } : {}),
 			...(step.turnBudget ? { turnBudget: step.turnBudget } : {}),
 			...(step.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: step.turnBudgetExceeded } : {}),
 			...(step.wrapUpRequested !== undefined ? { wrapUpRequested: step.wrapUpRequested } : {}),
@@ -209,8 +209,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		currentPath: status.currentPath,
 		turnCount: status.turnCount,
 		toolCount: status.toolCount,
-		steerCount: status.steerCount,
-		lastSteerAt: status.lastSteerAt,
+		steering: status.steering,
 		mode: status.mode,
 		cwd: status.cwd,
 		startedAt: status.startedAt,
@@ -219,6 +218,7 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 		...(status.timeoutMs !== undefined ? { timeoutMs: status.timeoutMs } : {}),
 		...(status.deadlineAt !== undefined ? { deadlineAt: status.deadlineAt } : {}),
 		...(status.timedOut !== undefined ? { timedOut: status.timedOut } : {}),
+		...(status.stopped !== undefined ? { stopped: status.stopped } : {}),
 		...(status.turnBudget ? { turnBudget: status.turnBudget } : {}),
 		...(status.turnBudgetExceeded !== undefined ? { turnBudgetExceeded: status.turnBudgetExceeded } : {}),
 		...(status.wrapUpRequested !== undefined ? { wrapUpRequested: status.wrapUpRequested } : {}),
@@ -237,12 +237,17 @@ function statusToSummary(asyncDir: string, status: AsyncStatus & { cwd?: string
 	};
 }
 
+export function summarizeAsyncStatus(asyncDir: string, status: AsyncStatus & { cwd?: string }): AsyncRunSummary {
+	return statusToSummary(asyncDir, status);
+}
+
 function sortRuns(runs: AsyncRunSummary[]): AsyncRunSummary[] {
 	const rank = (state: AsyncRunSummary["state"]): number => {
 		switch (state) {
 			case "running": return 0;
 			case "queued": return 1;
 			case "failed": return 2;
+			case "stopped": return 2;
 			case "paused": return 2;
 			case "complete": return 3;
 		}
@@ -294,11 +299,13 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 		if (options.sessionId && status.sessionId !== options.sessionId) continue;
 		const nestedWarnings: string[] = [];
 		let nestedRoute: NestedRoute | undefined;
-		try {
-			nestedRoute = resolveNestedRoute(status.runId || path.basename(asyncDir));
-			if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
-		} catch (error) {
-			nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
+		if (options.reconcile !== false) {
+			try {
+				nestedRoute = resolveNestedRoute(status.runId || path.basename(asyncDir));
+				if (nestedRoute) reconcileNestedAsyncDescendants(nestedRoute, { resultsDir: options.resultsDir, kill: options.kill, now: options.now });
+			} catch (error) {
+				nestedWarnings.push(`Nested status unavailable: ${getErrorMessage(error)}`);
+			}
 		}
 		const summary = statusToSummary(asyncDir, status, nestedWarnings, nestedRoute);
 		runs.push(summary);
@@ -308,18 +315,18 @@ export function listAsyncRuns(asyncDirRoot: string, options: AsyncRunListOptions
 	return options.limit !== undefined ? sorted.slice(0, options.limit) : sorted;
 }
 
-function formatActivityFacts(input: { activityState?: ActivityState; lastActivityAt?: number; currentTool?: string; currentToolStartedAt?: number; currentPath?: string; turnCount?: number; toolCount?: number; steerCount?: number; lastSteerAt?: number; turnBudget?: TurnBudgetState; turnBudgetExceeded?: boolean; wrapUpRequested?: boolean }): string | undefined {
+function formatActivityFacts(input: { activityState?: ActivityState; lastActivityAt?: number; currentTool?: string; currentToolStartedAt?: number; currentPath?: string; turnCount?: number; toolCount?: number; steering?: SteeringStatus; turnBudget?: TurnBudgetState; turnBudgetExceeded?: boolean; wrapUpRequested?: boolean }): string | undefined {
 	const facts: string[] = [];
 	if (input.currentTool && input.currentToolStartedAt !== undefined) facts.push(`tool ${input.currentTool} ${formatDuration(Math.max(0, Date.now() - input.currentToolStartedAt))}`);
 	else if (input.currentTool) facts.push(`tool ${input.currentTool}`);
 	if (input.currentPath) facts.push(shortenPath(input.currentPath));
 	if (input.turnCount !== undefined) facts.push(`${input.turnCount} turns`);
 	if (input.turnBudgetExceeded && input.turnBudget) facts.push(`turn budget exceeded ${input.turnBudget.turnCount}/${input.turnBudget.maxTurns}+${input.turnBudget.graceTurns}`);
+	else if (input.turnBudget?.outcome === "termination-deferred") facts.push(`turn-budget termination deferred ${input.turnBudget.turnCount}/${input.turnBudget.maxTurns}+${input.turnBudget.graceTurns}`);
 	else if (input.wrapUpRequested && input.turnBudget) facts.push(`wrap-up requested ${input.turnBudget.turnCount}/${input.turnBudget.maxTurns}`);
 	else if (input.turnBudget) facts.push(`turn budget ${input.turnBudget.turnCount}/${input.turnBudget.maxTurns}+${input.turnBudget.graceTurns}`);
 	if (input.toolCount !== undefined) facts.push(`${input.toolCount} tools`);
-	if (input.steerCount !== undefined) facts.push(`${input.steerCount} steers`);
-	if (typeof input.lastSteerAt === "number" && Number.isFinite(input.lastSteerAt)) facts.push(`last steer ${new Date(input.lastSteerAt).toISOString()}`);
+	if (input.steering) facts.push(`steering ${input.steering.scheduled} scheduled, ${input.steering.pending} pending, ${input.steering.delivered} delivered, ${input.steering.failed} failed, ${input.steering.recovered} recovered`);
 	const activity = formatActivityLabel(input.lastActivityAt, input.activityState);
 	return activity || facts.length ? [activity, ...facts].filter(Boolean).join(" | ") : undefined;
 }

package/src/runs/background/auto-drain.ts

@@ -0,0 +1,67 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { snapshotBackgroundWork } from "../../api/background-work.ts";
+import { ASYNC_DIR, RESULTS_DIR, type Details, type SubagentState } from "../../shared/types.ts";
+import { listAsyncRuns } from "./async-status.ts";
+import { waitForSubagents, type SubagentWaitDeps, type SubagentWaitParams, type WaitEventBus } from "./subagent-wait.ts";
+
+export const DEFAULT_AUTO_DRAIN_TIMEOUT_MS = 30 * 60 * 1000;
+
+export interface AutoDrainDeps {
+	state: SubagentState;
+	events?: WaitEventBus;
+	timeoutMs?: number;
+	now?: () => number;
+	wait?: (
+		params: SubagentWaitParams,
+		signal: AbortSignal | undefined,
+		deps: SubagentWaitDeps,
+	) => Promise<AgentToolResult<Details>>;
+	hasWork?: (sessionId: string, nowMs: number) => boolean;
+}
+
+function resultText(value: AgentToolResult<Details>): string {
+	return value.content.map((part) => part.type === "text" ? part.text : "").join(" ").trim();
+}
+
+function hasOutstandingWork(sessionId: string, nowMs: number): boolean {
+	const asyncRuns = listAsyncRuns(ASYNC_DIR, {
+		states: ["queued", "running"],
+		sessionId,
+		resultsDir: RESULTS_DIR,
+		now: () => nowMs,
+	});
+	return asyncRuns.length > 0 || snapshotBackgroundWork(sessionId, nowMs).items.length > 0;
+}
+
+/** Drain all work owned by the current headless session, including work added while draining. */
+export async function drainOutstandingWork(deps: AutoDrainDeps): Promise<void> {
+	const sessionId = deps.state.currentSessionId;
+	if (!sessionId) throw new Error("Cannot auto-drain background work without an active session identity.");
+	const now = deps.now ?? Date.now;
+	const timeoutMs = deps.timeoutMs ?? DEFAULT_AUTO_DRAIN_TIMEOUT_MS;
+	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("Auto-drain timeoutMs must be a positive finite number.");
+	const deadlineAt = now() + timeoutMs;
+	const hasWork = deps.hasWork ?? hasOutstandingWork;
+	const wait = deps.wait ?? waitForSubagents;
+
+	while (hasWork(sessionId, now())) {
+		const remainingMs = deadlineAt - now();
+		if (remainingMs <= 0) {
+			throw new Error(`Auto-drain timed out after ${timeoutMs}ms with background work still active in session '${sessionId}'.`);
+		}
+		const waitResult = await wait(
+			{ all: true, timeoutMs: remainingMs },
+			undefined,
+			{
+				state: deps.state,
+				events: deps.events,
+				now,
+				stopOnAttention: false,
+				failOnFailedRuns: true,
+			},
+		);
+		if (waitResult.isError) {
+			throw new Error(`Auto-drain failed for session '${sessionId}': ${resultText(waitResult) || "subagent_wait returned an error without details"}.`);
+		}
+	}
+}

package/src/runs/background/chain-root-attachment.ts

@@ -27,6 +27,7 @@ export interface ImportedAsyncRootResult {
 	structuredOutputSchemaPath?: string;
 	acceptance?: AcceptanceLedger;
 	timedOut?: boolean;
+	stopped?: boolean;
 }
 
 interface AsyncResultFile {
@@ -35,12 +36,14 @@ interface AsyncResultFile {
 	summary?: string;
 	error?: string;
 	timedOut?: boolean;
+	stopped?: boolean;
 	results?: Array<{
 		agent?: string;
 		output?: string;
 		error?: string;
 		success?: boolean;
 		timedOut?: boolean;
+		stopped?: boolean;
 		sessionFile?: string;
 		intercomTarget?: string;
 		model?: string;
@@ -54,8 +57,8 @@ interface AsyncResultFile {
 	}>;
 }
 
-const TERMINAL_STATES = new Set(["complete", "failed", "paused"]);
-const TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "paused"]);
+const TERMINAL_STATES = new Set(["complete", "failed", "paused", "stopped"]);
+const TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "paused", "stopped"]);
 
 function readResultFile(resultPath: string): AsyncResultFile | undefined {
 	try {
@@ -79,11 +82,12 @@ function isTerminalStatus(status: AsyncStatus | null, index: number): boolean {
 	return TERMINAL_STATES.has(status.state);
 }
 
-function resultState(result: AsyncResultFile | undefined, child: NonNullable<AsyncResultFile["results"]>[number] | undefined): "complete" | "failed" | "paused" | undefined {
+function resultState(result: AsyncResultFile | undefined, child: NonNullable<AsyncResultFile["results"]>[number] | undefined): "complete" | "failed" | "paused" | "stopped" | undefined {
 	if (!result) return undefined;
+	if (child?.stopped === true) return "stopped";
 	if (child?.success === true) return "complete";
-	if (child?.success === false) return result.state === "paused" ? "paused" : "failed";
-	if (result.state === "complete" || result.state === "failed" || result.state === "paused") return result.state;
+	if (child?.success === false) return result.state === "stopped" ? "stopped" : result.state === "paused" ? "paused" : "failed";
+	if (result.state === "complete" || result.state === "failed" || result.state === "paused" || result.state === "stopped") return result.state;
 	if (result.success === true) return "complete";
 	if (result.success === false) return "failed";
 	return undefined;
@@ -92,7 +96,8 @@ function resultState(result: AsyncResultFile | undefined, child: NonNullable<Asy
 function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus, step: NonNullable<AsyncStatus["steps"]>[number] | undefined): ImportedAsyncRootResult {
 	const agent = step?.agent ?? status.steps?.[root.index]?.agent ?? "subagent";
 	const timedOut = step?.timedOut === true || status.timedOut === true;
-	const message = step?.error ?? status.error ?? `Attached async root ${root.runId} ended without a result file at ${root.resultPath}.`;
+	const stopped = step?.stopped === true || status.stopped === true || status.state === "stopped";
+	const message = step?.error ?? status.error ?? (stopped ? "Subagent stopped by user." : `Attached async root ${root.runId} ended without a result file at ${root.resultPath}.`);
 	return {
 		agent,
 		output: message,
@@ -100,6 +105,7 @@ function outputFromTerminalStatus(root: ImportedAsyncRoot, status: AsyncStatus,
 		exitCode: 1,
 		error: message,
 		...(timedOut ? { timedOut: true } : {}),
+		...(stopped ? { stopped: true } : {}),
 		...(step?.sessionFile ?? status.sessionFile ? { sessionFile: step?.sessionFile ?? status.sessionFile } : {}),
 		...(step?.model ? { model: step.model } : {}),
 		...(step?.attemptedModels ? { attemptedModels: step.attemptedModels } : {}),
@@ -136,8 +142,9 @@ function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null
 	const agent = child?.agent ?? step?.agent ?? status?.steps?.[root.index]?.agent ?? "subagent";
 	const output = child?.output ?? result.summary ?? "";
 	const timedOut = child?.timedOut === true || step?.timedOut === true || result.timedOut === true || status?.timedOut === true;
-	const success = state === "complete" && !timedOut;
-	const error = child?.error ?? (success ? undefined : result.error ?? result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
+	const stopped = child?.stopped === true || step?.stopped === true || result.stopped === true || status?.stopped === true || state === "stopped";
+	const success = state === "complete" && !timedOut && !stopped;
+	const error = child?.error ?? (success ? undefined : stopped ? "Subagent stopped by user." : result.error ?? result.summary ?? status?.error ?? `Attached async root ${root.runId} did not complete successfully.`);
 	return {
 		agent,
 		output: success ? output : (output || error || ""),
@@ -145,6 +152,7 @@ function buildImportedResult(root: ImportedAsyncRoot, status: AsyncStatus | null
 		exitCode: success ? 0 : 1,
 		...(error ? { error } : {}),
 		...(timedOut ? { timedOut: true } : {}),
+		...(stopped ? { stopped: true } : {}),
 		...(child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile ? { sessionFile: child?.sessionFile ?? step?.sessionFile ?? status?.sessionFile } : {}),
 		...(child?.intercomTarget ? { intercomTarget: child.intercomTarget } : {}),
 		...(child?.model ?? step?.model ? { model: child?.model ?? step?.model } : {}),