@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/subagents/src/runs/background/result-watcher.ts

@@ -0,0 +1,250 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { buildCompletionKey, markSeenWithTtl } from "./completion-dedupe.ts";
+import { createFileCoalescer } from "../../shared/file-coalescer.ts";
+import {
+	SUBAGENT_ASYNC_COMPLETE_EVENT,
+	type IntercomEventBus,
+	type SubagentState,
+} from "../../shared/types.ts";
+import {
+	buildSubagentResultIntercomPayload,
+	deliverSubagentResultIntercomEvent,
+	resolveSubagentResultStatus,
+} from "../../intercom/result-intercom.ts";
+
+const WATCHER_RESTART_DELAY_MS = 3000;
+const POLL_INTERVAL_MS = 3000;
+
+type ResultWatcherFs = Pick<typeof fs, "existsSync" | "readFileSync" | "unlinkSync" | "readdirSync" | "mkdirSync" | "watch">;
+
+type ResultWatcherTimers = {
+	setTimeout: typeof setTimeout;
+	clearTimeout: typeof clearTimeout;
+	setInterval: typeof setInterval;
+	clearInterval: typeof clearInterval;
+};
+
+type ResultWatcherDeps = {
+	fs?: ResultWatcherFs;
+	timers?: ResultWatcherTimers;
+};
+
+function getErrorCode(error: unknown): string | undefined {
+	return typeof error === "object" && error !== null && "code" in error
+		? (error as NodeJS.ErrnoException).code
+		: undefined;
+}
+
+function isNotFoundError(error: unknown): boolean {
+	return getErrorCode(error) === "ENOENT";
+}
+
+function shouldFallBackToPolling(error: unknown): boolean {
+	const code = getErrorCode(error);
+	return code === "EMFILE" || code === "ENOSPC";
+}
+
+export function createResultWatcher(
+	pi: { events: IntercomEventBus },
+	state: SubagentState,
+	resultsDir: string,
+	completionTtlMs: number,
+	deps: ResultWatcherDeps = {},
+): {
+	startResultWatcher: () => void;
+	primeExistingResults: () => void;
+	stopResultWatcher: () => void;
+} {
+	const fsApi = deps.fs ?? fs;
+	const timers = deps.timers ?? { setTimeout, clearTimeout, setInterval, clearInterval };
+
+	const handleResult = async (file: string) => {
+		const resultPath = path.join(resultsDir, file);
+		if (!fsApi.existsSync(resultPath)) return;
+		try {
+			const data = JSON.parse(fsApi.readFileSync(resultPath, "utf-8")) as {
+				id?: string;
+				runId?: string;
+				agent?: string;
+				success?: boolean;
+				state?: string;
+				mode?: string;
+				summary?: string;
+				results?: Array<{
+					agent?: string;
+					output?: string;
+					error?: string;
+					success?: boolean;
+					sessionFile?: string;
+					artifactPaths?: { outputPath?: string };
+					intercomTarget?: string;
+				}>;
+				sessionId?: string;
+				cwd?: string;
+				sessionFile?: string;
+				asyncDir?: string;
+				intercomTarget?: string;
+			};
+			if (data.sessionId && data.sessionId !== state.currentSessionId) return;
+			if (!data.sessionId && data.cwd && (!state.baseCwd || data.cwd !== state.baseCwd)) return;
+
+			const now = Date.now();
+			const completionKey = buildCompletionKey(data, `result:${file}`);
+			if (markSeenWithTtl(state.completionSeen, completionKey, now, completionTtlMs)) {
+				fsApi.unlinkSync(resultPath);
+				return;
+			}
+
+			const intercomTarget = data.intercomTarget?.trim();
+			if (intercomTarget) {
+				const childResults = Array.isArray(data.results) && data.results.length > 0
+					? data.results
+					: [{
+						agent: data.agent,
+						output: data.summary,
+						success: data.success,
+					}];
+				const runId = data.runId ?? data.id ?? file.replace(/\.json$/i, "");
+				const mode = data.mode === "single" || data.mode === "parallel" || data.mode === "chain"
+					? data.mode
+					: childResults.length > 1 ? "chain" : "single";
+				const payload = buildSubagentResultIntercomPayload({
+					to: intercomTarget,
+					runId,
+					mode,
+					source: "async",
+					children: childResults.map((result = {}, index) => {
+						const baseOutput = result.output ?? data.summary;
+						const hasRealOutput = typeof baseOutput === "string" && baseOutput.trim().length > 0;
+						const output = hasRealOutput ? baseOutput : "(no output)";
+						const summary = result.success === false && result.error
+							? `${result.error}${hasRealOutput ? `\n\nOutput:\n${baseOutput}` : ""}`
+							: output;
+						const sessionPath = result.sessionFile ?? (childResults.length === 1 ? data.sessionFile : undefined);
+						return {
+							agent: result.agent ?? data.agent ?? `step-${index + 1}`,
+							status: resolveSubagentResultStatus({
+								success: result.success,
+								state: data.state === "paused" || typeof result.success !== "boolean" ? data.state : undefined,
+							}),
+							summary,
+							index,
+							artifactPath: result.artifactPaths?.outputPath,
+							...(typeof sessionPath === "string" && fsApi.existsSync(sessionPath) ? { sessionPath } : {}),
+							intercomTarget: result.intercomTarget,
+						};
+					}),
+					asyncId: data.id,
+					asyncDir: data.asyncDir,
+				});
+				const delivered = await deliverSubagentResultIntercomEvent(pi.events, payload);
+				if (!delivered) {
+					console.error(`Subagent async grouped result intercom delivery was not acknowledged for '${resultPath}'.`);
+				}
+			}
+
+			pi.events.emit(SUBAGENT_ASYNC_COMPLETE_EVENT, data);
+			fsApi.unlinkSync(resultPath);
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			console.error(`Failed to process subagent result file '${resultPath}':`, error);
+		}
+	};
+
+	state.resultFileCoalescer = createFileCoalescer((file) => {
+		void handleResult(file);
+	}, 50);
+
+	const primeExistingResults = () => {
+		try {
+			fsApi.readdirSync(resultsDir)
+				.filter((f) => f.endsWith(".json"))
+				.forEach((file) => state.resultFileCoalescer.schedule(file, 0));
+		} catch (error) {
+			if (isNotFoundError(error)) return;
+			console.error(`Failed to scan subagent result directory '${resultsDir}':`, error);
+		}
+	};
+
+	const startPollingFallback = (reason: unknown) => {
+		state.watcher?.close();
+		state.watcher = null;
+		if (state.watcherRestartTimer) return;
+
+		console.error(
+			`Subagent result watcher for '${resultsDir}' fell back to polling because native fs.watch is unavailable (${getErrorCode(reason) ?? "unknown error"}).`,
+		);
+		primeExistingResults();
+		state.watcherRestartTimer = timers.setInterval(primeExistingResults, POLL_INTERVAL_MS);
+		state.watcherRestartTimer.unref?.();
+	};
+
+	const scheduleRestart = () => {
+		if (state.watcherRestartTimer) return;
+		state.watcherRestartTimer = timers.setTimeout(() => {
+			state.watcherRestartTimer = null;
+			try {
+				fsApi.mkdirSync(resultsDir, { recursive: true });
+				startResultWatcher();
+			} catch (error) {
+				if (shouldFallBackToPolling(error)) {
+					startPollingFallback(error);
+					return;
+				}
+				console.error(`Failed to restart subagent result watcher for '${resultsDir}':`, error);
+				scheduleRestart();
+			}
+		}, WATCHER_RESTART_DELAY_MS);
+		state.watcherRestartTimer.unref?.();
+	};
+
+	const startResultWatcher = () => {
+		if (state.watcher) return;
+		if (state.watcherRestartTimer) {
+			timers.clearTimeout(state.watcherRestartTimer);
+			timers.clearInterval(state.watcherRestartTimer);
+			state.watcherRestartTimer = null;
+		}
+		try {
+			state.watcher = fsApi.watch(resultsDir, (ev, file) => {
+				if (ev !== "rename" || !file) return;
+				const fileName = file.toString();
+				if (!fileName.endsWith(".json")) return;
+				state.resultFileCoalescer.schedule(fileName);
+			});
+			state.watcher.on("error", (error) => {
+				if (shouldFallBackToPolling(error)) {
+					startPollingFallback(error);
+					return;
+				}
+				console.error(`Subagent result watcher failed for '${resultsDir}':`, error);
+				state.watcher?.close();
+				state.watcher = null;
+				scheduleRestart();
+			});
+			state.watcher.unref?.();
+		} catch (error) {
+			if (shouldFallBackToPolling(error)) {
+				startPollingFallback(error);
+				return;
+			}
+			console.error(`Failed to start subagent result watcher for '${resultsDir}':`, error);
+			state.watcher = null;
+			scheduleRestart();
+		}
+	};
+
+	const stopResultWatcher = () => {
+		state.watcher?.close();
+		state.watcher = null;
+		if (state.watcherRestartTimer) {
+			timers.clearTimeout(state.watcherRestartTimer);
+			timers.clearInterval(state.watcherRestartTimer);
+		}
+		state.watcherRestartTimer = null;
+		state.resultFileCoalescer.clear();
+	};
+
+	return { startResultWatcher, primeExistingResults, stopResultWatcher };
+}

