@maxiaochao/pi-toolkit 0.9.6 → 0.10.0

package/packages/herdr-subagents/src/continue-run.ts

@@ -0,0 +1,87 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { HerdrAutomation } from "./herdr.ts";
+import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { writeJsonAtomic } from "./state.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+import { RunPaneAllocator } from "./run-pane-allocator.ts";
+import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
+import { applyReport, applyTaskStatus, readRunRecord, readTaskRecord, settleAttemptFailure } from "./records.ts";
+import { isAbortError } from "./errors.ts";
+
+export interface ContinueQueuedRunOptions {
+	cleanup?: boolean;
+	onStalled?: (message: string) => void;
+	onCleanupError?: (message: string) => void;
+	onUpdate?: () => void | Promise<void>;
+	signal?: AbortSignal;
+}
+
+export async function continueQueuedRun(runDirectory: string, herdr: HerdrAutomation, options: ContinueQueuedRunOptions = {}): Promise<void> {
+	const runFile = join(runDirectory, "run.json");
+	const run = await readRunRecord(runFile);
+	const taskDirectories = readdirSync(join(runDirectory, "tasks")).sort().map((entry) => join(runDirectory, "tasks", entry));
+	const queuedDirectories: string[] = [];
+	let blockedCount = 0;
+	for (const directory of taskDirectories) {
+		const status = (await readTaskRecord(join(directory, "task.json"))).status;
+		if (status === "queued") queuedDirectories.push(directory);
+		if (status === "blocked") blockedCount += 1;
+	}
+	if (!queuedDirectories.length) return;
+	const availableSlots = Math.max(0, (Number(run.effectiveConcurrency) || 1) - blockedCount);
+	if (availableSlots === 0) return;
+	const concurrency = Math.min(availableSlots, queuedDirectories.length);
+	const paneAllocator = new RunPaneAllocator({ herdr, run, runFile, signal: options.signal, validateExistingPane: true, onCleanupError: options.onCleanupError });
+	let nextIndex = 0;
+	const runOne = async (directory: string): Promise<string> => {
+		const taskFile = join(directory, "task.json");
+		const task = await readTaskRecord(taskFile);
+		let paneId = "";
+		const reportFile = join(directory, "report.json");
+		try {
+			paneId = await paneAllocator.allocate(directory);
+			const agentName = liveAgentName(task.id, Number(task.attempt ?? 0) + 1);
+			const paneLabel = `${String(task.order).padStart(2, "0")} · ${task.name ?? task.agent}`;
+			await herdr.renamePane(paneId, paneLabel, options.signal);
+			applyTaskStatus(task, "running");
+			Object.assign(task, { tabId: run.tabId, paneId, paneLabel, agentName, attempt: Number(task.attempt ?? 0) + 1, startedAt: new Date().toISOString() });
+			await writeJsonAtomic(taskFile, task);
+			await options.onUpdate?.();
+			const report = (await promptLiveAgent({ herdr, task: { ...task, id: task.id, sessionFile: task.sessionFile }, paneId, prompt: task.prompt, systemPromptFile: join(directory, "system-prompt.md"), agentName, signal: options.signal, stalledWarningMs: run.stalledWarningSeconds ? Number(run.stalledWarningSeconds) * 1000 : undefined, onStalled: () => options.onStalled?.(`${task.name ?? task.agent} appears stalled; it is still running.`) })).report;
+			applyReport(task, report);
+		} catch (error) {
+			await settleAttemptFailure(task, reportFile, {
+				cancelled: isAbortError(error, options.signal),
+				error: error instanceof Error ? error.message : String(error),
+				name: String(task.name ?? task.agent ?? "Task"),
+			});
+		}
+		await writeJsonAtomic(taskFile, task);
+		await options.onUpdate?.();
+		return task.status;
+	};
+	const worker = async () => {
+		while (true) {
+			const index = nextIndex++;
+			if (index >= queuedDirectories.length) return;
+			if (await runOne(queuedDirectories[index]) === "blocked") return;
+		}
+	};
+	await Promise.all(Array.from({ length: concurrency }, worker));
+	if (options.signal?.aborted) {
+		for (const directory of taskDirectories) {
+			const taskFile = join(directory, "task.json");
+			const task = await readTaskRecord(taskFile);
+			if (task.status !== "queued") continue;
+			applyTaskStatus(task, "cancelled", { error: "Parent Pi session closed." });
+			await writeJsonAtomic(taskFile, task);
+		}
+	}
+	const statuses = await Promise.all(taskDirectories.map(async (directory) => (await readTaskRecord(join(directory, "task.json"))).status));
+	applyRunStatus(run, options.signal?.aborted ? "cancelled" : aggregateTaskStatus(statuses));
+	await writeJsonAtomic(runFile, run);
+	if (options.cleanup !== false && run.status !== "blocked" && run.tabId) {
+		await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal: options.signal, onError: options.onCleanupError, failureStatus: "failed" });
+	}
+}

