pi-subagents 0.69.0 → 0.70.1

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

@@ -1,354 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { randomUUID } from "node:crypto";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { listAsyncRuns, type AsyncRunSummary } from "./async-status.ts";
-import { formatResumeFirstFailedRunDetail } from "./resume-guidance.ts";
-import { readCompletionReplay } from "./completion-replay.ts";
-import { writeAtomicJson } from "../../shared/atomic-json.ts";
-import {
-	DIRS,
-	INTERCOM_DETACH_REQUEST_EVENT,
-	SUBAGENT_ASYNC_COMPLETE_EVENT,
-	SUBAGENT_CONTROL_EVENT,
-	SUBAGENT_CONTROL_INTERCOM_EVENT,
-	SUBAGENT_FOREGROUND_COMPLETE_EVENT,
-	SUBAGENT_RESULT_INTERCOM_EVENT,
-	type SubagentState,
-	type WaitCompletion,
-	type WaitSubscriptionRecord,
-} from "../../shared/types.ts";
-
-const SUBSCRIPTION_VERSION = 1;
-const RECONCILE_INTERVAL_MS = 1_000;
-/**
- * How often the subscriptions directory is re-scanned for expired records left
- * by other sessions. Rare compared to RECONCILE_INTERVAL_MS because it costs a
- * directory read, and nothing depends on the sweep being prompt.
- */
-const FOREIGN_SWEEP_INTERVAL_MS = 60_000;
-/**
- * How far past expiry a record armed by another session is kept before it is
- * swept. The owning session settles its own expired records with a "timed out"
- * notice on the next restore(), so removing one the moment it expires would take
- * that notice away from a session that simply had not resumed yet. A day is long
- * enough for an ordinary return and short enough to bound the directory.
- */
-const FOREIGN_SWEEP_GRACE_MS = 24 * 60 * 60 * 1000;
-
-export interface ArmWaitSubscriptionInput {
-	targetKind: "async" | "foreground";
-	runId: string;
-	requestedId: string;
-	timeoutMs: number;
-}
-
-export interface WaitSubscriptionManager {
-	start(): void;
-	arm(input: ArmWaitSubscriptionInput): WaitSubscriptionRecord;
-	restore(): void;
-	reconcile(): void;
-	dispose(): void;
-}
-
-interface WaitSubscriptionManagerOptions {
-	asyncDirRoot?: string;
-	resultsDir?: string;
-	subscriptionsDir?: string;
-	now?: () => number;
-	pollIntervalMs?: number;
-	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
-}
-
-function isNotFound(error: unknown): boolean {
-	return typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT";
-}
-
-function parseRecord(value: unknown): WaitSubscriptionRecord | undefined {
-	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
-	const record = value as Partial<WaitSubscriptionRecord>;
-	if (record.version !== SUBSCRIPTION_VERSION
-		|| typeof record.token !== "string"
-		|| !/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(record.token)
-		|| typeof record.sessionId !== "string"
-		|| (record.targetKind !== "async" && record.targetKind !== "foreground")
-		|| typeof record.runId !== "string"
-		|| typeof record.requestedId !== "string"
-		|| typeof record.createdAt !== "number"
-		|| typeof record.expiresAt !== "number") return undefined;
-	return record as WaitSubscriptionRecord;
-}
-
-function needsAttention(run: AsyncRunSummary): boolean {
-	return run.activityState === "needs_attention" || run.steps.some((step) => step.activityState === "needs_attention");
-}
-
-function subscriptionFile(dir: string, token: string): string {
-	return path.join(dir, `${token}.json`);
-}
-
-export function formatWaitSubscriptions(state: Pick<SubagentState, "waitSubscriptions">, now = Date.now()): string | undefined {
-	const subscriptions = [...(state.waitSubscriptions?.values() ?? [])].sort((left, right) => left.createdAt - right.createdAt);
-	if (subscriptions.length === 0) return undefined;
-	const lines = [`Armed wait subscriptions (${subscriptions.length}):`];
-	for (const record of subscriptions) {
-		lines.push(`- ${record.token}: ${record.targetKind} run ${record.runId}, timeout in ${Math.max(0, record.expiresAt - now)}ms`);
-	}
-	return lines.join("\n");
-}
-
-export function createWaitSubscriptionManager(
-	pi: Pick<ExtensionAPI, "events" | "sendMessage">,
-	state: SubagentState,
-	options: WaitSubscriptionManagerOptions = {},
-): WaitSubscriptionManager {
-	const asyncDirRoot = options.asyncDirRoot ?? DIRS.async;
-	const resultsDir = options.resultsDir ?? DIRS.results;
-	const subscriptionsDir = options.subscriptionsDir ?? path.join(path.dirname(asyncDirRoot), "wait-subscriptions");
-	const now = options.now ?? Date.now;
-	const subscriptions = state.waitSubscriptions ?? new Map<string, WaitSubscriptionRecord>();
-	state.waitSubscriptions = subscriptions;
-	const unresolvedRestoredForegroundTokens = new Set<string>();
-	let disposed = false;
-	let interval: ReturnType<typeof setInterval> | undefined;
-	let lastForeignSweepAt = 0;
-
-	/**
-	 * Remove expired records armed by another session.
-	 *
-	 * Only the owning session can be woken, so restore() never loads a foreign
-	 * record into `subscriptions` and reconcileRecord() returns before its
-	 * timeout branch. Nothing reconciles such a record and nothing expires it, so
-	 * a session that arms a wait and never comes back (forked, renamed, deleted)
-	 * leaves one file here per wait, forever.
-	 *
-	 * Kept for FOREIGN_SWEEP_GRACE_MS past expiry so an owner that resumes late
-	 * still finds its record and gets the timeout notice.
-	 *
-	 * Runs on the reconcile timer as well as at restore(), because a record that
-	 * is still live when another session starts would otherwise never be looked
-	 * at again: restore() only fires on session_start, and reconcile() walks the
-	 * in-memory map, which holds current-session records only. A host that keeps
-	 * one session open for hours is exactly where that gap bites.
-	 *
-	 * Never throws: it runs from the reconcile timer.
-	 */
-	const sweepExpiredForeignSubscriptions = (force = false) => {
-		const sweptAt = now();
-		if (!force && sweptAt - lastForeignSweepAt < FOREIGN_SWEEP_INTERVAL_MS) return;
-		lastForeignSweepAt = sweptAt;
-		let files: string[];
-		try {
-			files = fs.readdirSync(subscriptionsDir).filter((file) => file.endsWith(".json"));
-		} catch (error) {
-			if (!isNotFound(error)) console.error(`Failed to scan wait subscriptions in '${subscriptionsDir}':`, error);
-			return;
-		}
-		for (const file of files) {
-			const filePath = path.join(subscriptionsDir, file);
-			let record: WaitSubscriptionRecord | undefined;
-			try {
-				record = parseRecord(JSON.parse(fs.readFileSync(filePath, "utf-8")));
-			} catch (error) {
-				console.error(`Ignoring invalid wait subscription '${filePath}':`, error);
-				continue;
-			}
-			if (!record || file !== `${record.token}.json`) continue;
-			// The owning session keeps its own expired records so reconcileRecord()
-			// can still settle them with the "timed out" notice callers expect.
-			if (record.sessionId === state.currentSessionId) continue;
-			if (sweptAt < record.expiresAt + FOREIGN_SWEEP_GRACE_MS) continue;
-			try {
-				fs.unlinkSync(filePath);
-			} catch (error) {
-				// Losing this race is harmless: another session may have swept the
-				// same expired record. Anything else is reported and retried on the
-				// next sweep rather than interrupting the caller.
-				if (!isNotFound(error)) console.error(`Failed to remove expired wait subscription '${filePath}':`, error);
-			}
-		}
-	};
-
-	const remove = (record: WaitSubscriptionRecord) => {
-		try {
-			fs.unlinkSync(subscriptionFile(subscriptionsDir, record.token));
-		} catch (error) {
-			if (!isNotFound(error)) throw error;
-		}
-		subscriptions.delete(record.token);
-		unresolvedRestoredForegroundTokens.delete(record.token);
-	};
-
-	const settle = (record: WaitSubscriptionRecord, outcome: string, detail: string, completion?: WaitCompletion) => {
-		if (disposed || state.currentSessionId !== record.sessionId) return;
-		try {
-			remove(record);
-		} catch (error) {
-			console.error(`Failed to clear wait subscription '${record.token}'; it remains armed:`, error);
-			return;
-		}
-		try {
-			pi.sendMessage({
-				customType: "subagent-wait-subscription",
-				content: `Wait subscription ${record.token} fired for run ${record.runId}: ${outcome}. ${detail}`,
-				display: true,
-				details: {
-					token: record.token,
-					runId: record.runId,
-					outcome,
-					...(completion ? { completions: [completion] } : {}),
-				},
-			}, { triggerTurn: true });
-		} catch (error) {
-			console.error(`Failed to deliver wait subscription '${record.token}' after clearing it:`, error);
-		}
-	};
-
-	const reconcileRecord = (record: WaitSubscriptionRecord) => {
-		if (record.sessionId !== state.currentSessionId) return;
-		if (now() >= record.expiresAt) {
-			settle(record, "timed out", "The targeted run may still be active; inspect its status before taking follow-up action.");
-			return;
-		}
-		if (record.targetKind === "foreground") {
-			const run = state.foregroundRuns?.get(record.runId);
-			if (!run && unresolvedRestoredForegroundTokens.has(record.token)) return;
-			if (run) unresolvedRestoredForegroundTokens.delete(record.token);
-			if (!run || run.sessionId !== record.sessionId) {
-				settle(record, "could not be reconciled", "The remembered foreground run disappeared before completion was confirmed.");
-				return;
-			}
-			const detached = run.children.filter((child) => child.status === "detached");
-			if (detached.some((child) => child.activityState === "needs_attention" && child.currentTool === "contact_supervisor")) {
-				settle(record, "needs attention", "Reply to the pending supervisor request or inspect the run status.");
-				return;
-			}
-			if (detached.length === 0) {
-				const failed = run.children.some((child) => child.status === "failed");
-				settle(record, failed ? "failed" : "completed", "Inspect the run status for its final output.");
-			}
-			return;
-		}
-
-		const runs = listAsyncRuns(asyncDirRoot, {
-			sessionId: record.sessionId,
-			runId: record.runId,
-			exactRunId: true,
-			resultsDir,
-			kill: options.kill,
-			now,
-		});
-		const run = runs.find((candidate) => candidate.id === record.runId);
-		if (!run) {
-			settle(record, "could not be reconciled", "The exact async run disappeared before a terminal result was confirmed.");
-			return;
-		}
-		if (needsAttention(run)) {
-			settle(record, "needs attention", "Inspect the run status and answer any pending supervisor request.");
-			return;
-		}
-		if (run.state !== "queued" && run.state !== "running") {
-			let completion: WaitCompletion | undefined;
-			try {
-				completion = readCompletionReplay(resultsDir, record.runId, { sessionId: record.sessionId, now: now() })?.completion;
-			} catch (error) {
-				console.error(`Failed to read completion replay for wait subscription '${record.token}':`, error);
-			}
-			const detail = formatResumeFirstFailedRunDetail(run) ?? "Inspect the run status for its final output.";
-			const archiveDetail = completion?.archivePath ? ` Completion archive: ${completion.archivePath}.` : "";
-			settle(record, run.state === "complete" ? "completed" : run.state, `${detail}${archiveDetail}`, completion);
-		}
-	};
-
-	const reconcile = () => {
-		if (disposed) return;
-		// Before the session check: with no current session every record is
-		// foreign, and expired ones should still be cleaned up.
-		sweepExpiredForeignSubscriptions();
-		if (!state.currentSessionId) return;
-		for (const record of [...subscriptions.values()]) {
-			try {
-				reconcileRecord(record);
-			} catch (error) {
-				console.error(`Failed to reconcile wait subscription '${record.token}':`, error);
-				settle(record, "reconciliation failed", "The targeted run could not be reconciled. Inspect its status before taking follow-up action.");
-			}
-		}
-	};
-
-	const wakeChannels = [
-		INTERCOM_DETACH_REQUEST_EVENT,
-		SUBAGENT_ASYNC_COMPLETE_EVENT,
-		SUBAGENT_FOREGROUND_COMPLETE_EVENT,
-		SUBAGENT_CONTROL_EVENT,
-		SUBAGENT_CONTROL_INTERCOM_EVENT,
-		SUBAGENT_RESULT_INTERCOM_EVENT,
-	];
-	const unsubscribes = wakeChannels.map((channel) => pi.events.on(channel, reconcile));
-
-	return {
-		start() {
-			if (disposed || interval) return;
-			interval = setInterval(reconcile, options.pollIntervalMs ?? RECONCILE_INTERVAL_MS);
-			interval.unref?.();
-		},
-		arm(input) {
-			const sessionId = state.currentSessionId;
-			if (!sessionId) throw new Error("A wait subscription requires an active session identity.");
-			const createdAt = now();
-			const record: WaitSubscriptionRecord = {
-				version: SUBSCRIPTION_VERSION,
-				token: randomUUID(),
-				sessionId,
-				targetKind: input.targetKind,
-				runId: input.runId,
-				requestedId: input.requestedId,
-				createdAt,
-				expiresAt: createdAt + input.timeoutMs,
-			};
-			fs.mkdirSync(subscriptionsDir, { recursive: true });
-			writeAtomicJson(subscriptionFile(subscriptionsDir, record.token), record);
-			subscriptions.set(record.token, record);
-			return record;
-		},
-		restore() {
-			subscriptions.clear();
-			unresolvedRestoredForegroundTokens.clear();
-			// Unconditional: a process that starts without a session identity should
-			// still clear records nobody can act on.
-			sweepExpiredForeignSubscriptions(true);
-			if (!state.currentSessionId) return;
-			let files: string[];
-			try {
-				files = fs.readdirSync(subscriptionsDir).filter((file) => file.endsWith(".json"));
-			} catch (error) {
-				if (isNotFound(error)) return;
-				throw error;
-			}
-			for (const file of files) {
-				try {
-					const record = parseRecord(JSON.parse(fs.readFileSync(path.join(subscriptionsDir, file), "utf-8")));
-					if (!record || file !== `${record.token}.json`) continue;
-					if (record.sessionId === state.currentSessionId) {
-						subscriptions.set(record.token, record);
-						if (record.targetKind === "foreground" && !state.foregroundRuns?.has(record.runId)) unresolvedRestoredForegroundTokens.add(record.token);
-					}
-				} catch (error) {
-					console.error(`Ignoring invalid wait subscription '${path.join(subscriptionsDir, file)}':`, error);
-				}
-			}
-			reconcile();
-		},
-		reconcile,
-		dispose() {
-			if (disposed) return;
-			disposed = true;
-			if (interval) clearInterval(interval);
-			interval = undefined;
-			for (const unsubscribe of unsubscribes) {
-				try { unsubscribe(); } catch { /* best effort */ }
-			}
-			subscriptions.clear();
-		},
-	};
-}

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

