@astrofoundry/pi-astro 0.14.6 → 0.16.0

package/node_modules/pi-subagents/src/runs/shared/pi-spawn.ts

@@ -0,0 +1,115 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
+
+export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
+	let dir = path.dirname(entryPoint);
+	while (dir !== path.dirname(dir)) {
+		const packageJsonPath = path.join(dir, "package.json");
+		if (fs.existsSync(packageJsonPath)) {
+			const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as { name?: unknown };
+			if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
+		}
+		dir = path.dirname(dir);
+	}
+	return undefined;
+}
+
+export function resolveInstalledPiPackageRoot(): string | undefined {
+	return findPiPackageRootFromEntry(fileURLToPath(import.meta.resolve(PI_CODING_AGENT_PACKAGE)));
+}
+
+export function resolvePiPackageRoot(): string | undefined {
+	try {
+		const entry = process.argv[1];
+		return entry ? findPiPackageRootFromEntry(fs.realpathSync(entry)) : undefined;
+	} catch {
+		// process.argv[1] probing is best-effort; callers can fall back to PATH/package resolution.
+		return undefined;
+	}
+}
+
+export interface PiSpawnDeps {
+	platform?: NodeJS.Platform;
+	execPath?: string;
+	argv1?: string;
+	existsSync?: (filePath: string) => boolean;
+	readFileSync?: (filePath: string, encoding: "utf-8") => string;
+	resolvePackageJson?: () => string;
+	resolvePackageEntry?: () => string;
+	piPackageRoot?: string;
+}
+
+interface PiSpawnCommand {
+	command: string;
+	args: string[];
+}
+
+function isRunnableNodeScript(filePath: string, existsSync: (filePath: string) => boolean): boolean {
+	if (!existsSync(filePath)) return false;
+	return /\.(?:mjs|cjs|js)$/i.test(filePath);
+}
+
+function normalizePath(filePath: string): string {
+	return path.isAbsolute(filePath) ? filePath : path.resolve(filePath);
+}
+
+export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | undefined {
+	const existsSync = deps.existsSync ?? fs.existsSync;
+	const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
+	const argv1 = deps.argv1 ?? process.argv[1];
+
+	if (argv1) {
+		const argvPath = normalizePath(argv1);
+		if (isRunnableNodeScript(argvPath, existsSync)) {
+			return argvPath;
+		}
+	}
+
+	try {
+		const resolvePackageJson = deps.resolvePackageJson ?? (() => {
+			const root = deps.piPackageRoot ?? resolvePiPackageRoot();
+			if (root) return path.join(root, "package.json");
+			const packageRoot = deps.resolvePackageEntry
+				? findPiPackageRootFromEntry(deps.resolvePackageEntry())
+				: resolveInstalledPiPackageRoot();
+			if (!packageRoot) throw new Error(`Could not resolve ${PI_CODING_AGENT_PACKAGE} package root`);
+			return path.join(packageRoot, "package.json");
+		});
+		const packageJsonPath = resolvePackageJson();
+		const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
+			bin?: string | Record<string, string>;
+		};
+		const binField = packageJson.bin;
+		const binPath = typeof binField === "string"
+			? binField
+			: binField?.pi ?? Object.values(binField ?? {})[0];
+		if (!binPath) return undefined;
+		const candidate = path.resolve(path.dirname(packageJsonPath), binPath);
+		if (isRunnableNodeScript(candidate, existsSync)) {
+			return candidate;
+		}
+	} catch {
+		// Windows CLI resolution is optional; falling back to `pi` lets PATH handle execution.
+		return undefined;
+	}
+
+	return undefined;
+}
+
+export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
+	const platform = deps.platform ?? process.platform;
+	if (platform === "win32") {
+		const piCliPath = resolveWindowsPiCliScript(deps);
+		if (piCliPath) {
+			return {
+				command: deps.execPath ?? process.execPath,
+				args: [piCliPath, ...args],
+			};
+		}
+	}
+
+	return { command: "pi", args };
+}