package/packages/herdr-subagents/src/dispatcher.ts

@@ -0,0 +1,73 @@
+interface QueuedRun<T> {
+	id: string;
+	execute: () => Promise<T>;
+	resolve: (value: T) => void;
+	reject: (error: unknown) => void;
+}
+
+export interface DispatcherSnapshot {
+	activeRunId?: string;
+	queuedRunIds: string[];
+}
+
+export class RunDispatcher {
+	private activeRunId?: string;
+	private readonly queue: QueuedRun<unknown>[] = [];
+	private readonly onChange?: (snapshot: DispatcherSnapshot) => void;
+	private paused = false;
+	private retainedRunId?: string;
+
+	constructor(onChange?: (snapshot: DispatcherSnapshot) => void) { this.onChange = onChange; }
+
+	submit<T>(id: string, execute: () => Promise<T>): Promise<T> {
+		const promise = new Promise<T>((resolve, reject) => this.queue.push({ id, execute, resolve: resolve as (value: unknown) => void, reject }));
+		this.changed();
+		void this.drain();
+		return promise;
+	}
+
+	snapshot(): DispatcherSnapshot {
+		return { ...(this.activeRunId ? { activeRunId: this.activeRunId } : {}), queuedRunIds: this.queue.map((run) => run.id) };
+	}
+
+	pause(): void { this.paused = true; this.changed(); }
+	resume(): void { this.paused = false; this.changed(); void this.drain(); }
+	retain(id: string): void {
+		if (this.activeRunId !== id) throw new Error(`Cannot retain inactive run '${id}'.`);
+		this.retainedRunId = id;
+		this.changed();
+	}
+	release(id: string): boolean {
+		if (this.activeRunId !== id || this.retainedRunId !== id) return false;
+		this.retainedRunId = undefined;
+		this.activeRunId = undefined;
+		this.changed();
+		void this.drain();
+		return true;
+	}
+	cancelQueued(reason: Error): string[] {
+		const cancelled = this.queue.splice(0);
+		for (const run of cancelled) run.reject(reason);
+		this.changed();
+		return cancelled.map((run) => run.id);
+	}
+
+	private changed(): void { this.onChange?.(this.snapshot()); }
+
+	private async drain(): Promise<void> {
+		if (this.activeRunId || this.paused) return;
+		const run = this.queue.shift();
+		if (!run) { this.changed(); return; }
+		this.activeRunId = run.id;
+		this.changed();
+		try { run.resolve(await run.execute()); }
+		catch (error) { run.reject(error); }
+		finally {
+			if (this.retainedRunId !== run.id) {
+				this.activeRunId = undefined;
+				this.changed();
+				void this.drain();
+			}
+		}
+	}
+}

package/packages/herdr-subagents/src/errors.ts

@@ -0,0 +1,3 @@
+export function isAbortError(error: unknown, signal?: AbortSignal): boolean {
+	return signal?.aborted === true || (error instanceof Error && (error.name === "AbortError" || /abort/i.test(error.message)));
+}

