@maxiaochao/pi-toolkit 0.9.6 → 0.10.1

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

@@ -0,0 +1,175 @@
+import { existsSync, readdirSync } from "node:fs";
+import { mkdir, rename } from "node:fs/promises";
+import { join } from "node:path";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
+import { continueQueuedRun } from "./continue-run.ts";
+import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { writeJsonAtomic, writeTextAtomic } from "./state.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+import type { OwnerIdentity } from "./ownership.ts";
+import { ownerRecord } from "./ownership.ts";
+import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
+import { applyReport, applyTaskStatus, isActiveStatus, persistFailureReport, readReport, readRunRecord, readTaskRecord, readTurnRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type TaskRecord, type TaskStatus, type TurnRecord } from "./records.ts";
+import { isAbortError } from "./errors.ts";
+import { continuationSystemPrompt } from "./protocol.ts";
+import { RunPaneAllocator } from "./run-pane-allocator.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface RespondToBlockedTaskOptions { herdr?: HerdrAutomation; taskNumber?: number; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; onWarning?: (message: string) => void; onStalled?: (message: string) => void; onUpdate?: (result: ResumeBlockedResult) => void; }
+export interface ResumeBlockedResult {
+	ok: boolean;
+	runId: string;
+	label: string;
+	status: "blocked" | "completed" | "partial" | "failed" | "cancelled";
+	summary: string;
+	question?: string;
+	documents: PersistedDocument[];
+	recordDirectory: string;
+	requestedConcurrency: number;
+	effectiveConcurrency: number;
+	tasks?: Array<{ index: number; name: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; error?: string; question?: string; paneId: string; recordDirectory: string; sessionFile: string }>;
+	activity?: Array<{ index: number; name: string; status: TaskStatus; paneId?: string }>;
+	tabId?: string;
+}
+
+async function emitProgress(options: RespondToBlockedTaskOptions, runDirectory: string, run: RunRecord, taskDirectories: string[], summary: string): Promise<void> {
+	if (!options.onUpdate) return;
+	const tasks = await Promise.all(taskDirectories.map((directory) => readTaskRecord(join(directory, "task.json"))));
+	options.onUpdate({
+		ok: false,
+		runId: run.id,
+		label: run.label,
+		status: "blocked",
+		summary,
+		documents: [],
+		recordDirectory: runDirectory,
+		requestedConcurrency: Number(run.requestedConcurrency ?? 1),
+		effectiveConcurrency: Number(run.effectiveConcurrency ?? 1),
+		activity: tasks.map((entry, index) => ({ index, name: String(entry.name ?? entry.agent ?? `Task ${index + 1}`), status: entry.status, ...(entry.paneId ? { paneId: entry.paneId } : {}) })),
+		...(run.tabId ? { tabId: run.tabId } : {}),
+	});
+}
+
+async function projectSettledRun(runDirectory: string, runFile: string, run: RunRecord, taskDirectories: string[], herdr: HerdrAutomation, onCleanupError?: (message: string) => void): Promise<ResumeBlockedResult> {
+	const finalTasks = await Promise.all(taskDirectories.map((directory) => readTaskRecord(join(directory, "task.json"))));
+	const finalReports = await Promise.all(taskDirectories.map(async (directory, index) => {
+		const reportFile = join(directory, "report.json");
+		if (!existsSync(reportFile) && (finalTasks[index].status === "queued" || finalTasks[index].status === "cancelled")) return { status: "failed" as const, summary: finalTasks[index].error ?? (finalTasks[index].status === "queued" ? "Task is still queued." : "Task was cancelled."), documents: [] };
+		try { return await readReport(reportFile); }
+		catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			const failedReport = { status: "failed" as const, summary: `Could not read task report: ${detail}`, documents: [], error: detail };
+			applyReport(finalTasks[index], failedReport);
+			await Promise.all([writeJsonAtomic(join(directory, "task.json"), finalTasks[index]), persistFailureReport(reportFile, failedReport)]);
+			return failedReport;
+		}
+	}));
+	const aggregateStatus = aggregateTaskStatus(finalTasks.map((entry) => entry.status));
+	const runStatus = aggregateStatus === "running" ? "blocked" : aggregateStatus;
+	const blockedIndex = finalTasks.findIndex((entry) => entry.status === "blocked");
+	const blockedReport = blockedIndex >= 0 ? finalReports[blockedIndex] : undefined;
+	run = await readRunRecord(runFile);
+	applyRunStatus(run, runStatus, { question: blockedReport?.question });
+	await writeJsonAtomic(runFile, run);
+	if (runStatus !== "blocked" && run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, onError: onCleanupError, failureStatus: "failed" });
+	const summary = runStatus === "completed" ? "All tasks completed after the answer." : runStatus === "blocked" ? `${finalTasks[blockedIndex]?.name ?? "Task"} needs input: ${blockedReport?.question ?? "Input required."}` : finalReports.map((entry, index) => `${finalTasks[index].name}: ${entry.summary}`).join("\n");
+	const activity = finalTasks.map((entry, index) => ({ index, name: String(entry.name ?? entry.agent ?? `Task ${index + 1}`), status: entry.status, ...(entry.paneId ? { paneId: String(entry.paneId) } : {}) }));
+	const tasks = finalTasks.map((entry, index) => ({ index, name: activity[index].name, status: entry.status, summary: String(finalReports[index].summary ?? "Task has no report."), documents: finalReports[index].documents ?? [], ...(entry.error ? { error: String(entry.error) } : {}), ...(entry.question ? { question: String(entry.question) } : {}), paneId: String(entry.paneId ?? ""), recordDirectory: taskDirectories[index], sessionFile: String(entry.sessionFile ?? "") }));
+	return { ok: runStatus === "completed", runId: run.id, label: String(run.label ?? "batch"), status: runStatus, summary, ...(blockedReport?.question ? { question: blockedReport.question } : {}), documents: finalReports.flatMap((entry) => entry.documents ?? []), recordDirectory: runDirectory, requestedConcurrency: Number(run.requestedConcurrency ?? run.effectiveConcurrency ?? 1), effectiveConcurrency: Number(run.effectiveConcurrency ?? 1), tasks, activity, ...(run.tabId ? { tabId: String(run.tabId) } : {}) };
+}
+
+export async function respondToBlockedTask(cwd: string, runId: string, answer: string, options: RespondToBlockedTaskOptions = {}): Promise<ResumeBlockedResult> {
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const { taskNumber, signal, onCleanupError } = options;
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	const runDirectory = await findRunDirectory(runsDirectory, runId);
+	if (!runDirectory) throw new Error(`Unknown Subagent run '${runId}'.`);
+	const runFile = join(runDirectory, "run.json");
+	const run = await readRunRecord(runFile);
+	const taskDirectories = readdirSync(join(runDirectory, "tasks")).sort().map((entry) => join(runDirectory, "tasks", entry));
+	let taskDirectory: string | undefined;
+	let task: TaskRecord | undefined;
+	for (const directory of taskDirectories) {
+		const candidate = await readTaskRecord(join(directory, "task.json"));
+		if (candidate.status === "blocked" && (!taskNumber || candidate.order === taskNumber)) { taskDirectory = directory; task = candidate; break; }
+	}
+	if (!taskDirectory || !task) throw new Error(`Run '${runId}' has no blocked task.`);
+	Object.assign(run, ownerRecord(options.owner));
+	const previousReport = await readReport(join(taskDirectory, "report.json"));
+	const turnsDirectory = join(taskDirectory, "turns");
+	await mkdir(turnsDirectory, { recursive: true, mode: 0o700 });
+	const resumePrompt = join(taskDirectory, "resume-system-prompt.md");
+	await writeTextAtomic(resumePrompt, `${continuationSystemPrompt(task.systemPrompt, "Continue from the supplied answer.", "resumed")}\n`);
+	let paneId = String(task.paneId ?? "");
+	let agentName = String(task.agentName ?? liveAgentName(task.id));
+	let live = Boolean(paneId) && await herdr.paneExists(paneId, signal) && await herdr.isTaskRunning(paneId, signal);
+	if (!live) {
+		const paneAllocator = new RunPaneAllocator({ herdr, run, runFile, signal, validateExistingPane: true, onCleanupError });
+		paneId = await paneAllocator.allocate(taskDirectory);
+		agentName = liveAgentName(task.id, Number(task.attempt ?? 1) + 1);
+		task.attempt = Number(task.attempt ?? 1) + 1;
+		await herdr.renamePane(paneId, `${String(task.order).padStart(2, "0")} · ${task.name ?? task.agent}`, signal);
+	}
+	const attempt = Number(task.attempt ?? 1);
+	const turnFile = live && task.currentTurnFile ? String(task.currentTurnFile) : join(turnsDirectory, `${String(attempt).padStart(2, "0")}.json`);
+	let turn: TurnRecord = { attempt, prompt: task.prompt, status: "blocked", summary: previousReport.summary, question: previousReport.question, documents: previousReport.documents ?? [], sessionFile: task.sessionFile, startedAt: task.startedAt };
+	if (existsSync(turnFile)) {
+		try { turn = await readTurnRecord(turnFile); }
+		catch (error) {
+			const archivedPath = `${turnFile}.invalid-${Date.now()}`;
+			await rename(turnFile, archivedPath);
+			options.onWarning?.(`Archived invalid durable turn ${turnFile} at ${archivedPath}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	turn.events = [...(Array.isArray(turn.events) ? turn.events : []), { type: "answer", text: answer, at: new Date().toISOString() }];
+	task.currentTurnFile = turnFile;
+	applyTaskStatus(task, "running");
+	Object.assign(task, { tabId: run.tabId, paneId, agentName });
+	await Promise.all([writeJsonAtomic(join(taskDirectory, "task.json"), task), writeJsonAtomic(runFile, run), writeJsonAtomic(turnFile, turn)]);
+	await emitProgress(options, runDirectory, run, taskDirectories, `${task.name ?? task.agent} is continuing after input.`);
+	let report: PersistedReport;
+	let status: "blocked" | "completed" | "failed" | "cancelled";
+	let attemptError: unknown;
+	try {
+		report = (await promptLiveAgent({ herdr, task: { ...task, id: task.id, sessionFile: task.sessionFile }, paneId, prompt: answer, systemPromptFile: resumePrompt, agentName, start: !live, signal, stalledWarningMs: run.stalledWarningSeconds ? Number(run.stalledWarningSeconds) * 1000 : undefined, onStalled: () => options.onStalled?.(`${task.name ?? task.agent} appears stalled; it is still running.`) })).report;
+		status = applyReport(task, report);
+	} catch (error) {
+		attemptError = error;
+		const settled = await settleAttemptFailure(task, join(taskDirectory, "report.json"), {
+			cancelled: isAbortError(error, signal),
+			error: error instanceof Error ? error.message : String(error),
+			name: `${task.name ?? task.agent} response`,
+			replaceReport: true,
+		});
+		report = settled.report;
+		status = settled.status;
+	}
+	if (attemptError && isAbortError(attemptError, signal)) {
+		const message = attemptError instanceof Error ? attemptError.message : String(attemptError);
+			applyTaskStatus(task, "cancelled", { error: message });
+			applyRunStatus(run, "cancelled", { error: message });
+			applyTaskStatus(turn, "cancelled", { error: message });
+			for (const siblingDirectory of taskDirectories) {
+				if (siblingDirectory === taskDirectory) continue;
+				const siblingFile = join(siblingDirectory, "task.json");
+				const sibling = await readTaskRecord(siblingFile);
+				if (!isActiveStatus(sibling.status)) continue;
+				applyTaskStatus(sibling, "cancelled", { error: "Parent Pi session closed." });
+				await writeJsonAtomic(siblingFile, sibling);
+			}
+			await Promise.all([writeJsonAtomic(join(taskDirectory, "task.json"), task), writeJsonAtomic(runFile, run), writeJsonAtomic(turnFile, turn)]);
+			if (run.tabId) await cleanupRunTab({ herdr, tabId: run.tabId, runFile, runRecord: run, signal, onError: onCleanupError, failureStatus: "failed" });
+			return { ok: false, runId, label: String(run.label ?? "batch"), status: "cancelled", summary: "Subagent response cancelled.", documents: [], recordDirectory: runDirectory, requestedConcurrency: Number(run.requestedConcurrency ?? 1), effectiveConcurrency: Number(run.effectiveConcurrency ?? 1), ...(run.tabId ? { tabId: String(run.tabId) } : {}) };
+	}
+	turn.events.push({ type: "report", status, summary: report.summary, question: report.question, error: report.error, at: new Date().toISOString() });
+	Object.assign(turn, { summary: report.summary, documents: report.documents ?? [] });
+	applyReport(turn, report);
+	await Promise.all([writeJsonAtomic(join(taskDirectory, "task.json"), task), writeJsonAtomic(turnFile, turn)]);
+	await emitProgress(options, runDirectory, run, taskDirectories, `${task.name ?? task.agent} ${status}.`);
+	if (status !== "blocked") {
+		applyRunStatus(run, "queued");
+		await writeJsonAtomic(runFile, run);
+		await continueQueuedRun(runDirectory, herdr, { cleanup: false, signal, onStalled: options.onStalled, onCleanupError, onUpdate: () => emitProgress(options, runDirectory, run, taskDirectories, "Queued tasks are continuing.") });
+	}
+	return projectSettledRun(runDirectory, runFile, run, taskDirectories, herdr, onCleanupError);
+}

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

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { discoverPackageAgents, type AgentDefinition } from "./personas.ts";
+
+export type PersonaAccess = "read" | "write";
+export interface PersonaConfig { model?: string; thinking?: string; skills?: string[]; }
+export interface SubagentConfig {
+	defaultConcurrency: number;
+	maxConcurrency: number;
+	stalledWarningSeconds: number;
+	defaultModel?: string;
+	defaultThinking?: string;
+	personas: Record<string, PersonaConfig>;
+}
+export interface EffectivePersona extends AgentDefinition {
+	source: "project" | "global" | "package";
+	access: PersonaAccess;
+	model?: string;
+	modelSource: string;
+	thinking?: string;
+	thinkingSource: string;
+	skills: string[];
+	skillsSource: string;
+}
+export interface SubagentConfiguration {
+	settings: SubagentConfig;
+	settingSources: Record<string, string>;
+	personas: EffectivePersona[];
+	diagnostics: string[];
+}
+interface ConfigFile {
+	defaultConcurrency?: number;
+	maxConcurrency?: number;
+	stalledWarningSeconds?: number;
+	defaultModel?: string;
+	defaultThinking?: string;
+	personas?: Record<string, PersonaConfig>;
+}
+export interface ConfigurationPaths {
+	globalConfig?: string;
+	projectConfig?: string;
+	globalAgents?: string;
+	projectAgents?: string;
+}
+const DEFAULTS: SubagentConfig = { defaultConcurrency: 1, maxConcurrency: 4, stalledWarningSeconds: 300, personas: {} };
+
+function readConfig(path: string, source: string, diagnostics: string[]): ConfigFile {
+	if (!existsSync(path)) return {};
+	try {
+		const value = JSON.parse(readFileSync(path, "utf8")) as unknown;
+		if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("expected a JSON object");
+		return value as ConfigFile;
+	} catch (error) {
+		diagnostics.push(`${source} configuration ${path}: ${error instanceof Error ? error.message : String(error)}`);
+		return {};
+	}
+}
+
+function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, sources: Record<string, string>, diagnostics: string[]): SubagentConfig {
+	const result: SubagentConfig = { ...base, personas: { ...base.personas } };
+	for (const key of ["defaultConcurrency", "maxConcurrency", "stalledWarningSeconds"] as const) {
+		const value = input[key];
+		if (value === undefined) continue;
+		if (!Number.isInteger(value) || Number(value) <= 0) { diagnostics.push(`${source} ${key} must be a positive integer`); continue; }
+		result[key] = value as number;
+		sources[key] = source;
+	}
+	for (const key of ["defaultModel", "defaultThinking"] as const) {
+		const value = input[key];
+		if (value === undefined) continue;
+		if (typeof value === "string" && value.trim()) { result[key] = value.trim(); sources[key] = source; }
+		else diagnostics.push(`${source} ${key} must be a non-empty string`);
+	}
+	if (input.personas !== undefined) {
+		if (!input.personas || typeof input.personas !== "object" || Array.isArray(input.personas)) diagnostics.push(`${source} personas must be an object`);
+		else for (const [name, raw] of Object.entries(input.personas)) {
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) { diagnostics.push(`${source} persona '${name}' must be an object`); continue; }
+			const valid: PersonaConfig = {};
+			for (const field of ["model", "thinking"] as const) {
+				const value = raw[field];
+				if (value === undefined) continue;
+				if (typeof value === "string" && value.trim()) valid[field] = value.trim();
+				else diagnostics.push(`${source} persona '${name}' ${field} must be a non-empty string`);
+			}
+			if (raw.skills !== undefined) {
+				if (Array.isArray(raw.skills) && raw.skills.every((value) => typeof value === "string" && value.trim())) valid.skills = raw.skills.map((value) => value.trim());
+				else diagnostics.push(`${source} persona '${name}' skills must be an array of non-empty strings`);
+			}
+			input.personas[name] = valid;
+			result.personas[name] = { ...(result.personas[name] ?? {}), ...valid };
+			for (const field of Object.keys(valid)) sources[`personas.${name}.${field}`] = source;
+		}
+	}
+	return result;
+}
+
+export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: string, parentModel?: string, paths: ConfigurationPaths = {}): SubagentConfiguration {
+	const diagnostics: string[] = [];
+	const globalConfigPath = paths.globalConfig ?? join(homedir(), ".pi", "agent", "herdr-subagents.json");
+	const projectConfigPath = paths.projectConfig ?? join(cwd, ".pi", "herdr-subagents.json");
+	const globalAgentsDirectory = paths.globalAgents ?? join(dirname(globalConfigPath), "herdr-subagents", "agents");
+	const projectAgentsDirectory = paths.projectAgents ?? join(cwd, ".pi", "herdr-subagents", "agents");
+	const settingSources: Record<string, string> = { defaultConcurrency: "built-in", maxConcurrency: "built-in", stalledWarningSeconds: "built-in" };
+	const globalInput = readConfig(globalConfigPath, "global", diagnostics);
+	const projectInput = readConfig(projectConfigPath, "project", diagnostics);
+	const globalSettings = mergeConfig(DEFAULTS, globalInput, "global", settingSources, diagnostics);
+	const settings = mergeConfig(globalSettings, projectInput, "project", settingSources, diagnostics);
+	if (settings.defaultConcurrency > settings.maxConcurrency) { diagnostics.push("defaultConcurrency exceeds maxConcurrency; maxConcurrency is used"); settings.defaultConcurrency = settings.maxConcurrency; }
+	const layers = [
+		{ source: "package" as const, discovery: discoverPackageAgents(packageAgentsDirectory) },
+		{ source: "global" as const, discovery: discoverPackageAgents(globalAgentsDirectory, true) },
+		{ source: "project" as const, discovery: discoverPackageAgents(projectAgentsDirectory, true) },
+	];
+	const definitions = new Map<string, { definition: AgentDefinition; source: "project" | "global" | "package" }>();
+	for (const layer of layers) { diagnostics.push(...layer.discovery.diagnostics); for (const definition of layer.discovery.agents) definitions.set(definition.name, { definition, source: layer.source }); }
+	const personas = [...definitions.values()].map(({ definition, source }): EffectivePersona => {
+		const globalPersona = globalInput.personas?.[definition.name] ?? {};
+		const projectPersona = projectInput.personas?.[definition.name] ?? {};
+		const model = projectPersona.model ?? globalPersona.model ?? definition.model ?? settings.defaultModel ?? parentModel;
+		const modelSource = projectPersona.model ? "project persona" : globalPersona.model ? "global persona" : definition.model ? `${source} persona` : settings.defaultModel ? settingSources.defaultModel : parentModel ? "parent session" : "unresolved";
+		const thinking = projectPersona.thinking ?? globalPersona.thinking ?? definition.thinking ?? settings.defaultThinking;
+		const thinkingSource = projectPersona.thinking ? "project persona" : globalPersona.thinking ? "global persona" : definition.thinking ? `${source} persona` : settings.defaultThinking ? settingSources.defaultThinking : "default";
+		const skills = projectPersona.skills ?? globalPersona.skills ?? definition.skills ?? [];
+		const skillsSource = projectPersona.skills ? "project persona" : globalPersona.skills ? "global persona" : definition.skills ? `${source} persona` : "none";
+		return { ...definition, source, access: definition.access ?? "write", model, modelSource, thinking, thinkingSource, skills, skillsSource };
+	}).sort((left, right) => left.name.localeCompare(right.name));
+	return { settings, settingSources, personas, diagnostics };
+}

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}`),
+	];
+}