@fitchmultz/pi-subagents 0.0.0-stage → 0.44.5

package/src/shared/status-format.ts

@@ -0,0 +1,123 @@
+import { loadConfig } from "../extension/config.ts";
+import type { AgentProcessExit, ActivityState, AsyncJobStep, ManagementAction, ManagementControl, ManagementRunState, SubagentLiveIntercomHealth } from "./types.ts";
+
+export function formatAgentProcessExit(exit: AgentProcessExit | undefined): string {
+	return exit ? `Agent process exited (${exit.signal ? `signal ${exit.signal}` : `code ${exit.code ?? "unrecorded"}`}). Command and descendant exit are not implied.`
+		: "Agent process exit not recorded. Command exit is unconfirmed.";
+}
+
+export function formatRunAction(action: ManagementAction | "questions" | "answer", id: string | undefined, fields: Record<string, string | number | boolean> = {}, childSafe = false): string {
+	const legacyChild = childSafe && loadConfig().compactChildTools === false;
+	const parentAction = { status: "inspect", resume: "continue", interrupt: "stop" };
+	const name = legacyChild ? action : parentAction[action as keyof typeof parentAction] ?? action;
+	const args = Object.entries({ action: name, ...(id !== undefined ? { id } : {}), ...fields }).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(", ");
+	const call = `${legacyChild || action === "extend" ? "subagent" : "agent_runs"}({ ${args} })`;
+	return action === "extend" && !legacyChild ? `load_subagent({}), then ${call}` : call;
+}
+
+export function buildManagementControl(input: {
+	state: ManagementRunState;
+	runId: string;
+	index?: number;
+	intercomTarget?: string;
+	canExtend?: boolean;
+	canResume?: boolean;
+	canNudge?: boolean;
+	canInterrupt?: boolean;
+	canReview?: boolean;
+	unavailableActions?: Partial<Record<ManagementAction, string>>;
+	revivedFromRunId?: string;
+}): ManagementControl {
+	const capabilities: ManagementAction[] = ["status"];
+	if (input.state === "live") {
+		if (input.canNudge) capabilities.push("nudge");
+		if (input.canResume) capabilities.push("resume");
+		if (input.canInterrupt) capabilities.push("interrupt");
+	} else if (input.canResume) capabilities.push("resume");
+	if (input.state === "live" && input.canExtend) capabilities.push("extend");
+	if (input.canReview) capabilities.push("review");
+	return {
+		state: input.state,
+		runId: input.runId,
+		capabilities,
+		nextActions: capabilities.map((action) => ({
+			action,
+			runId: input.runId,
+			...(input.index !== undefined && (action === "nudge" || action === "resume") ? { index: input.index } : {}),
+			...(input.intercomTarget && (action === "nudge" || action === "resume") ? { intercomTarget: input.intercomTarget } : {}),
+		})),
+		...(input.unavailableActions ? { unavailableActions: input.unavailableActions } : {}),
+		...(input.revivedFromRunId ? { revivedFromRunId: input.revivedFromRunId, pendingReplyContextValid: false } : {}),
+	};
+}
+
+type StepStatusLike = Pick<AsyncJobStep, "status">;
+
+function formatActivityAge(ms: number): string {
+	if (ms < 1000) return "now";
+	if (ms < 60000) return `${Math.floor(ms / 1000)}s`;
+	return `${Math.floor(ms / 60000)}m`;
+}
+
+export function formatActivityLabel(lastActivityAt: number | undefined, activityState?: ActivityState, now = Date.now()): string | undefined {
+	if (lastActivityAt === undefined) {
+		if (activityState === "needs_attention") return "needs attention";
+		return undefined;
+	}
+	const age = formatActivityAge(Math.max(0, now - lastActivityAt));
+	if (activityState === "needs_attention") return `no activity for ${age}`;
+	return age === "now" ? "active now" : `active ${age} ago`;
+}
+
+function isCompletedStepStatus(status: AsyncJobStep["status"]): boolean {
+	return status === "complete" || status === "completed";
+}
+
+export function aggregateStepStatus(steps: StepStatusLike[]): AsyncJobStep["status"] {
+	if (steps.some((step) => step.status === "running")) return "running";
+	if (steps.some((step) => step.status === "failed")) return "failed";
+	if (steps.some((step) => step.status === "blocked")) return "blocked";
+	if (steps.some((step) => step.status === "paused")) return "paused";
+	if (steps.length > 0 && steps.every((step) => isCompletedStepStatus(step.status))) return "complete";
+	return "pending";
+}
+
+export function formatAgentRunningLabel(count: number): string {
+	return count === 1 ? "1 agent running" : `${count} agents running`;
+}
+
+export function formatLiveIntercomActionLines(input: {
+	runId: string;
+	target: string;
+	index?: number;
+	health?: SubagentLiveIntercomHealth;
+	indent?: string;
+	childSafe?: boolean;
+}): string[] {
+	const fields = { ...(input.index !== undefined ? { index: input.index } : {}), message: "What are you blocked on?" };
+	const healthText = !input.health
+		? "unknown"
+		: input.health.status === "registered"
+			? `registered${input.health.sessionStatus ? `, ${input.health.sessionStatus}` : ""}${input.health.acceptsAsks !== undefined ? `, accepts_asks:${input.health.acceptsAsks}` : ""}${input.health.pendingAsks !== undefined ? `, pending_asks:${input.health.pendingAsks}` : ""}`
+			: input.health.status.replace(/_/g, " ");
+	const indent = input.indent ?? "";
+	return [
+		`${indent}Intercom: ${healthText} (${input.target})`,
+		`${indent}Nudge (preferred live coordination): ${formatRunAction("nudge", input.runId, fields, input.childSafe)}`,
+		`${indent}Ask (blocking wait only; parent must remain alive): intercom({ action: "ask", to: "${input.target}", delivery: "steer", message: "What are you blocked on?" })`,
+	];
+}
+
+export function formatParallelOutcome(steps: StepStatusLike[], total: number, options: { showRunning?: boolean } = {}): string {
+	const running = steps.filter((step) => step.status === "running").length;
+	const succeeded = steps.filter((step) => isCompletedStepStatus(step.status)).length;
+	const failed = steps.filter((step) => step.status === "failed").length;
+	const paused = steps.filter((step) => step.status === "paused").length;
+	const blocked = steps.filter((step) => step.status === "blocked").length;
+	const parts = [`${succeeded}/${total} succeeded`];
+	if (options.showRunning !== false && running > 0) parts.unshift(formatAgentRunningLabel(running));
+	if (failed > 0) parts.push(`${failed} failed`);
+	if (paused > 0) parts.push(`${paused} paused`);
+	if (blocked > 0) parts.push(`${blocked} need human action`);
+	return parts.join(" · ");
+}

