@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

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

@@ -0,0 +1,384 @@
+import * as fs from "node:fs";
+import { readOutputPage } from "../../shared/journal-reader.ts";
+import * as path from "node:path";
+import { formatActivityFacts, formatAsyncRunList, formatAsyncRunOutputPath, formatAsyncRunProgressLabel, listAsyncRuns } from "./async-status.ts";
+import { formatNestedRunStatusLines } from "../shared/nested-render.ts";
+import { formatModelThinking } from "../../shared/formatters.ts";
+import { buildManagementControl, formatActivityLabel, formatLiveIntercomActionLines, formatRunAction } from "../../shared/status-format.ts";
+import { ASYNC_DIR, RESULTS_DIR, type AsyncStatus, type NestedRunSummary, type SubagentLiveIntercomHealth, type SubagentState, type SubagentExecutionResult } from "../../shared/types.ts";
+import { resolveSubagentIntercomTarget } from "../../intercom/intercom-bridge.ts";
+import { exactAsyncRunLocation, resolveAsyncRunLocation } from "./async-resume.ts";
+import { resolveSubagentRunId } from "./run-id-resolver.ts";
+import { flatToLogicalStepIndex, normalizeParallelGroups } from "./parallel-groups.ts";
+import { reconcileAsyncRun, reconcileNestedAsyncDescendants } from "./stale-run-reconciler.ts";
+import { attachRootChildrenToSteps, findNestedRouteForRootId, findNestedRun, type NestedRunResolutionScope } from "../shared/nested-events.ts";
+import { readAsyncResultFile } from "./async-result-file.ts";
+import { readStatus } from "../../shared/utils.ts";
+
+const ASYNC_COMPLETION_REMINDER = "Completion will be delivered automatically. If you are only waiting, end your turn instead of polling status again.";
+
+interface RunStatusParams {
+	action?: "status";
+	id?: string;
+	runId?: string;
+	dir?: string;
+	full?: boolean;
+}
+
+interface RunStatusDeps {
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	kill?: (pid: number, signal?: NodeJS.Signals | 0) => boolean;
+	now?: () => number;
+	state?: SubagentState;
+	nested?: NestedRunResolutionScope;
+	intercomHealth?: Map<string, SubagentLiveIntercomHealth>;
+	includeRunHeader?: boolean;
+}
+
+function hasExistingSessionFile(value: unknown): value is string {
+	return typeof value === "string" && fs.existsSync(value);
+}
+
+function completionTargetsCurrentSession(run: Pick<AsyncStatus, "sessionId" | "cwd">, state: SubagentState | undefined): boolean {
+	if (!state) return true;
+	if (run.sessionId) return run.sessionId === state.currentSessionId;
+	return false;
+}
+
+function nestedCompletionTargetsCurrentSession(rootRunId: string, asyncDirRoot: string, state: SubagentState | undefined): boolean {
+	if (!state || state.ownedRuns?.has(rootRunId)) return true;
+	const tracked = state.asyncJobs.get(rootRunId);
+	if (tracked) return completionTargetsCurrentSession(tracked, state);
+	try {
+		const location = exactAsyncRunLocation(rootRunId, asyncDirRoot, RESULTS_DIR);
+		const status = location.asyncDir ? readStatus(location.asyncDir) : null;
+		return status ? completionTargetsCurrentSession(status, state) : false;
+	} catch {
+		return false;
+	}
+}
+
+function formatResumeGuidance(runId: string | undefined, children: Array<{ agent?: unknown; sessionFile?: unknown }>, fallbackSessionFile?: unknown, childSafe = false): 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 `Continue: ${formatRunAction("resume", runId, { message: "..." }, childSafe)}`;
+	}
+	const childWithSession = knownChildren.find(({ child }) => hasExistingSessionFile(child.sessionFile));
+	if (childWithSession) {
+		return `Continue child: ${formatRunAction("resume", runId, { index: childWithSession.index, message: "..." }, childSafe)}`;
+	}
+	return "Resume: unavailable; no child session file was persisted.";
+}
+
+function formatAcceptanceFinalizationSummary(finalization: NonNullable<NonNullable<AsyncStatus["steps"]>[number]["acceptance"]>["finalization"] | undefined): string {
+	if (!finalization) return "";
+	return `, finalization: ${finalization.status} after ${finalization.turns.length}/${finalization.maxTurns} turns`;
+}
+
+function formatOutputExcerpt(outputPath: string | undefined, maxBytes = 4096, maxLines = 12): string[] {
+	if (!outputPath || !fs.existsSync(outputPath)) return [];
+	try {
+		const page = readOutputPage(outputPath, { length: maxBytes });
+		const truncatedBytes = page.offset > 0;
+		const text = page.text.trim();
+		if (!text) return [];
+		const allLines = text.split(/\r?\n/);
+		const lines = allLines.slice(-maxLines);
+		const truncatedLines = allLines.length > maxLines;
+		const suffix = truncatedBytes || truncatedLines ? " (tail, truncated)" : "";
+		return [`Output excerpt${suffix}:`, ...lines.map((line) => `  ${line}`)];
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		return [`Output excerpt unavailable: ${message}`];
+	}
+}
+
+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}`;
+}
+
+function nestedRunDisplayName(run: NestedRunSummary): string {
+	if (run.agent) return run.agent;
+	if (run.agents?.length) return run.agents.join(", ");
+	return run.id;
+}
+
+function normalizedState(state: AsyncStatus["state"] | NestedRunSummary["state"]): "live" | "completed" | "paused" | "blocked" | "failed" | "unknown" {
+	if (state === "running" || state === "queued") return "live";
+	if (state === "complete") return "completed";
+	if (state === "paused" || state === "blocked" || state === "failed") return state;
+	return "unknown";
+}
+
+function formatNestedExactStatus(rootRunId: string, run: NestedRunSummary, childSafe: boolean): string {
+	const lines = [
+		`Nested run: ${run.id}`,
+		`Root: ${rootRunId}`,
+		`Parent: ${run.parentRunId}${run.parentStepIndex !== undefined ? ` step ${run.parentStepIndex + 1}` : ""}`,
+		`State: ${run.state}`,
+		run.activityState || run.lastActivityAt ? `Activity: ${formatActivityLabel(run.lastActivityAt, run.activityState)}` : undefined,
+		run.mode ? `Mode: ${run.mode}` : undefined,
+		`Agent: ${nestedRunDisplayName(run)}`,
+		run.currentStep !== undefined ? `Progress: step ${run.currentStep + 1}/${run.chainStepCount ?? run.steps?.length ?? 1}` : undefined,
+		run.asyncDir ? `Dir: ${run.asyncDir}` : undefined,
+		run.sessionFile ? `Session: ${run.sessionFile}` : undefined,
+		run.error ? `Error: ${run.error}` : undefined,
+	].filter((line): line is string => Boolean(line));
+	if (run.path.length) {
+		lines.push(`Path: ${run.path.map((part) => `${part.runId}${part.stepIndex !== undefined ? `:${part.stepIndex + 1}` : ""}${part.agent ? `:${part.agent}` : ""}`).join(" > ")} > ${run.id}`);
+	}
+	if (run.steps?.length) {
+		lines.push("Steps:");
+		for (const [index, step] of run.steps.entries()) {
+			const activity = step.status === "running" ? formatActivityLabel(step.lastActivityAt, step.activityState) : undefined;
+			lines.push(`  ${index + 1}. ${step.agent} ${step.status}${activity ? `, ${activity}` : ""}${step.error ? `, error: ${step.error}` : ""}`);
+			lines.push(...formatNestedRunStatusLines(step.children, { indent: "    ", commandHints: true, childSafe }));
+		}
+	}
+	lines.push(...formatNestedRunStatusLines(run.children, { indent: "  ", commandHints: true, childSafe }));
+	const state = normalizedState(run.state);
+	lines.push("Commands:", `  Status: ${formatRunAction("status", run.id, {}, childSafe)}`);
+	if (state === "live") lines.push(`  ${childSafe ? "Interrupt" : "Stop"}: ${formatRunAction("interrupt", run.id, {}, childSafe)}`);
+	if (state === "live" || run.sessionFile) lines.push(`  ${childSafe ? "Resume" : "Continue"}: ${formatRunAction("resume", run.id, { message: "..." }, childSafe)}`);
+	lines.push(`  Root status: ${formatRunAction("status", rootRunId, {}, childSafe)}`);
+	return lines.join("\n");
+}
+
+export function inspectSubagentStatus(params: RunStatusParams, deps: RunStatusDeps = {}): SubagentExecutionResult {
+	const childSafe = Boolean(deps.nested);
+	const asyncDirRoot = deps.asyncDirRoot ?? ASYNC_DIR;
+	const resultsDir = deps.resultsDir ?? RESULTS_DIR;
+	if (!params.id && !params.runId && !params.dir) {
+		if (deps.nested) {
+			return {
+				content: [{ type: "text", text: "Child-safe subagent status requires a run id." }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+		try {
+			const runs = listAsyncRuns(asyncDirRoot, {
+				resultsDir,
+				kill: deps.kill,
+				now: deps.now,
+			}).filter((run) => completionTargetsCurrentSession(run, deps.state));
+			const text = formatAsyncRunList(runs, "Async runs");
+			const reminder = runs.some((run) => run.state === "running" || run.state === "queued");
+			return {
+				content: [{ type: "text", text: reminder ? `${text}\n${ASYNC_COMPLETION_REMINDER}` : text }],
+				details: {
+					mode: "single", results: [],
+					managementControls: runs.map((run) => {
+						const running = run.steps.find((step) => step.status === "running");
+						const target = running ? resolveSubagentIntercomTarget(run.id, running.agent, running.index) : undefined;
+						const resumable = run.steps.find((step) => hasExistingSessionFile(step.sessionFile));
+						return buildManagementControl({ state: normalizedState(run.state), runId: run.id, index: running?.index ?? resumable?.index, intercomTarget: target, canNudge: Boolean(running), canResume: Boolean(running || resumable || (run.steps.length <= 1 && hasExistingSessionFile(run.sessionFile))), canInterrupt: run.state === "running" });
+					}),
+				},
+			};
+		} 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 {
+		const requestedId = params.id ?? params.runId;
+		if (!params.dir && requestedId) {
+			const resolved = resolveSubagentRunId(requestedId, { asyncDirRoot, resultsDir, state: deps.state, nested: deps.nested });
+			if (resolved?.kind === "nested") {
+				const children = reconcileNestedAsyncDescendants(resolved.match.route, { resultsDir, kill: deps.kill, now: deps.now });
+				const nested = resolved;
+				const run = findNestedRun(children, nested.id) ?? nested.match.run;
+				const state = normalizedState(run.state);
+				const intercomTarget = run.intercomTarget ?? run.leafIntercomTarget;
+				const text = formatNestedExactStatus(nested.match.rootRunId, run, childSafe);
+				const reminder = state === "live" && nestedCompletionTargetsCurrentSession(nested.match.rootRunId, asyncDirRoot, deps.state);
+				return {
+					content: [{ type: "text", text: reminder ? `${text}\n${ASYNC_COMPLETION_REMINDER}` : text }],
+					details: {
+						mode: "single", results: [],
+						managementControl: buildManagementControl({ state, runId: run.id, intercomTarget, canNudge: false, canResume: state === "live" || Boolean(run.sessionFile), canInterrupt: state === "live" }),
+					},
+				};
+			}
+			if (resolved?.kind === "async") location = resolved.location;
+			else location = { asyncDir: null, resultPath: null, resolvedId: requestedId };
+		} else {
+			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 intercomTargets: string[] = [];
+			let nestedChildren: NestedRunSummary[] = [];
+			let nestedWarning: string | undefined;
+			try {
+				const nestedRoute = findNestedRouteForRootId(status.runId);
+				if (nestedRoute) nestedChildren = reconcileNestedAsyncDescendants(nestedRoute, { resultsDir, kill: deps.kill, now: deps.now });
+				attachRootChildrenToSteps(status.runId, status.steps, nestedChildren);
+			} catch (error) {
+				nestedWarning = `Nested status unavailable: ${error instanceof Error ? error.message : String(error)}`;
+			}
+			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" ? formatActivityFacts(status) : undefined;
+			const canExtend = status.runtimeVersion === 2 && status.state === "running" && !status.timedOut && Boolean(status.timeoutAt);
+
+			const lines = [
+				...(deps.includeRunHeader !== false ? [`Run: ${status.runId}`, `State: ${status.state}`, `Mode: ${status.mode}`] : []),
+				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
+				`Progress: ${progressLabel}`,
+				`Started: ${started}`,
+				`Updated: ${updated}`,
+				status.timeoutAt ? `Timeout: ${new Date(status.timeoutAt).toISOString()}` : undefined,
+				canExtend ? `Extend: ${formatRunAction("extend", status.runId, { extendMs: 300000 }, childSafe)}` : undefined,
+				`Dir: ${asyncDir}`,
+				`Status: ${formatRunAction("status", status.runId, {}, childSafe)}`,
+				outputPath ? `Output: ${outputPath}` : undefined,
+				reconciliation.message ? `Diagnosis: ${reconciliation.message}` : undefined,
+				reconciliation.resultPath && fs.existsSync(reconciliation.resultPath) ? `${deps.includeRunHeader === false ? "Runtime result" : "Result"}: ${reconciliation.resultPath}` : undefined,
+			].filter((line): line is string => Boolean(line));
+			if (status.state !== "running") lines.push(...formatOutputExcerpt(outputPath));
+
+			for (const [index, step] of (status.steps ?? []).entries()) {
+				const stepActivityText = step.status === "running" ? formatActivityFacts(step) : undefined;
+				const modelThinking = formatModelThinking(step.model, step.thinking);
+				const modelText = modelThinking ? ` (${modelThinking})` : "";
+				const errorText = step.error ? `, error: ${step.error}` : "";
+				const finalizationText = formatAcceptanceFinalizationSummary(step.acceptance?.finalization);
+				const acceptanceText = step.acceptance?.status ? `, acceptance: ${step.acceptance.status}${finalizationText}` : "";
+				const display = step.label ? `${step.label} (${step.agent})` : step.agent;
+				const phase = step.phase ? `[${step.phase}] ` : "";
+				lines.push(`${stepLineLabel(status, index)}: ${phase}${display} ${step.status}${modelText}${stepActivityText ? `, ${stepActivityText}` : ""}${acceptanceText}${errorText}`);
+				if (step.tokens) lines.push(`  ${step.tokens.total} tokens`);
+				lines.push(...formatNestedRunStatusLines(step.children, { indent: "  ", commandHints: true, maxLines: 20, childSafe }));
+				const stepOutputPath = path.join(asyncDir, `output-${index}.log`);
+				if (stepOutputPath !== outputPath && fs.existsSync(stepOutputPath)) lines.push(`  Output: ${stepOutputPath}`);
+				if (step.status === "running") {
+					const target = resolveSubagentIntercomTarget(status.runId, step.agent, index);
+					intercomTargets.push(target);
+					lines.push(...formatLiveIntercomActionLines({ runId: status.runId, index, target, health: deps.intercomHealth?.get(target), indent: "  ", childSafe }));
+				}
+			}
+			const attached = new Set((status.steps ?? []).flatMap((step) => step.children?.map((child) => child.id) ?? []));
+			const unattached = nestedChildren.filter((child) => !attached.has(child.id));
+			lines.push(...formatNestedRunStatusLines(unattached, { indent: "", commandHints: true, maxLines: 20, childSafe }));
+			if (nestedWarning) lines.push(`Warning: ${nestedWarning}`);
+			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
+			if (status.state !== "running") {
+				lines.push(formatResumeGuidance(status.runId, status.steps ?? [], status.sessionFile, childSafe));
+			}
+			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
+			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
+			if ((status.state === "running" || status.state === "queued") && completionTargetsCurrentSession(status, deps.state)) lines.push(ASYNC_COMPLETION_REMINDER);
+
+			const state = normalizedState(status.state);
+			const runningStep = (status.steps ?? []).map((step, index) => ({ step, index })).find(({ step }) => step.status === "running");
+			const target = runningStep ? resolveSubagentIntercomTarget(status.runId, runningStep.step.agent, runningStep.index) : undefined;
+			const resumableStep = (status.steps ?? []).map((step, index) => ({ step, index })).find(({ step }) => hasExistingSessionFile(step.sessionFile));
+			const canResume = state !== "live" && Boolean(resumableStep || ((status.steps?.length ?? 0) <= 1 && hasExistingSessionFile(status.sessionFile)));
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: {
+					mode: "single", results: [], intercomTargets,
+					managementControl: buildManagementControl({ state, runId: status.runId, index: runningStep?.index ?? resumableStep?.index, intercomTarget: target, canNudge: Boolean(runningStep), canResume: state === "live" ? Boolean(runningStep) : canResume, canInterrupt: status.state === "running", canExtend }),
+				},
+			};
+		}
+	}
+
+	if (resultPath) {
+		try {
+			const data = readAsyncResultFile(resultPath);
+			const status = data.terminalState;
+			const runId = data.runId ?? data.id ?? resolvedId;
+			const lines = [...(deps.includeRunHeader !== false ? [`Run: ${runId}`, `State: ${status}`] : []), `${deps.includeRunHeader === false ? "Runtime result" : "Result"}: ${resultPath}`, `Status: ${formatRunAction("status", runId ?? "unknown", {}, childSafe)}`];
+			const children = Array.isArray(data.results) ? data.results : data.agent ? [{ agent: data.agent, sessionFile: data.sessionFile }] : [];
+			lines.push(formatResumeGuidance(runId, children, data.sessionFile, childSafe));
+			if (data.summary) lines.push("", params.full ? data.summary : data.summary.length > 600 ? `${data.summary.slice(0, 599)}…` : data.summary);
+			const state = normalizedState(status);
+			const resumableChild = children.map((child, index) => ({ child, index })).find(({ child }) => hasExistingSessionFile(child.sessionFile));
+			return {
+				content: [{ type: "text", text: lines.join("\n") }],
+				details: {
+					mode: "single", results: [],
+					managementControl: buildManagementControl({ state, runId: runId ?? "unknown", index: resumableChild?.index, canResume: state !== "live" && Boolean(resumableChild) }),
+				},
+			};
+		} 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: [] },
+	};
+}