package/dist/builtin/subagents/src/runs/background/run-status.ts

@@ -0,0 +1,193 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { formatAsyncRunList, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, listAsyncRuns } from "./async-status.ts";
+import { formatModelThinking } from "../../shared/formatters.ts";
+import { formatActivityLabel } from "../../shared/status-format.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type Details } from "../../shared/types.ts";
+import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
+import { resolveAsyncRunLocation } from "./async-resume.ts";
+import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
+import { reconcileAsyncRun } from "./stale-run-reconciler.ts";
+
+interface RunStatusParams {
+	action?: "status";
+	id?: string;
+	runId?: string;
+	dir?: string;
+}
+
+interface RunStatusDeps {
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+}
+
+function hasExistingSessionFile(value: unknown): value is string {
+	return typeof value === "string" && fs.existsSync(value);
+}
+
+function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown): string {
+	const knownChildren = children
+		.map((child, index) => ({ child, index }))
+		.filter(({ child }) => typeof child.agent === "string");
+	if (!runId || knownChildren.length === 0) return "Resume: unavailable; no child session file was persisted.";
+	const singleSessionFile = knownChildren[0]?.child.sessionFile ?? fallbackSessionFile;
+	if (children.length === 1 && knownChildren.length === 1 && hasExistingSessionFile(singleSessionFile)) {
+		return `Revive: subagent({ action: "resume", id: "${runId}", message: "..." })`;
+	}
+	const childWithSession = knownChildren.find(({ child }) => hasExistingSessionFile(child.sessionFile));
+	if (childWithSession) {
+		return `Revive child: subagent({ action: "resume", id: "${runId}", index: ${childWithSession.index}, message: "..." })`;
+	}
+	return "Resume: unavailable; no child session file was persisted.";
+}
+
+function stepLineLabel(status: AsyncStatus, index: number): string {
+	const steps = status.steps ?? [];
+	if (status.mode === "parallel") return `Agent ${index + 1}/${steps.length || 1}`;
+	if (status.mode === "chain") {
+		const chainStepCount = status.chainStepCount ?? (steps.length || 1);
+		const groups = normalizeParallelGroups(status.parallelGroups, steps.length, chainStepCount);
+		const group = groups.find((candidate) => index >= candidate.start && index < candidate.start + candidate.count);
+		if (group) return `Step ${group.stepIndex + 1}/${chainStepCount} Agent ${index - group.start + 1}/${group.count}`;
+		return `Step ${flatToLogicalStepIndex(index, chainStepCount, groups) + 1}/${chainStepCount}`;
+	}
+	return `Step ${index + 1}`;
+}
+
+export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDeps = {}): AgentToolResult<Details> {
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	if (!params.id && !params.runId && !params.dir) {
+		try {
+			const runs = listAsyncRuns(asyncDirRoot, { states: ["queued", "running"], resultsDir, kill: deps.kill, now: deps.now });
+			return {
+				content: [{ type: "text", text: formatAsyncRunList(runs) }],
+				details: { mode: "single", results: [] },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	let location;
+	try {
+		location = resolveAsyncRunLocation(params, asyncDirRoot, resultsDir);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return {
+			content: [{ type: "text", text: message }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+	const { asyncDir, resultPath, resolvedId } = location;
+
+	if (!asyncDir && !resultPath) {
+		return {
+			content: [{ type: "text", text: "Async run not found. Provide id or dir." }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+
+	if (asyncDir) {
+		let reconciliation;
+		try {
+			reconciliation = reconcileAsyncRun(asyncDir, { resultsDir, kill: deps.kill, now: deps.now });
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+		const status = reconciliation.status;
+		const effectiveRunId = status?.runId ?? resolvedId ?? "unknown";
+		const logPath = path.join(asyncDir, `subagent-log-${effectiveRunId}.md`);
+		const eventsPath = path.join(asyncDir, "events.jsonl");
+		if (status) {
+			const outputPath = formatAsyncRunOutputPath({ asyncDir, outputFile: status.outputFile });
+			const progressLabel = formatAsyncRunProgressLabel({
+				mode: status.mode,
+				state: status.state,
+				currentStep: status.currentStep,
+				chainStepCount: status.chainStepCount,
+				parallelGroups: status.parallelGroups,
+				steps: (status.steps ?? []).map((step, index) => ({ index, agent: step.agent, status: step.status })),
+			});
+			const started = new Date(status.startedAt).toISOString();
+			const updated = status.lastUpdate ? new Date(status.lastUpdate).toISOString() : "n/a";
+			const statusActivityText = status.state === "running" ? formatActivityLabel(status.lastActivityAt, status.activityState) : undefined;
+
+			const lines = [
+				`Run: ${status.runId}`,
+				`State: ${status.state}`,
+				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
+				`Mode: ${status.mode}`,
+				`Progress: ${progressLabel}`,
+				`Started: ${started}`,
+				`Updated: ${updated}`,
+				`Dir: ${asyncDir}`,
+				outputPath ? `Output: ${outputPath}` : undefined,
+				reconciliation.message ? `Diagnosis: ${reconciliation.message}` : undefined,
+				reconciliation.resultPath && fs.existsSync(reconciliation.resultPath) ? `Result: ${reconciliation.resultPath}` : undefined,
+			].filter((line): line is string => Boolean(line));
+			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);
+				const modelText = modelThinking ? ` (${modelThinking})` : "";
+				const errorText = step.error ? `, error: ${step.error}` : "";
+				lines.push(`${stepLineLabel(status, index)}: ${step.agent} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${errorText}`);
+				const stepOutputPath = path.join(asyncDir, `output-${index}.log`);
+				if (stepOutputPath !== outputPath && fs.existsSync(stepOutputPath)) lines.push(`  Output: ${stepOutputPath}`);
+				if (step.status === "running") {
+					lines.push(`  Intercom target: ${resolveSubagentIntercomTarget(status.runId, step.agent, index)} (if registered)`);
+				}
+			}
+			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
+			if (status.state !== "running") {
+				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile));
+			}
+			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
+			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
+
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		}
+	}
+
+	if (resultPath) {
+		try {
+			const raw = fs.readFileSync(resultPath, "utf-8");
+			const data = JSON.parse(raw) as { id?: string; runId?: string; agent?: string; success?: boolean; summary?: string; exitCode?: number; state?: string; sessionFile?: string; results?: Array<{ agent?: string; sessionFile?: string }> };
+			const status = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+			const runId = data.runId ?? data.id ?? resolvedId;
+			const lines = [`Run: ${runId}`, `State: ${status}`, `Result: ${resultPath}`];
+			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
+			lines.push(formatResumeGuidance(runId, children, data.sessionFile));
+			if (data.summary) lines.push("", data.summary);
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: `Failed to read async result file: ${message}` }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	return {
+		content: [{ type: "text", text: "Status file not found." }],
+		isError: true,
+		details: { mode: "single", results: [] },
+	};
+}