package/packages/herdr-subagents/src/fleet-controller.ts

@@ -0,0 +1,82 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { Container, isKeyRelease, matchesKey, Text } from "@earendil-works/pi-tui";
+import type { HerdrAutomation } from "./herdr.ts";
+import { fleetEditorHasFocus, FleetSelection, fleetLines } from "./fleet.ts";
+import { focusActiveTask } from "./monitor.ts";
+import { isActiveStatus } from "./records.ts";
+import type { HerdrSubagentsBatchDetails } from "./tool.ts";
+
+export class FleetController {
+	private activeBatch?: HerdrSubagentsBatchDetails;
+	private readonly selection = new FleetSelection(matchesKey);
+	private unsubscribeInput?: () => void;
+	private ui?: ExtensionUIContext;
+	private tui?: { focusedComponent?: unknown };
+
+	constructor(
+		private readonly herdr: HerdrAutomation,
+		private readonly isEditor: (value: unknown) => boolean,
+		private readonly createWidget?: (lines: string[]) => Container,
+	) {}
+
+	get active(): HerdrSubagentsBatchDetails | undefined { return this.activeBatch; }
+
+	bind(ui: ExtensionUIContext, tuiMode: boolean): void {
+		this.unsubscribeInput?.();
+		this.ui = ui;
+		this.unsubscribeInput = tuiMode ? ui.onTerminalInput((data) => this.handleInput(data)) : undefined;
+	}
+
+	sync(details: unknown): void {
+		const batch = details as Partial<HerdrSubagentsBatchDetails>;
+		if (!batch.activity || !batch.label || !batch.status) return;
+		this.activeBatch = isActiveStatus(batch.status) ? batch as HerdrSubagentsBatchDetails : undefined;
+		this.render();
+	}
+
+	setActive(batch: HerdrSubagentsBatchDetails | undefined): void {
+		this.activeBatch = batch;
+		this.render();
+	}
+
+	clearRun(runId?: string): void {
+		if (!runId || this.activeBatch?.runId === runId) this.activeBatch = undefined;
+		this.render();
+	}
+
+	resetSelection(): void { this.selection.reset(); this.render(); }
+	async focus(taskNumber: number): Promise<boolean> { return this.activeBatch ? focusActiveTask(this.activeBatch, taskNumber, this.herdr) : false; }
+
+	shutdown(): void {
+		this.unsubscribeInput?.();
+		this.unsubscribeInput = undefined;
+		this.activeBatch = undefined;
+		this.selection.reset();
+		this.render();
+	}
+
+	render(): void {
+		if (!this.ui) return;
+		this.ui.setWidget("herdr-subagents", this.activeBatch ? ((tui) => {
+			this.tui = tui as { focusedComponent?: unknown };
+			const lines = fleetLines(this.activeBatch as HerdrSubagentsBatchDetails, this.selection);
+			if (this.createWidget) return this.createWidget(lines);
+			const container = new Container();
+			for (const line of lines) container.addChild(new Text(line, 1, 0));
+			return container;
+		}) : undefined, { placement: "belowEditor" });
+	}
+
+	private handleInput(data: string): { consume: true } | undefined {
+		if (!this.activeBatch || isKeyRelease(data)) return undefined;
+		if (!fleetEditorHasFocus(this.tui?.focusedComponent, this.isEditor)) {
+			this.selection.reset();
+			this.render();
+			return undefined;
+		}
+		const result = this.selection.handle(data, this.ui?.getEditorText() ?? "", this.activeBatch.activity.length);
+		if (result.changed) this.render();
+		if (result.focusTask) void focusActiveTask(this.activeBatch, result.focusTask, this.herdr);
+		return result.consume ? { consume: true } : undefined;
+	}
+}

package/packages/herdr-subagents/src/fleet.ts