@@ -1,45 +0,0 @@
-import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { SubagentWaitParams } from "../../extension/schemas.ts";
-import type { Details, SubagentState } from "../../shared/types.ts";
-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">,
-	defaultTimeoutMs?: number,
-	child?: { nestedRootRunId?: string },
-): void {
-	const description = `Wait for background, provider, or detached work that has no native completion notification, then return.
-
-${child ? "This child runtime does not install the root session's native completion notifier. Use blocking bg_wait to collect your owned descendants during this turn, then read the returned result references before synthesizing findings. Automatic draining at agent_end keeps owned work alive but does not synthesize its results." : "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, 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). Named async runs that already finished return their terminal result references.
-• { 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.
-• { 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 \`bg_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: bg_wait is disabled by config.waitTool or PI_SUBAGENT_WAIT_TOOL_ENABLED and returns immediately without blocking."}`;
-	const execute: ToolDefinition<typeof SubagentWaitParams, Details>["execute"] = async (_id, params, signal, onUpdate, ctx) => finalizeToolResult(await waitForSubagents(params, signal, {
-		state,
-		nestedRootRunId: child?.nestedRootRunId,
-		events: pi.events,
-		enabled,
-		...(defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {}),
-		onUpdate,
-		...(subscriptions && ctx?.hasUI ? { subscribe: (input) => subscriptions.arm(input) } : {}),
-	}));
-	const primaryTool: ToolDefinition<typeof SubagentWaitParams, Details> = {
-		name: "bg_wait",
-		label: "Background Wait",
-		description,
-		parameters: SubagentWaitParams,
-		execute,
-	};
-	pi.registerTool(primaryTool);
-}

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