package/node_modules/pi-subagents/src/runs/shared/run-history.ts

@@ -0,0 +1,55 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export interface RunEntry {
+	agent: string;
+	task: string;
+	ts: number;
+	status: "ok" | "error";
+	duration: number;
+	exit?: number;
+}
+
+const HISTORY_PATH = path.join(os.homedir(), ".pi", "agent", "run-history.jsonl");
+const ROTATE_READ_THRESHOLD = 1200;
+const ROTATE_KEEP = 1000;
+
+export function recordRun(agent: string, task: string, exitCode: number, durationMs: number): void {
+	try {
+		const entry: RunEntry = {
+			agent,
+			task: task.slice(0, 200),
+			ts: Math.floor(Date.now() / 1000),
+			status: exitCode === 0 ? "ok" : "error",
+			duration: durationMs,
+			...(exitCode !== 0 ? { exit: exitCode } : {}),
+		};
+		fs.mkdirSync(path.dirname(HISTORY_PATH), { recursive: true });
+		fs.appendFileSync(HISTORY_PATH, `${JSON.stringify(entry)}\n`);
+	} catch {
+		// Best-effort — never crash the execution flow for history recording
+	}
+}
+
+export function loadRunsForAgent(agent: string): RunEntry[] {
+	if (!fs.existsSync(HISTORY_PATH)) return [];
+	let raw: string;
+	try {
+		raw = fs.readFileSync(HISTORY_PATH, "utf-8");
+	} catch {
+		return [];
+	}
+
+	let lines = raw.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+
+	if (lines.length > ROTATE_READ_THRESHOLD) {
+		lines = lines.slice(-ROTATE_KEEP);
+		try { fs.writeFileSync(HISTORY_PATH, `${lines.join("\n")}\n`, "utf-8"); } catch {}
+	}
+
+	return lines
+		.map((line) => { try { return JSON.parse(line) as RunEntry; } catch { return undefined; } })
+		.filter((entry): entry is RunEntry => Boolean(entry) && entry.agent === agent)
+		.reverse();
+}

package/node_modules/pi-subagents/src/runs/shared/single-output.ts