@@ -0,0 +1,56 @@
+import type { BatchResult } from "./batch-runner.ts";
+
+type FleetKey = "up" | "down" | "enter" | "escape";
+type KeyMatcher = (data: string, key: FleetKey) => boolean;
+
+const legacyKeys: Record<FleetKey, string> = { up: "\u001b[A", down: "\u001b[B", enter: "\r", escape: "\u001b" };
+const legacyMatchesKey: KeyMatcher = (data, key) => data === legacyKeys[key];
+
+export interface FleetInputResult { consume?: boolean; focusTask?: number; changed?: boolean; }
+
+export function fleetEditorHasFocus(focused: unknown, isEditor: (value: unknown) => boolean): boolean {
+	return isEditor(focused);
+}
+
+export class FleetSelection {
+	private selected = 0;
+	private selecting = false;
+	private readonly matchesKey: KeyMatcher;
+
+	constructor(matchesKey: KeyMatcher = legacyMatchesKey) { this.matchesKey = matchesKey; }
+
+	reset(): void { this.selected = 0; this.selecting = false; }
+	isSelecting(): boolean { return this.selecting; }
+	selectedIndex(taskCount: number): number { return Math.min(this.selected, Math.max(0, taskCount - 1)); }
+
+	handle(data: string, editorText: string, taskCount: number): FleetInputResult {
+		if (taskCount === 0) { this.reset(); return {}; }
+		if (!this.selecting) {
+			if (!this.matchesKey(data, "down") || editorText.length !== 0) return {};
+			this.selecting = true;
+			this.selected = 0;
+			return { consume: true, changed: true };
+		}
+		if (this.matchesKey(data, "up") || this.matchesKey(data, "down")) {
+			const delta = this.matchesKey(data, "up") ? -1 : 1;
+			this.selected = (this.selected + delta + taskCount) % taskCount;
+			return { consume: true, changed: true };
+		}
+		if (this.matchesKey(data, "enter")) return { consume: true, focusTask: this.selected + 1 };
+		if (this.matchesKey(data, "escape")) { this.selecting = false; return { consume: true, changed: true }; }
+		this.selecting = false;
+		return { changed: true };
+	}
+}
+
+export function fleetLines(batch: Pick<BatchResult, "label" | "activity">, selection: FleetSelection): string[] {
+	const counts = new Map<string, number>();
+	for (const task of batch.activity) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	const summary = ["running", "queued", "blocked", "failed", "completed", "cancelled"]
+		.filter((status) => counts.has(status)).map((status) => `${status} ${counts.get(status)}`).join(" · ");
+	const selected = selection.selectedIndex(batch.activity.length);
+	return [
+		`Subagents · ${batch.label} · ${summary}`,
+		...batch.activity.map((task, index) => `${selection.isSelecting() && index === selected ? "›" : " "} ${String(task.index + 1).padStart(2, "0")} · ${task.name}  ${task.status}`),
+	];
+}

package/packages/herdr-subagents/src/herdr.ts