@@ -1,86 +0,0 @@
-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 { DIRS, type Details, type SubagentState } from "../../shared/types.ts";
-import { readStatus } from "../../shared/utils.ts";
-import { updateActiveRunIndex } from "../background/active-run-index.ts";
-import { reconcileAsyncRun } from "../background/stale-run-reconciler.ts";
-import { resultFilePath } from "../background/result-files.ts";
-
-export function dismissRecoveredWorkflow(
-	state: SubagentState,
-	location: { asyncDir: string | null; resolvedId?: string },
-): AgentToolResult<Details> {
-	const asyncDir = location.asyncDir;
-	const runId = location.resolvedId ?? (asyncDir ? path.basename(asyncDir) : "requested");
-	if (!asyncDir) {
-		return {
-			content: [{ type: "text", text: `Recovered workflow '${runId}' has no disk status to dismiss.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	const status = readStatus(asyncDir);
-	if (!status || status.mode !== "workflow") {
-		return {
-			content: [{ type: "text", text: `Run '${runId}' is not a recovered workflow.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	if (!state.currentSessionId || status.sessionId !== state.currentSessionId) {
-		return {
-			content: [{ type: "text", text: `Recovered workflow '${runId}' was not found in the active session.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	if (state.workflowControllers?.has(status.runId) || state.workflowControllers?.has(runId)) {
-		return {
-			content: [{ type: "text", text: `Workflow '${runId}' still has a live controller and cannot be dismissed.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	if (status.state !== "running") {
-		return {
-			content: [{ type: "text", text: `Recovered workflow '${runId}' is ${status.state}, not running.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	let latestStatus = status;
-	const resultPath = resultFilePath(DIRS.results, status.runId);
-	if (fs.existsSync(resultPath)) {
-		const reconciled = reconcileAsyncRun(asyncDir).status;
-		if (reconciled && reconciled.state !== "running") {
-			return {
-				content: [{ type: "text", text: `Recovered workflow '${runId}' is ${reconciled.state}, not running.` }],
-				isError: true,
-				details: { mode: "management", results: [] },
-			};
-		}
-		if (reconciled) latestStatus = reconciled;
-	}
-
-	const dismissed = { ...latestStatus, displayDismissedAt: Date.now() };
-	writeAtomicJson(path.join(asyncDir, "status.json"), dismissed);
-	const repaired = reconcileAsyncRun(asyncDir).status;
-	if (repaired && repaired.state !== "running") {
-		return {
-			content: [{ type: "text", text: `Recovered workflow '${runId}' is ${repaired.state}, not running.` }],
-			isError: true,
-			details: { mode: "management", results: [] },
-		};
-	}
-	updateActiveRunIndex(asyncDir, "complete");
-	state.asyncJobs.delete(status.runId);
-	state.asyncJobs.delete(runId);
-	state.fleetJobs?.delete(status.runId);
-	state.fleetJobs?.delete(runId);
-	return {
-		content: [{ type: "text", text: `Dismissed recovered workflow ${status.runId} from the display. No running work was terminated.` }],
-		details: { mode: "management", results: [] },
-	};
-}