@@ -0,0 +1,154 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { OutputMode, SavedOutputReference } from "../../shared/types.ts";
+
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	size?: number;
+}
+
+export function resolveSingleOutputPath(
+	output: string | false | undefined,
+	runtimeCwd: string,
+	requestedCwd?: string,
+): string | undefined {
+	if (typeof output !== "string" || !output) return undefined;
+	if (path.isAbsolute(output)) return output;
+	const baseCwd = requestedCwd
+		? (path.isAbsolute(requestedCwd) ? requestedCwd : path.resolve(runtimeCwd, requestedCwd))
+		: runtimeCwd;
+	return path.resolve(baseCwd, output);
+}
+
+export function injectSingleOutputInstruction(task: string, outputPath: string | undefined): string {
+	if (!outputPath) return task;
+	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
+}
+
+function countLines(text: string): number {
+	if (!text) return 0;
+	const newlineMatches = text.match(/\r\n|\r|\n/g);
+	return (newlineMatches?.length ?? 0) + (/[\r\n]$/.test(text) ? 0 : 1);
+}
+
+function formatByteSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes} B`;
+	const units = ["KB", "MB", "GB", "TB"];
+	let value = bytes / 1024;
+	let unitIndex = 0;
+	while (value >= 1024 && unitIndex < units.length - 1) {
+		value /= 1024;
+		unitIndex++;
+	}
+	return `${value.toFixed(1)} ${units[unitIndex]}`;
+}
+
+export function formatSavedOutputReference(savedPath: string, fullOutput: string): SavedOutputReference {
+	const absolutePath = path.resolve(savedPath);
+	const bytes = Buffer.byteLength(fullOutput, "utf-8");
+	const lines = countLines(fullOutput);
+	return {
+		path: absolutePath,
+		bytes,
+		lines,
+		message: `Output saved to: ${absolutePath} (${formatByteSize(bytes)}, ${lines} ${lines === 1 ? "line" : "lines"}). Read this file if needed.`,
+	};
+}
+
+export function validateFileOnlyOutputMode(outputMode: OutputMode | undefined, outputPath: string | undefined, context: string): string | undefined {
+	if (outputMode === "file-only" && !outputPath) {
+		return `${context} sets outputMode: "file-only" but does not configure an output file. Set output to a path or use outputMode: "inline".`;
+	}
+	return undefined;
+}
+
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		// The snapshot is advisory; resolveSingleOutput reports concrete read/write failures.
+		return { exists: false };
+	}
+}
+
+function persistSingleOutput(
+	outputPath: string | undefined,
+	fullOutput: string,
+): { savedPath?: string; error?: string } {
+	if (!outputPath) return {};
+	try {
+		fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+		fs.writeFileSync(outputPath, fullOutput, "utf-8");
+		return { savedPath: outputPath };
+	} catch (err) {
+		return { error: err instanceof Error ? err.message : String(err) };
+	}
+}
+
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { fullOutput: string; savedPath?: string; saveError?: string } {
+	if (!outputPath) return { fullOutput: fallbackOutput };
+
+	let changedSinceStart = false;
+	try {
+		const stat = fs.statSync(outputPath);
+		changedSinceStart = !beforeRun?.exists
+			|| stat.mtimeMs !== beforeRun.mtimeMs
+			|| stat.size !== beforeRun.size;
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? (error as { code?: unknown }).code : undefined;
+		if (code !== "ENOENT" && code !== "ENOTDIR") {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to inspect output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	if (changedSinceStart) {
+		try {
+			return { fullOutput: fs.readFileSync(outputPath, "utf-8"), savedPath: outputPath };
+		} catch (error) {
+			return {
+				fullOutput: fallbackOutput,
+				saveError: `Failed to read changed output file: ${error instanceof Error ? error.message : String(error)}`,
+			};
+		}
+	}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
+	return { fullOutput: fallbackOutput, saveError: save.error };
+}
+
+export function finalizeSingleOutput(params: {
+	fullOutput: string;
+	truncatedOutput?: string;
+	outputPath?: string;
+	outputMode?: OutputMode;
+	exitCode: number;
+	savedPath?: string;
+	outputReference?: SavedOutputReference;
+	saveError?: string;
+}): { displayOutput: string; savedPath?: string; outputReference?: SavedOutputReference; saveError?: string } {
+	let displayOutput = params.truncatedOutput || params.fullOutput;
+	if (params.exitCode === 0 && params.savedPath) {
+		const outputReference = params.outputReference ?? formatSavedOutputReference(params.savedPath, params.fullOutput);
+		if (params.outputMode === "file-only") {
+			return { displayOutput: outputReference.message, savedPath: params.savedPath, outputReference };
+		}
+		displayOutput += `\n\n${outputReference.message}`;
+		return { displayOutput, savedPath: params.savedPath, outputReference };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\nOutput file error: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
+	}
+	return { displayOutput };
+}

package/node_modules/pi-subagents/src/runs/shared/subagent-control.ts

@@ -0,0 +1,226 @@
+import {
+	type ActivityState,
+	type ControlConfig,
+	type ControlEvent,
+	type ControlEventType,
+	type ControlNotificationChannel,
+	type ResolvedControlConfig,
+} from "../../shared/types.ts";
+
+const CONTROL_EVENT_TYPES: ControlEventType[] = ["active_long_running", "needs_attention"];
+const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
+const DEFAULT_NOTIFY_ON: ControlEventType[] = ["active_long_running", "needs_attention"];
+
+export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
+	enabled: true,
+	needsAttentionAfterMs: 60_000,
+	activeNoticeAfterMs: 240_000,
+	failedToolAttemptsBeforeAttention: 3,
+	notifyOn: DEFAULT_NOTIFY_ON,
+	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
+};
+
+function parsePositiveInt(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
+	return value;
+}
+
+function parseControlList<T extends string>(value: unknown, allowed: readonly T[]): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.length === 0) return [];
+	const allowedSet = new Set(allowed);
+	const parsed = value.filter((entry): entry is T => typeof entry === "string" && allowedSet.has(entry as T));
+	return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
+}
+
+export function resolveControlConfig(
+	globalConfig?: ControlConfig,
+	override?: ControlConfig,
+): ResolvedControlConfig {
+	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
+	const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const activeNoticeAfterMs = parsePositiveInt(override?.activeNoticeAfterMs)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.activeNoticeAfterMs;
+	const activeNoticeAfterTurns = parsePositiveInt(override?.activeNoticeAfterTurns)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterTurns);
+	const activeNoticeAfterTokens = parsePositiveInt(override?.activeNoticeAfterTokens)
+		?? parsePositiveInt(globalConfig?.activeNoticeAfterTokens);
+	const failedToolAttemptsBeforeAttention = parsePositiveInt(override?.failedToolAttemptsBeforeAttention)
+		?? parsePositiveInt(globalConfig?.failedToolAttemptsBeforeAttention)
+		?? DEFAULT_CONTROL_CONFIG.failedToolAttemptsBeforeAttention;
+	const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
+		?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
+		?? DEFAULT_CONTROL_CONFIG.notifyOn;
+	const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+	return {
+		enabled,
+		needsAttentionAfterMs,
+		activeNoticeAfterMs,
+		activeNoticeAfterTurns,
+		activeNoticeAfterTokens,
+		failedToolAttemptsBeforeAttention,
+		notifyOn: [...notifyOn],
+		notifyChannels: [...notifyChannels],
+	};
+}
+
+export function deriveActivityState(input: {
+	config: ResolvedControlConfig;
+	startedAt: number;
+	lastActivityAt?: number;
+	now?: number;
+}): ActivityState | undefined {
+	if (!input.config.enabled) return undefined;
+	const now = input.now ?? Date.now();
+	const lastActivity = input.lastActivityAt ?? input.startedAt;
+	const ageMs = Math.max(0, now - lastActivity);
+	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
+}
+
+export function buildControlEvent(input: {
+	type?: ControlEventType;
+	from?: ActivityState;
+	to: ActivityState;
+	runId: string;
+	agent: string;
+	index?: number;
+	ts?: number;
+	lastActivityAt?: number;
+	message?: string;
+	reason?: ControlEvent["reason"];
+	turns?: number;
+	tokens?: number;
+	toolCount?: number;
+	currentTool?: string;
+	currentToolDurationMs?: number;
+	currentPath?: string;
+	elapsedMs?: number;
+	recentFailureSummary?: string;
+}): ControlEvent {
+	const ts = input.ts ?? Date.now();
+	const type = input.type ?? (input.to === "active_long_running" ? "active_long_running" : "needs_attention");
+	const elapsedMs = input.elapsedMs ?? (input.lastActivityAt ? Math.max(0, ts - input.lastActivityAt) : undefined);
+	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+	const message = input.message ?? (type === "active_long_running"
+		? `${input.agent} is still active but long-running`
+		: elapsedSeconds !== undefined
+			? `${input.agent} needs attention (no observed activity for ${elapsedSeconds}s)`
+			: `${input.agent} needs attention`);
+	return {
+		type,
+		...(input.from ? { from: input.from } : {}),
+		to: input.to,
+		ts,
+		runId: input.runId,
+		agent: input.agent,
+		...(input.index !== undefined ? { index: input.index } : {}),
+		message,
+		reason: input.reason ?? (type === "active_long_running" ? "active_long_running" : "idle"),
+		...(input.turns !== undefined ? { turns: input.turns } : {}),
+		...(input.tokens !== undefined ? { tokens: input.tokens } : {}),
+		...(input.toolCount !== undefined ? { toolCount: input.toolCount } : {}),
+		...(input.currentTool ? { currentTool: input.currentTool } : {}),
+		...(input.currentToolDurationMs !== undefined ? { currentToolDurationMs: input.currentToolDurationMs } : {}),
+		...(input.currentPath ? { currentPath: input.currentPath } : {}),
+		...(elapsedMs !== undefined ? { elapsedMs } : {}),
+		...(input.recentFailureSummary ? { recentFailureSummary: input.recentFailureSummary } : {}),
+	};
+}
+
+export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: ControlEvent): boolean {
+	return config.enabled && config.notifyOn.includes(event.type);
+}
+
+export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
+	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+	return `${childKey}:${event.type}:${event.reason ?? "idle"}`;
+}
+
+export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
+	if (!shouldNotifyControlEvent(config, event)) return false;
+	const key = controlNotificationKey(event, childIntercomTarget);
+	if (seenKeys.has(key)) return false;
+	seenKeys.add(key);
+	return true;
+}
+
+function formatLongRunningFacts(event: ControlEvent): string | undefined {
+	const facts: string[] = [];
+	if (event.elapsedMs !== undefined) facts.push(`elapsed ${Math.floor(Math.max(0, event.elapsedMs) / 1000)}s`);
+	if (event.turns !== undefined) facts.push(`${event.turns} turns`);
+	if (event.tokens !== undefined) facts.push(`${event.tokens} tokens`);
+	if (event.toolCount !== undefined) facts.push(`${event.toolCount} tools`);
+	if (event.currentTool) facts.push(`tool ${event.currentTool}${event.currentToolDurationMs !== undefined ? ` ${Math.floor(Math.max(0, event.currentToolDurationMs) / 1000)}s` : ""}`);
+	if (event.currentPath) facts.push(`path ${event.currentPath}`);
+	return facts.length > 0 ? facts.join(" | ") : undefined;
+}
+
+export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const runTarget = event.runId;
+	if (event.reason === "completion_guard") {
+		return [
+			`Subagent failed: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			"Next: read the output artifact or session from the subagent result, then retry with a more explicit implementation prompt or handle the fix directly.",
+			childIntercomTarget ? `Run intercom target (may be inactive): ${childIntercomTarget}` : undefined,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	const nudgeCommand = childIntercomTarget
+		? `intercom({ action: "send", to: "${childIntercomTarget}", message: "What are you blocked on? Reply with the smallest next step or ask for a decision." })`
+		: undefined;
+	if (event.type === "active_long_running") {
+		const facts = formatLongRunningFacts(event);
+		return [
+			`Subagent active but long-running: ${event.agent}`,
+			`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+			`Signal: ${event.message}`,
+			facts ? `Facts: ${facts}` : undefined,
+			"Hint: Inspect status, then nudge if the work seems stuck.",
+			childIntercomTarget
+				? `Nudge: ${nudgeCommand}`
+				: "Nudge: no child message route registered",
+			`Status: subagent({ action: "status", id: "${runTarget}" })`,
+			`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+		].filter((line): line is string => Boolean(line)).join("\n");
+	}
+
+	return [
+		`Subagent needs attention: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
+		"Hint: Inspect status first unless the run is clearly blocked.",
+		childIntercomTarget
+			? `Nudge: ${nudgeCommand}`
+			: "Nudge: no child message route registered",
+		`Status: subagent({ action: "status", id: "${runTarget}" })`,
+		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+	].filter((line): line is string => Boolean(line)).join("\n");
+}
+
+export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const statusLabel = event.reason === "completion_guard"
+		? "subagent failed"
+		: event.type === "active_long_running"
+			? "subagent active but long-running"
+			: "subagent needs attention";
+	return [
+		statusLabel,
+		"",
+		event.reason === "completion_guard"
+			? `${event.agent} failed in run ${event.runId}.`
+			: event.type === "active_long_running"
+				? `${event.agent} is still active but long-running in run ${event.runId}.`
+				: `${event.agent} needs attention in run ${event.runId}.`,
+		"",
+		formatControlNoticeMessage(event, childIntercomTarget),
+	].join("\n");
+}