@@ -0,0 +1,224 @@
+import { spawn } from "node:child_process";
+
+export interface CreateTabRequest {
+	workspaceId: string;
+	cwd: string;
+	label: string;
+	env: Record<string, string>;
+	focus: boolean;
+	signal?: AbortSignal;
+}
+
+export interface StartAgentRequest {
+	name: string;
+	kind: "pi";
+	paneId: string;
+	args: string[];
+	signal?: AbortSignal;
+}
+
+export interface PromptAgentRequest {
+	target: string;
+	prompt: string;
+	signal?: AbortSignal;
+}
+
+export interface SplitPaneRequest {
+	paneId: string;
+	cwd: string;
+	direction: "right" | "down";
+	focus: boolean;
+	env?: Record<string, string>;
+	signal?: AbortSignal;
+}
+
+export interface HerdrAutomation {
+	createTab(request: CreateTabRequest): Promise<{ tabId: string; paneId: string }>;
+	startAgent(request: StartAgentRequest): Promise<void>;
+	promptAgent(request: PromptAgentRequest): Promise<{ status?: string }>;
+	splitPane(request: SplitPaneRequest): Promise<{ paneId: string }>;
+	renamePane(paneId: string, label: string, signal?: AbortSignal): Promise<void>;
+	renameTab(tabId: string, label: string, signal?: AbortSignal): Promise<void>;
+	focusPane(paneId: string, signal?: AbortSignal): Promise<void>;
+	isTabFocused(tabId: string, signal?: AbortSignal): Promise<boolean>;
+	waitForTabUnfocused(tabId: string, signal?: AbortSignal): Promise<void>;
+	paneExists(paneId: string, signal?: AbortSignal): Promise<boolean>;
+	isTaskRunning(paneId: string, signal?: AbortSignal): Promise<boolean>;
+	closeTab(tabId: string, signal?: AbortSignal): Promise<void>;
+}
+
+interface HerdrResponse {
+	result?: {
+		tab?: { tab_id?: string; focused?: boolean };
+		root_pane?: { pane_id?: string };
+		pane?: { pane_id?: string };
+		agent?: { status?: string };
+		process_info?: { foreground_processes?: Array<{ name?: string; argv?: string[] }> };
+	};
+}
+
+export class HerdrCommandError extends Error {
+	readonly args: string[];
+	readonly exitCode: number | null;
+	readonly stderr: string;
+
+	constructor(
+		message: string,
+		args: string[],
+		exitCode: number | null,
+		stderr: string,
+	) {
+		super(message);
+		this.name = "HerdrCommandError";
+		this.args = args;
+		this.exitCode = exitCode;
+		this.stderr = stderr;
+	}
+}
+
+async function runCommand(binary: string, args: string[], signal?: AbortSignal): Promise<string> {
+	return await new Promise<string>((resolve, reject) => {
+		let stdout = "";
+		let stderr = "";
+		let spawnError: Error | undefined;
+		const child = spawn(binary, args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			env: process.env,
+			shell: false,
+		});
+		child.stdout.on("data", (chunk: Buffer | string) => {
+			stdout += chunk.toString();
+		});
+		child.stderr.on("data", (chunk: Buffer | string) => {
+			stderr += chunk.toString();
+		});
+		child.once("error", (error) => {
+			spawnError = error;
+		});
+		const abort = () => child.kill("SIGTERM");
+		const removeAbortListener = () => signal?.removeEventListener("abort", abort);
+		child.once("close", (code) => {
+			removeAbortListener();
+			if (spawnError) {
+				reject(new HerdrCommandError(spawnError.message, args, 1, stderr));
+				return;
+			}
+			if (code !== 0) {
+				const detail = stderr.trim() || stdout.trim() || `exit code ${code}`;
+				reject(new HerdrCommandError(`Herdr command failed: ${detail}`, args, code, stderr));
+				return;
+			}
+			resolve(stdout);
+		});
+
+		if (signal?.aborted) abort();
+		else signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+
+function parseResponse(output: string, operation: string): HerdrResponse {
+	try {
+		return JSON.parse(output) as HerdrResponse;
+	} catch {
+		throw new Error(`${operation} returned invalid JSON`);
+	}
+}
+
+export class CliHerdrAutomation implements HerdrAutomation {
+	private readonly binary: string;
+
+	constructor(binary = process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr") {
+		this.binary = binary;
+	}
+
+	async createTab(request: CreateTabRequest): Promise<{ tabId: string; paneId: string }> {
+		const args = ["tab", "create", "--workspace", request.workspaceId, "--cwd", request.cwd, "--label", request.label];
+		for (const [key, value] of Object.entries(request.env).sort(([left], [right]) => left.localeCompare(right))) {
+			args.push("--env", `${key}=${value}`);
+		}
+		args.push(request.focus ? "--focus" : "--no-focus");
+		const response = parseResponse(await runCommand(this.binary, args, request.signal), "herdr tab create");
+		const tabId = response.result?.tab?.tab_id;
+		const paneId = response.result?.root_pane?.pane_id;
+		if (!tabId || !paneId) throw new Error("herdr tab create omitted the tab or root pane id");
+		return { tabId, paneId };
+	}
+
+	async startAgent(request: StartAgentRequest): Promise<void> {
+		await runCommand(this.binary, ["agent", "start", request.name, "--kind", request.kind, "--pane", request.paneId, "--", ...request.args], request.signal);
+	}
+
+	async promptAgent(request: PromptAgentRequest): Promise<{ status?: string }> {
+		const response = parseResponse(
+			await runCommand(this.binary, ["agent", "prompt", request.target, request.prompt, "--wait"], request.signal),
+			"herdr agent prompt",
+		);
+		return { status: response.result?.agent?.status };
+	}
+
+	async splitPane(request: SplitPaneRequest): Promise<{ paneId: string }> {
+		const args = ["pane", "split", request.paneId, "--direction", request.direction, "--cwd", request.cwd, request.focus ? "--focus" : "--no-focus"];
+		for (const [key, value] of Object.entries(request.env ?? {}).sort(([left], [right]) => left.localeCompare(right))) args.push("--env", `${key}=${value}`);
+		const response = parseResponse(await runCommand(this.binary, args, request.signal), "herdr pane split");
+		const paneId = response.result?.pane?.pane_id;
+		if (!paneId) throw new Error("herdr pane split omitted the pane id");
+		return { paneId };
+	}
+
+	async renamePane(paneId: string, label: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["pane", "rename", paneId, label], signal);
+	}
+
+	async renameTab(tabId: string, label: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["tab", "rename", tabId, label], signal);
+	}
+
+	async focusPane(paneId: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["agent", "focus", paneId], signal);
+	}
+
+	async isTabFocused(tabId: string, signal?: AbortSignal): Promise<boolean> {
+		const response = parseResponse(await runCommand(this.binary, ["tab", "get", tabId], signal), "herdr tab get");
+		return response.result?.tab?.focused === true;
+	}
+
+	async waitForTabUnfocused(tabId: string, signal?: AbortSignal): Promise<void> {
+		while (await this.isTabFocused(tabId, signal)) {
+			await new Promise<void>((resolve, reject) => {
+				const onAbort = () => { clearTimeout(timer); reject(signal?.reason); };
+				const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, 500);
+				if (signal?.aborted) onAbort();
+				else signal?.addEventListener("abort", onAbort, { once: true });
+			});
+		}
+	}
+
+	async paneExists(paneId: string, signal?: AbortSignal): Promise<boolean> {
+		try { await runCommand(this.binary, ["pane", "get", paneId], signal); return true; }
+		catch (error) {
+			if (error instanceof HerdrCommandError && /pane[_ -]?not[_ -]?found|unknown pane/i.test(`${error.message}\n${error.stderr}`)) return false;
+			throw error;
+		}
+	}
+
+	async isTaskRunning(paneId: string, signal?: AbortSignal): Promise<boolean> {
+		try {
+			const response = parseResponse(await runCommand(this.binary, ["pane", "process-info", "--pane", paneId], signal), "herdr pane process-info");
+			return (response.result?.process_info?.foreground_processes ?? []).some((process) => {
+				if (process.name === "pi") return true;
+				return (process.argv ?? []).some((argument) => {
+					const normalized = argument.replaceAll("\\", "/");
+					const file = normalized.split("/").at(-1);
+					return file === "pi" || (/pi-coding-agent/.test(normalized) && /(?:^|\/)cli\.js$/.test(normalized)) || /pi-coding-agent\/dist\/bundle\//.test(normalized);
+				});
+			});
+		} catch (error) {
+			if (error instanceof HerdrCommandError && /pane[_ -]?not[_ -]?found|unknown pane/i.test(`${error.message}\n${error.stderr}`)) return false;
+			throw error;
+		}
+	}
+
+	async closeTab(tabId: string, signal?: AbortSignal): Promise<void> {
+		await runCommand(this.binary, ["tab", "close", tabId], signal);
+	}
+}