package/src/shared/temp-root.ts

@@ -0,0 +1,107 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isSafeNestedPathId } from "../runs/shared/nested-path.ts";
+import { ASYNC_DIR, RESULTS_DIR, TEMP_ROOT_DIR } from "./types.ts";
+import { listRunQuestions, LEGACY_QUESTIONS_DIR, QUESTIONS_DIR } from "../runs/shared/supervisor-questions.ts";
+
+const MAX_RUN_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function ensureTempRoot(): void {
+	fs.mkdirSync(TEMP_ROOT_DIR, { recursive: true, mode: 0o700 });
+	const stat = fs.lstatSync(TEMP_ROOT_DIR);
+	if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`Unsafe pi-subagents temp root: ${TEMP_ROOT_DIR}`);
+	const uid = process.getuid?.();
+	if (uid !== undefined && stat.uid !== uid) throw new Error(`pi-subagents temp root is owned by another user: ${TEMP_ROOT_DIR}`);
+	fs.chmodSync(TEMP_ROOT_DIR, 0o700);
+}
+
+export function ensureSafeTempPath(candidate: string): void {
+	const root = path.resolve(TEMP_ROOT_DIR);
+	const resolved = path.resolve(candidate);
+	const relative = path.relative(root, resolved);
+	if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) return;
+	ensureTempRoot();
+	let current = root;
+	for (const segment of relative.split(path.sep).filter(Boolean)) {
+		current = path.join(current, segment);
+		try {
+			const stat = fs.lstatSync(current);
+			if (stat.isSymbolicLink()) throw new Error(`Unsafe symlink in pi-subagents temp path: ${current}`);
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+			throw error;
+		}
+	}
+}
+
+// Missing, malformed, or non-object JSON means the entry is incomplete garbage and safe
+// to remove. Operational read failures throw so callers fail closed instead of deleting.
+async function readJsonObject(file: string): Promise<Record<string, unknown> | undefined> {
+	try {
+		const parsed: unknown = JSON.parse(await fs.promises.readFile(file, "utf-8"));
+		return parsed !== null && typeof parsed === "object" ? parsed as Record<string, unknown> : undefined;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT" || error instanceof SyntaxError) return undefined;
+		throw error;
+	}
+}
+
+async function activeStatus(statusFile: string): Promise<boolean> {
+	const status = await readJsonObject(statusFile);
+	return status?.state === "running" || status?.state === "queued";
+}
+
+async function removeOldEntries(root: string, now: number, keepActive?: (entryPath: string) => boolean | Promise<boolean>): Promise<void> {
+	let entries: fs.Dirent[];
+	try {
+		entries = await fs.promises.readdir(root, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const entry of entries) {
+		const entryPath = path.join(root, entry.name);
+		try {
+			const stat = await fs.promises.lstat(entryPath);
+			if (now - stat.mtimeMs <= MAX_RUN_AGE_MS) continue;
+			if (keepActive && entry.isDirectory() && await keepActive(entryPath)) continue;
+			await fs.promises.rm(entryPath, { recursive: entry.isDirectory(), force: true });
+		} catch {
+			// Startup retention cleanup is best effort; entries that fail closed are skipped.
+		}
+	}
+}
+
+// A route is live while anything still writes into it (nested descendants can outlive a
+// terminal root, and foreground roots have no async status at all) or while its root run
+// reports an active state. Child writes land in the events/ and controls/ subdirs without
+// bumping the route-root mtime; registry projection renames into routeRoot, which the
+// caller's mtime gate already covers.
+async function nestedRouteActive(routeRoot: string, now: number): Promise<boolean> {
+	for (const name of ["events", "controls"]) {
+		try {
+			if (now - (await fs.promises.stat(path.join(routeRoot, name))).mtimeMs <= MAX_RUN_AGE_MS) return true;
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+		}
+	}
+	const metadata = await readJsonObject(path.join(routeRoot, "route.json"));
+	if (!metadata || !isSafeNestedPathId(metadata.rootRunId)) return false;
+	return activeStatus(path.join(ASYNC_DIR, metadata.rootRunId, "status.json"));
+}
+
+function pendingQuestion(runDir: string): boolean {
+	return listRunQuestions(runDir).some((question) => question.state === "awaiting_input" || question.state === "answer_pending");
+}
+
+export async function cleanupOldRunStorage(now = Date.now()): Promise<void> {
+	for (const [dir, keepActive] of [
+		[ASYNC_DIR, async (entryPath: string) => await activeStatus(path.join(entryPath, "status.json")) || pendingQuestion(path.join(QUESTIONS_DIR, path.basename(entryPath)))],
+		[LEGACY_QUESTIONS_DIR, pendingQuestion],
+		[RESULTS_DIR, undefined],
+		[path.join(TEMP_ROOT_DIR, "nested-subagent-runs"), undefined],
+		[path.join(TEMP_ROOT_DIR, "nested-subagent-events"), (entryPath: string) => nestedRouteActive(entryPath, now)],
+	] as const) {
+		ensureSafeTempPath(dir);
+		await removeOldEntries(dir, now, keepActive);
+	}
+}