pi-subagents 0.40.0 → 0.42.0

package/src/inspectors/herdr/client.ts

@@ -0,0 +1,130 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+export type HerdrErrorCode =
+	| "HERDR_UNAVAILABLE"
+	| "HERDR_UNSUPPORTED_VERSION"
+	| "PANE_GONE"
+	| "NOT_FOUND"
+	| "TIMEOUT"
+	| "VALIDATION_ERROR";
+
+export type HerdrResult<T> =
+	| { ok: true; data: T }
+	| { ok: false; error: { code: HerdrErrorCode; message: string; details?: unknown } };
+
+export interface HerdrClient {
+	run<T = unknown>(args: string[], options?: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean }): Promise<HerdrResult<T>>;
+}
+
+type SpawnHerdr = (command: string, args: readonly string[], options: { shell: false; windowsHide: true; env: NodeJS.ProcessEnv }) => ChildProcess;
+
+function error(code: HerdrErrorCode, message: string, details?: unknown): HerdrResult<never> {
+	return { ok: false, error: { code, message, ...(details !== undefined ? { details } : {}) } };
+}
+
+function parseLastJson(value: string): unknown | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+	try { return JSON.parse(trimmed) as unknown; } catch {}
+	for (const line of trimmed.split(/\r?\n/).reverse()) {
+		try { return JSON.parse(line) as unknown; } catch {}
+	}
+	return undefined;
+}
+
+function normalizeCode(raw: unknown): HerdrErrorCode {
+	const code = String(raw ?? "").toLowerCase();
+	if (code.includes("timeout") || code.includes("timed_out")) return "TIMEOUT";
+	if (code.includes("gone")) return "PANE_GONE";
+	if (code.includes("not_found") || code.includes("not-found") || code === "no_such_pane") return "NOT_FOUND";
+	return "VALIDATION_ERROR";
+}
+
+export function createHerdrClient(options: { bin?: string; spawn?: SpawnHerdr } = {}): HerdrClient {
+	const bin = options.bin ?? process.env.HERDR_BIN ?? "herdr";
+	const spawnImpl = options.spawn ?? spawn;
+	return {
+		run<T>(args: string[], runOptions: { timeoutMs?: number; signal?: AbortSignal; textOk?: boolean } = {}): Promise<HerdrResult<T>> {
+			return new Promise((resolve) => {
+				let child: ChildProcess;
+				try {
+					child = spawnImpl(bin, args, { shell: false, windowsHide: true, env: process.env });
+				} catch (cause) {
+					const code = (cause as NodeJS.ErrnoException | undefined)?.code;
+					resolve(error("HERDR_UNAVAILABLE", code === "ENOENT"
+						? "Herdr is not installed or is not on PATH. Install Herdr 0.7.5+ or set HERDR_BIN."
+						: `Failed to start Herdr: ${cause instanceof Error ? cause.message : String(cause)}`));
+					return;
+				}
+				let stdout = "";
+				let stderr = "";
+				let settled = false;
+				const finish = (result: HerdrResult<T>) => {
+					if (settled) return;
+					settled = true;
+					clearTimeout(timer);
+					runOptions.signal?.removeEventListener("abort", abort);
+					resolve(result);
+				};
+				const abort = () => {
+					try { child.kill(); } catch {}
+					finish(error("TIMEOUT", `Herdr command '${args.join(" ")}' was aborted.`));
+				};
+				const timer = setTimeout(() => {
+					try { child.kill(); } catch {}
+					finish(error("TIMEOUT", `Herdr command '${args.join(" ")}' timed out after ${runOptions.timeoutMs ?? 15_000}ms.`));
+				}, runOptions.timeoutMs ?? 15_000);
+				timer.unref?.();
+				if (runOptions.signal?.aborted) abort();
+				else runOptions.signal?.addEventListener("abort", abort, { once: true });
+				child.stdout?.on("data", (chunk) => { stdout += chunk.toString(); });
+				child.stderr?.on("data", (chunk) => { stderr += chunk.toString(); });
+				child.on("error", (cause) => {
+					const code = (cause as NodeJS.ErrnoException).code;
+					finish(error("HERDR_UNAVAILABLE", code === "ENOENT"
+						? "Herdr is not installed or is not on PATH. Install Herdr 0.7.5+ or set HERDR_BIN."
+						: `Failed to run Herdr: ${cause.message}`));
+				});
+				child.on("close", (exitCode) => {
+					const parsed = parseLastJson(stdout) ?? (exitCode === 0 ? undefined : parseLastJson(stderr));
+					if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && "error" in parsed) {
+						const raw = (parsed as { error?: { code?: unknown; message?: unknown } }).error;
+						finish(error(normalizeCode(raw?.code), String(raw?.message ?? "Herdr command failed."), raw));
+						return;
+					}
+					if (exitCode === 0) {
+						if (parsed !== undefined) {
+							const envelope = parsed as { result?: unknown };
+							finish({ ok: true, data: (envelope.result ?? parsed) as T });
+						} else if (runOptions.textOk) finish({ ok: true, data: stdout.trim() as T });
+						else finish({ ok: true, data: {} as T });
+						return;
+					}
+					const message = stderr.split(/\r?\n/).find((line) => line.trim())?.trim() ?? `Herdr exited with code ${exitCode}.`;
+					finish(error("VALIDATION_ERROR", message, { exitCode }));
+				});
+			});
+		},
+	};
+}
+
+export interface HerdrVersion { major: number; minor: number; patch: number }
+
+export function parseHerdrVersion(value: string): HerdrVersion | undefined {
+	const match = /(\d+)\.(\d+)\.(\d+)/.exec(value);
+	return match ? { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) } : undefined;
+}
+
+export function supportsRawPanes(version: HerdrVersion): boolean {
+	return version.major > 0 || version.minor > 7 || (version.minor === 7 && version.patch >= 5);
+}
+
+export async function detectHerdr(client: HerdrClient, signal?: AbortSignal): Promise<HerdrResult<{ version: HerdrVersion; versionText: string }>> {
+	const result = await client.run<string>(["--version"], { timeoutMs: 3_000, signal, textOk: true });
+	if (result.ok === false) return result;
+	const versionText = typeof result.data === "string" ? result.data : JSON.stringify(result.data);
+	const version = parseHerdrVersion(versionText);
+	if (!version) return error("VALIDATION_ERROR", `Could not parse the Herdr version from '${versionText}'.`);
+	if (!supportsRawPanes(version)) return error("HERDR_UNSUPPORTED_VERSION", `Herdr ${versionText} does not support raw inspector panes. Upgrade to Herdr 0.7.5 or newer.`);
+	return { ok: true, data: { version, versionText } };
+}

package/src/inspectors/herdr/inspector-runner.ts

@@ -0,0 +1,141 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { fileURLToPath } from "node:url";
+import { parseMissionRecord } from "../../missions/store.ts";
+import type { MissionRecord } from "../../missions/types.ts";
+import { requestAsyncSteer, requestAsyncStop } from "../../runs/background/control-channel.ts";
+import { formatAsyncRunTranscript } from "../../runs/background/fleet-view.ts";
+import type { AsyncStatus } from "../../shared/types.ts";
+import { readStatus } from "../../shared/utils.ts";
+
+export interface RunnerOptions {
+	asyncDir: string;
+	runId: string;
+	index?: number;
+	missionPath?: string;
+	refreshMs: number;
+	allowSteer?: boolean;
+	allowStop?: boolean;
+}
+
+function readMission(filePath: string | undefined): MissionRecord | undefined {
+	if (!filePath) return undefined;
+	try { return parseMissionRecord(JSON.parse(fs.readFileSync(filePath, "utf-8")), filePath); } catch { return undefined; }
+}
+
+export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir: string; index?: number; mission?: MissionRecord; allowSteer?: boolean; allowStop?: boolean }): string {
+	const { status, asyncDir, mission } = input;
+	const lines = [
+		`pi-subagents inspector for ${status.runId}`,
+		"This pane mirrors lifecycle artifacts; closing it does not stop the run.",
+		"",
+	];
+	if (mission) {
+		lines.push(`Mission: ${mission.title} (${mission.status})`, `Mission id: ${mission.id}`);
+		const open = mission.decisions.filter((decision) => decision.status === "open");
+		if (open.length) lines.push(`Open decisions: ${open.map((decision) => `${decision.id}: ${decision.title}`).join(" | ")}`);
+		lines.push("");
+	}
+	lines.push(formatAsyncRunTranscript(status, asyncDir, { index: input.index, lines: 60 }));
+	const controls = [input.allowSteer === false ? undefined : "steer <message>", input.allowStop === false ? undefined : "stop", "status"].filter(Boolean);
+	lines.push("", `Controls: ${controls.join(" | ")}`, "Supervisor replies remain in the parent Pi session (subagent_supervisor/intercom).");
+	return lines.join("\n");
+}
+
+function parseArgs(argv: string[]): RunnerOptions {
+	const values = new Map<string, string>();
+	for (let index = 0; index < argv.length; index += 2) {
+		const key = argv[index];
+		const value = argv[index + 1];
+		if (!key?.startsWith("--") || value === undefined) throw new Error(`Invalid inspector argument '${key ?? ""}'.`);
+		values.set(key, value);
+	}
+	const asyncDir = values.get("--async-dir");
+	const runId = values.get("--run-id");
+	if (!asyncDir || !runId) throw new Error("Inspector requires --async-dir and --run-id.");
+	const indexRaw = values.get("--index");
+	const childIndex = indexRaw === undefined ? undefined : Number(indexRaw);
+	if (childIndex !== undefined && (!Number.isInteger(childIndex) || childIndex < 0)) throw new Error("--index must be a non-negative integer.");
+	const refreshRaw = values.get("--refresh-ms");
+	const refreshMs = refreshRaw === undefined ? 1_500 : Number(refreshRaw);
+	if (!Number.isInteger(refreshMs) || refreshMs < 250) throw new Error("--refresh-ms must be an integer >= 250.");
+	return {
+		asyncDir: path.resolve(asyncDir),
+		runId,
+		...(childIndex !== undefined ? { index: childIndex } : {}),
+		...(values.get("--mission-path") ? { missionPath: path.resolve(values.get("--mission-path")!) } : {}),
+		refreshMs,
+		allowSteer: values.get("--allow-steer") !== "false",
+		allowStop: values.get("--allow-stop") !== "false",
+	};
+}
+
+function isTerminal(status: AsyncStatus): boolean {
+	return status.state !== "queued" && status.state !== "running";
+}
+
+export function submitInspectorControl(options: RunnerOptions, line: string): string {
+	const command = line.trim();
+	if (!command || command === "status") return "Status refreshed.";
+	const status = readStatus(options.asyncDir);
+	if (!status || status.runId !== options.runId) throw new Error(`Lifecycle status for run '${options.runId}' is unavailable.`);
+	if (command === "stop") {
+		if (options.allowStop === false) throw new Error("Authority policy does not allow stop from this inspector.");
+		if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be stopped.`);
+		requestAsyncStop(options.asyncDir, { source: "herdr-inspector" });
+		return `Stop requested for run ${options.runId}.`;
+	}
+	if (command.startsWith("steer ")) {
+		if (options.allowSteer === false) throw new Error("Authority policy does not allow steer from this inspector.");
+		const message = command.slice("steer ".length).trim();
+		if (!message) throw new Error("steer requires a message.");
+		if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be steered.`);
+		const runningIndexes = (status.steps ?? []).map((step, index) => step.status === "running" ? index : undefined).filter((index): index is number => index !== undefined);
+		const targetIndex = options.index ?? (status.mode === "single" ? 0 : undefined);
+		if (targetIndex === undefined && runningIndexes.length === 0) throw new Error("No running child is available to steer. Open a child-specific inspector for a pending child.");
+		requestAsyncSteer(options.asyncDir, {
+			message,
+			...(targetIndex !== undefined ? { targetIndex } : { targetIndexes: runningIndexes }),
+			source: "herdr-inspector",
+		});
+		return `Steering queued for run ${options.runId}.`;
+	}
+	if (command.startsWith("reply ")) throw new Error("Supervisor replies are owned by the parent Pi session; use subagent_supervisor/intercom there.");
+	throw new Error("Unknown control. Use steer <message>, stop, or status.");
+}
+
+export function runInspector(argv = process.argv.slice(2)): void {
+	const options = parseArgs(argv);
+	let notice = "";
+	let timer: ReturnType<typeof setInterval> | undefined;
+	const render = () => {
+		const status = readStatus(options.asyncDir);
+		if (!status || status.runId !== options.runId) {
+			process.stdout.write(`\x1b[2J\x1b[Hpi-subagents inspector\n\nLifecycle status for ${options.runId} is unavailable.\n`);
+			return;
+		}
+		process.stdout.write(`\x1b[2J\x1b[H${formatInspectorDashboard({ status, asyncDir: options.asyncDir, index: options.index, mission: readMission(options.missionPath), allowSteer: options.allowSteer, allowStop: options.allowStop })}${notice ? `\n\n${notice}` : ""}\n> `);
+		if (isTerminal(status) && timer) {
+			clearInterval(timer);
+			timer = undefined;
+		}
+	};
+	const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+	rl.on("line", (line) => {
+		try { notice = submitInspectorControl(options, line); } catch (cause) { notice = `Control error: ${cause instanceof Error ? cause.message : String(cause)}`; }
+		render();
+	});
+	render();
+	if (!isTerminal(readStatus(options.asyncDir) ?? { state: "failed" } as AsyncStatus)) {
+		timer = setInterval(render, options.refreshMs);
+		timer.unref?.();
+	}
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url))) {
+	try { runInspector(); } catch (cause) {
+		process.stderr.write(`Herdr inspector failed: ${cause instanceof Error ? cause.message : String(cause)}\n`);
+		process.exitCode = 1;
+	}
+}

package/src/inspectors/herdr/project-panes.ts

@@ -0,0 +1,154 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { getPiSpawnCommand } from "../../runs/shared/pi-spawn.ts";
+import { writeAtomicJson } from "../../shared/atomic-json.ts";
+import type { Details } from "../../shared/types.ts";
+import { createHerdrClient, detectHerdr, type HerdrClient, type HerdrErrorCode, type HerdrResult } from "./client.ts";
+
+export const HERDR_PROJECT_PANE_ACTIONS = ["project.open", "project.status", "project.close"] as const;
+export type HerdrProjectPaneAction = typeof HERDR_PROJECT_PANE_ACTIONS[number];
+
+export interface HerdrProjectPaneBinding {
+	schemaVersion: 1;
+	kind: "herdr-project-pane";
+	projectRoot: string;
+	paneId: string;
+	openedAt: string;
+	lastFocusedAt?: string;
+	herdrVersion?: string;
+	command: string;
+	startupMessage?: string;
+}
+
+interface ProjectPaneParams {
+	cwd?: string;
+	message?: string;
+	focus?: boolean;
+}
+
+interface ProjectPaneDeps {
+	cwd: string;
+	client?: HerdrClient;
+	signal?: AbortSignal;
+	now?: () => Date;
+}
+
+function result(text: string, isError = false): AgentToolResult<Details> {
+	return { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}), details: { mode: "management", results: [] } };
+}
+
+function formatHerdrError(input: { code: HerdrErrorCode; message: string }): string {
+	return `Herdr project pane error (${input.code}): ${input.message}`;
+}
+
+function projectPaneDir(projectRoot: string): string {
+	return path.join(projectRoot, ".pi-subagents", "project-panes");
+}
+
+function bindingPath(projectRoot: string): string {
+	return path.join(projectPaneDir(projectRoot), "herdr.json");
+}
+
+function parseBinding(value: unknown): HerdrProjectPaneBinding | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const input = value as Partial<HerdrProjectPaneBinding>;
+	if (input.schemaVersion !== 1 || input.kind !== "herdr-project-pane") return undefined;
+	if (typeof input.projectRoot !== "string" || typeof input.paneId !== "string" || typeof input.openedAt !== "string" || typeof input.command !== "string") return undefined;
+	return input as HerdrProjectPaneBinding;
+}
+
+export function readHerdrProjectPaneBinding(projectRoot: string): HerdrProjectPaneBinding | undefined {
+	try { return parseBinding(JSON.parse(fs.readFileSync(bindingPath(projectRoot), "utf-8"))); } catch { return undefined; }
+}
+
+function extractPaneId(value: unknown): string | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	const pane = record.pane && typeof record.pane === "object" && !Array.isArray(record.pane) ? record.pane as Record<string, unknown> : record;
+	for (const key of ["pane_id", "paneId", "id"]) if (typeof pane[key] === "string") return pane[key];
+	return undefined;
+}
+
+function shellQuote(value: string): string {
+	if (process.platform === "win32") return `"${value.replaceAll('"', '\\"')}"`;
+	return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+function resolveProjectRoot(params: ProjectPaneParams, deps: ProjectPaneDeps): string | { error: string } {
+	const requested = params.cwd?.trim() || deps.cwd;
+	const resolved = path.resolve(requested);
+	try {
+		const stat = fs.statSync(resolved);
+		if (!stat.isDirectory()) return { error: `Project pane target '${resolved}' is not a directory.` };
+		return fs.realpathSync(resolved);
+	} catch (cause) {
+		return { error: `Project pane target '${resolved}' is unavailable: ${cause instanceof Error ? cause.message : String(cause)}` };
+	}
+}
+
+async function paneExists(client: HerdrClient, paneId: string, signal?: AbortSignal): Promise<HerdrResult<unknown>> {
+	return client.run(["pane", "get", paneId], { timeoutMs: 5_000, signal });
+}
+
+function projectPaneCommand(message: string | undefined): string {
+	const args = message?.trim() ? [message.trim()] : [];
+	const command = getPiSpawnCommand(args);
+	return [command.command, ...command.args].map(shellQuote).join(" ");
+}
+
+export async function handleHerdrProjectPaneAction(action: HerdrProjectPaneAction, params: ProjectPaneParams, deps: ProjectPaneDeps): Promise<AgentToolResult<Details>> {
+	const projectRoot = resolveProjectRoot(params, deps);
+	if (typeof projectRoot !== "string") return result(projectRoot.error, true);
+	const client = deps.client ?? createHerdrClient();
+	const existing = readHerdrProjectPaneBinding(projectRoot);
+
+	if (action === "project.status") {
+		if (!existing) return result(`No Herdr project pane binding exists for ${projectRoot}.`);
+		const live = await paneExists(client, existing.paneId, deps.signal);
+		if (live.ok === false) return result(`${formatHerdrError(live.error)}\nBinding: ${bindingPath(projectRoot)}`, true);
+		return result(`Herdr project pane ${existing.paneId} is open for ${projectRoot}.\nBinding: ${bindingPath(projectRoot)}`);
+	}
+
+	if (action === "project.close") {
+		if (!existing) return result(`No Herdr project pane binding exists for ${projectRoot}.`);
+		const closed = await client.run(["pane", "close", existing.paneId], { timeoutMs: 10_000, signal: deps.signal });
+		if (closed.ok === false && closed.error.code !== "NOT_FOUND" && closed.error.code !== "PANE_GONE") return result(formatHerdrError(closed.error), true);
+		fs.rmSync(bindingPath(projectRoot), { force: true });
+		return result(`Closed Herdr project pane ${existing.paneId} for ${projectRoot}.`);
+	}
+
+	const detected = await detectHerdr(client, deps.signal);
+	if (detected.ok === false) return result(formatHerdrError(detected.error), true);
+	if (existing) {
+		const live = await paneExists(client, existing.paneId, deps.signal);
+		if (live.ok) return result(`Herdr project pane ${existing.paneId} is already open for ${projectRoot}.${params.focus ? " Herdr cannot refocus an arbitrary raw pane id; select it in the Herdr UI." : ""}`);
+	}
+	const splitArgs = ["pane", "split", "--current", "--direction", "right", "--cwd", projectRoot];
+	if (params.focus !== false) splitArgs.push("--focus");
+	const split = await client.run(splitArgs, { timeoutMs: 15_000, signal: deps.signal });
+	if (split.ok === false) return result(formatHerdrError(split.error), true);
+	const paneId = extractPaneId(split.data);
+	if (!paneId) return result("Herdr project pane error (PANE_GONE): pane split returned no pane id.", true);
+	const startupMessage = params.message?.trim();
+	const command = projectPaneCommand(startupMessage);
+	const started = await client.run(["pane", "run", paneId, command], { timeoutMs: 15_000, signal: deps.signal });
+	if (started.ok === false) {
+		await client.run(["pane", "close", paneId], { timeoutMs: 5_000 });
+		return result(formatHerdrError(started.error), true);
+	}
+	const now = (deps.now?.() ?? new Date()).toISOString();
+	const binding: HerdrProjectPaneBinding = {
+		schemaVersion: 1,
+		kind: "herdr-project-pane",
+		projectRoot,
+		paneId,
+		openedAt: now,
+		...(params.focus !== false ? { lastFocusedAt: now } : {}),
+		herdrVersion: detected.data.versionText,
+		command,
+		...(startupMessage ? { startupMessage } : {}),
+	};
+	writeAtomicJson(bindingPath(projectRoot), binding);
+	return result(`Opened Herdr project pane ${paneId} for ${projectRoot}. The pane runs its own Pi session; subagents launched there belong to that project.`);
+}