@maxiaochao/pi-toolkit 0.9.6 → 0.10.1

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

@@ -0,0 +1,258 @@
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Container, Editor, Spacer, Text } from "@earendil-works/pi-tui";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { CliHerdrAutomation, type HerdrAutomation } from "../src/herdr.ts";
+import { activeRunText } from "../src/monitor.ts";
+import { RunDispatcher } from "../src/dispatcher.ts";
+import { historyText, listSubagentHistory } from "../src/history.ts";
+import { cancelQueuedRuns, loadQueuedRuns, persistQueuedRun, removeQueuedRun } from "../src/queued-runs.ts";
+import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcile.ts";
+import { executeHerdrSubagents, type HerdrSubagentsBatchDetails, type HerdrSubagentsDetails, type HerdrSubagentsToolParams } from "../src/tool.ts";
+import { HerdrSubagentsParams } from "../src/parameters.ts";
+import { HERDR_ACTIONS } from "../src/validation.ts";
+import { FleetController } from "../src/fleet-controller.ts";
+import { isSettledRunStatus } from "../src/records.ts";
+
+const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
+
+function statusVisual(status: string): { color: "success" | "warning" | "error" | "accent"; glyph: string } {
+	if (status === "completed") return { color: "success", glyph: "✓" };
+	if (status === "blocked") return { color: "warning", glyph: "?" };
+	if (status === "cancelled" || status === "partial") return { color: "warning", glyph: "−" };
+	if (status === "starting" || status === "queued" || status === "running") return { color: "accent", glyph: "·" };
+	return { color: "error", glyph: "✗" };
+}
+
+function renderToolCall(args: HerdrSubagentsToolParams, theme: Theme): Text {
+	if (args.action) {
+		const action = HERDR_ACTIONS[args.action];
+		const runId = action.includeRunId ? ` ${theme.fg("muted", String(args.runId ?? ""))}` : "";
+		return new Text(`${theme.fg("toolTitle", theme.bold(`herdr_subagents ${args.action}`))}${runId}`, 0, 0);
+	}
+	if (args.tasks) return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", `${args.tasks.length} tasks`)}${theme.fg("muted", ` · concurrency ${args.concurrency ?? "default"}`)}`, 0, 0);
+	const agent = args.agent || "worker";
+	const label = args.label ? ` · ${String(args.label)}` : "";
+	const prompt = args.prompt ? String(args.prompt).replace(/\s+/g, " ") : "...";
+	const preview = prompt.length > 80 ? `${prompt.slice(0, 80)}...` : prompt;
+	return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", agent)}${theme.fg("muted", label)}\n  ${theme.fg("dim", preview)}`, 0, 0);
+}
+
+function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRenderResultOptions, theme: Theme): Container | Text {
+	const batch = result.details as HerdrSubagentsBatchDetails | undefined;
+	if (batch?.tasks && "effectiveConcurrency" in batch) {
+		const container = new Container();
+		const visual = statusVisual(batch.status);
+		container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(batch.label))} ${theme.fg(visual.color, batch.status)} · ${batch.tasks.length} settled · concurrency ${batch.effectiveConcurrency}`, 0, 0));
+		for (const task of batch.tasks) container.addChild(new Text(`${statusVisual(task.status).glyph} ${task.name}: ${task.summary}`, 0, 0));
+		return container;
+	}
+	const details = result.details as HerdrSubagentsDetails | undefined;
+	if (!details?.agent) {
+		const content = result.content[0];
+		return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
+	}
+	const container = new Container();
+	container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(statusVisual(details.status).color, details.status)}`, 0, 0));
+	container.addChild(new Text(details.summary, 0, 0));
+	if (details.documents.length > 0) {
+		container.addChild(new Spacer(1));
+		for (const document of details.documents) container.addChild(new Text(theme.fg("muted", `${document.description}: ${document.path}`), 0, 0));
+	}
+	if (details.recordDirectory) container.addChild(new Text(theme.fg("dim", `Record: ${details.recordDirectory}`), 0, 0));
+	if (details.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
+	return container;
+}
+
+async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fleet: FleetController): Promise<void> {
+	const section = args.trim() || "active";
+	if (section === "active") {
+		ctx.ui.notify(fleet.active ? activeRunText(fleet.active) : "No active Subagent run.", "info");
+		return;
+	}
+	if (section === "history") {
+		ctx.ui.notify(historyText(await listSubagentHistory(ctx.cwd)), "info");
+		return;
+	}
+	if (section.startsWith("focus ")) {
+		if (!await fleet.focus(Number(section.slice(6).trim()))) ctx.ui.notify("That task is not active in a Herdr pane.", "warning");
+		return;
+	}
+	if (section === "models") {
+		await ctx.modelRegistry.refresh();
+		const lines = ctx.modelRegistry.getAvailable().map((model) => `${model.provider}/${model.id}`).sort();
+		ctx.ui.notify(lines.length ? `Available Pi models:\n${lines.join("\n")}` : "No authenticated Pi models are available.", "info");
+		return;
+	}
+	const configuration = loadSubagentConfiguration(ctx.cwd, packageAgentsDir, ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
+	if (section === "agents") {
+		ctx.ui.notify(configuration.personas.map((persona) => `${persona.name}: ${persona.source}, ${persona.access}, model=${persona.model ?? "unresolved"} (${persona.modelSource}), thinking=${persona.thinking ?? "default"}, tools=${persona.tools?.join(",") ?? "default"}, skills=${persona.skills.join(",") || "none"}`).join("\n"), "info");
+		return;
+	}
+	if (section === "settings") {
+		const settings = configuration.settings;
+		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, defaultModel: settings.defaultModel, defaultThinking: settings.defaultThinking };
+		const lines = Object.entries(values).map(([key, value]) => `${key}=${String(value ?? "unset")} (${configuration.settingSources[key] ?? "built-in"})`);
+		if (configuration.diagnostics.length) lines.push("Diagnostics:", ...configuration.diagnostics);
+		ctx.ui.notify(lines.join("\n"), "info");
+		return;
+	}
+	ctx.ui.notify("Usage: /herdr-subagents active|history|focus <task-number>|agents|models|settings", "warning");
+}
+
+export interface HerdrSubagentsExtensionDependencies {
+	herdr?: HerdrAutomation;
+	execute?: typeof executeHerdrSubagents;
+	isEditor?: (value: unknown) => boolean;
+	createFleetWidget?: (lines: string[]) => Container;
+}
+
+async function recoverParentSession(cwd: string, herdr: HerdrAutomation, owner: { sessionId?: string; processId: number }, notify: (message: string) => void): Promise<void> {
+	try {
+		const queued = await loadQueuedRuns(cwd, notify);
+		await cancelQueuedRuns(cwd, queued.map((run) => run.runId), { reason: "Owning parent Pi session is no longer active.", owner, onlyOrphaned: true, onError: notify });
+	}
+	catch (error) { notify(`Subagent queue recovery failed: ${error instanceof Error ? error.message : String(error)}`); }
+	try {
+		const reconciliation = await reconcileSubagentRuns(cwd, herdr, owner);
+		for (const message of reconciliation.cleanupErrors) notify(message);
+	}
+	catch (error) { notify(`Subagent recovery could not inspect active runs: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+async function shutdownParentSession(options: { cwd: string; herdr: HerdrAutomation; owner: { sessionId?: string; processId: number }; dispatcher: RunDispatcher; fleet: FleetController; sessionController: AbortController; runControllers: Map<string, AbortController>; inFlight: Set<Promise<unknown>>; notify: (message: string) => void }): Promise<void> {
+	options.dispatcher.pause();
+	options.sessionController.abort(new Error("Parent Pi session closed."));
+	const queuedRunIds = options.dispatcher.cancelQueued(new Error("Parent Pi session closed."));
+	await cancelQueuedRuns(options.cwd, queuedRunIds, { reason: "Parent Pi session closed.", owner: options.owner });
+	for (const controller of options.runControllers.values()) controller.abort(new Error("Parent Pi session closed."));
+	options.fleet.shutdown();
+	await Promise.allSettled([...options.inFlight]);
+	const cancellation = await cancelActiveSubagentRuns(options.cwd, options.herdr, { reason: "Parent Pi session closed.", owner: options.owner });
+	const retainedRunId = options.dispatcher.snapshot().activeRunId;
+	if (retainedRunId) options.dispatcher.release(retainedRunId);
+	for (const message of cancellation.cleanupErrors) options.notify(message);
+}
+
+export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSubagentsExtensionDependencies = {}) {
+	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1" || process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) return;
+	const herdr = dependencies.herdr ?? new CliHerdrAutomation();
+	const execute = dependencies.execute ?? executeHerdrSubagents;
+	const isEditorComponent = dependencies.isEditor ?? ((value: unknown) => value instanceof Editor);
+	const dispatcher = new RunDispatcher();
+	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget);
+	const runControllers = new Map<string, AbortController>();
+	const inFlight = new Set<Promise<unknown>>();
+	let sessionController = new AbortController();
+	let ownerSessionId: string | undefined;
+	let sessionGeneration = 0;
+	const notifyRun = (runId: string, result: { details: unknown; content?: Array<{ type: string; text?: string }> }) => {
+		const details = result.details as Partial<HerdrSubagentsBatchDetails> & { errorMessage?: string };
+		if (!details.tasks || !details.documents || !details.status) {
+			const error = details.errorMessage ?? result.content?.find((item) => item.type === "text")?.text ?? "Unknown Subagent failure.";
+			pi.sendMessage({ customType: "herdr-subagents-run", content: `Subagent run ${runId} failed: ${error}`, display: true, details: { runId, status: "failed" } }, { triggerTurn: true, deliverAs: "followUp" });
+			return;
+		}
+		const lines = [`Subagent run ${runId} ${details.status}: ${details.summary}`, ...details.tasks.map((task) => `- ${task.name}: ${task.summary}`)];
+		if (details.documents.length) lines.push("Documents:", ...details.documents.map((document) => `- ${document.description}: ${document.path}`));
+		pi.sendMessage({ customType: "herdr-subagents-run", content: lines.join("\n"), display: true, details: { runId, status: details.status } }, { triggerTurn: true, deliverAs: "followUp" });
+	};
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		sessionGeneration += 1;
+		await shutdownParentSession({ cwd: ctx.cwd, herdr, owner: { sessionId: ownerSessionId, processId: process.pid }, dispatcher, fleet, sessionController, runControllers, inFlight, notify: (message) => ctx.ui.notify(message, "error") });
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		sessionGeneration += 1;
+		sessionController.abort(new Error("Parent Pi session changed."));
+		sessionController = new AbortController();
+		ownerSessionId = `${ctx.sessionManager.getSessionId()}:${randomUUID()}`;
+		fleet.bind(ctx.ui, ctx.mode === "tui");
+		dispatcher.pause();
+		try { await recoverParentSession(ctx.cwd, herdr, { sessionId: ownerSessionId, processId: process.pid }, (message) => ctx.ui.notify(message, "error")); }
+		finally { dispatcher.resume(); }
+	});
+
+	pi.registerTool({
+		name: "herdr_subagents",
+		label: "Herdr Subagents",
+		description: "Run one focused task or an ordered bounded-concurrency batch in visible interactive Herdr Pi Agents. Foreground calls block while workers run concurrently; background batches return a run ID immediately and publish completion later. Complete results and Pi sessions stay in project-local records.",
+		promptSnippet: "Run focused work in visible Herdr subagents",
+		promptGuidelines: ["Call action=list once before the first execution. Submit one prompt or an ordered tasks list; use concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
+		parameters: HerdrSubagentsParams,
+
+		async execute(_toolCallId, params: HerdrSubagentsToolParams, signal, onUpdate, ctx) {
+			const generation = sessionGeneration;
+			const runId = params.tasks ? randomUUID() : undefined;
+			const executionId = runId ?? params.runId ?? randomUUID();
+			const controller = new AbortController();
+			runControllers.set(executionId, controller);
+			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(!params.background && signal ? [signal] : [])]);
+			const executeRun = async () => {
+				const result = await execute(params, runSignal, (update) => {
+				const details = update.details as HerdrSubagentsBatchDetails | undefined;
+				if (details?.activity) fleet.sync(details);
+				const updateText = update.content.find((item) => item.type === "text")?.text;
+				const updateDetails = update.details as { warning?: string };
+				if (updateDetails.warning || updateText?.includes("cleanup failed") || (params.background && updateText?.includes("appears stalled"))) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
+				if (!params.background) onUpdate?.(update);
+				}, ctx, { agentsDirectory: packageAgentsDir, owner: { sessionId: ownerSessionId, processId: process.pid }, runId });
+				fleet.sync(result.details);
+				return result;
+			};
+			if (!params.tasks) {
+				const promise = executeRun();
+				inFlight.add(promise);
+				const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
+				if (params.action === "respond") {
+					const details = result.details as { runId?: string; status?: string };
+					if (details.status === "blocked") fleet.sync(result.details);
+					else if (isSettledRunStatus(details.status)) {
+						fleet.clearRun(params.runId);
+						if (params.runId) dispatcher.release(params.runId);
+					}
+				}
+				return result;
+			}
+			if (!runId) throw new Error("Batch run ID was not allocated.");
+			if (params.background) await persistQueuedRun(ctx.cwd, runId, params, { sessionId: ownerSessionId, processId: process.pid });
+			const promise = dispatcher.submit(runId, async () => {
+				const result = await executeRun().finally(async () => { if (params.background) await removeQueuedRun(ctx.cwd, runId); });
+					const details = result.details as HerdrSubagentsBatchDetails;
+					fleet.setActive(details.status === "blocked" ? details : undefined);
+					if (fleet.active) {
+						dispatcher.retain(runId);
+				}
+				return result;
+			});
+			inFlight.add(promise);
+			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); }).catch(() => undefined);
+			if (params.background) {
+				void promise.then((result) => {
+					if (generation !== sessionGeneration) return;
+					notifyRun(runId, result);
+					if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.render();
+				}).catch((error) => {
+					if (generation !== sessionGeneration) return;
+					pi.sendMessage({ customType: "herdr-subagents-run", content: `Subagent run ${runId} failed: ${error instanceof Error ? error.message : String(error)}`, display: true, details: { runId, status: "failed" } }, { triggerTurn: true, deliverAs: "followUp" });
+				});
+				return { content: [{ type: "text" as const, text: `Subagent run queued: ${runId}` }], details: { runId, status: "queued", background: true } };
+			}
+			const result = await promise;
+			if (!fleet.active && !dispatcher.snapshot().activeRunId && dispatcher.snapshot().queuedRunIds.length === 0) fleet.resetSelection();
+			return result;
+		},
+
+		renderCall: renderToolCall,
+		renderResult: renderToolResult,
+	});
+
+	pi.registerCommand("herdr-subagents", {
+		description: "Inspect effective subagent agents, models, and settings",
+		getArgumentCompletions: (prefix) => ["active", "history", "agents", "models", "settings", "focus "].filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),
+		handler: (args, ctx) => handleHerdrCommand(args, ctx, fleet),
+	});
+}
+
+export default registerHerdrSubagents;

package/packages/herdr-subagents/extensions/subagent-report.ts

@@ -0,0 +1,65 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { resultPathForAttempt } from "../src/result-path.ts";
+
+const ReportParams = Type.Object({
+	status: StringEnum(["completed", "needs-input", "failed"] as const, { description: "Current outcome for this task." }),
+	summary: Type.String({ minLength: 1, description: "One concise paragraph for the parent agent." }),
+	result: Type.String({ description: "Complete final result. Stored on disk and excluded from the parent context." }),
+	documents: Type.Optional(Type.Array(Type.Object({
+		path: Type.String({ minLength: 1, description: "Path to a document produced or consulted by this task." }),
+		description: Type.String({ minLength: 1, description: "Short description of the document." }),
+	}))),
+	error: Type.Optional(Type.String({ minLength: 1, description: "Failure detail when status is failed." })),
+	question: Type.Optional(Type.String({ minLength: 1, description: "Exact question when status is needs-input." })),
+});
+
+function writeAtomic(path: string, content: string): void {
+	const temporary = `${path}.tmp-${process.pid}`;
+	writeFileSync(temporary, content, { encoding: "utf8", mode: 0o600 });
+	renameSync(temporary, path);
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "subagent_report",
+		label: "Subagent Report",
+		description: "Finish this delegated task by saving its complete result and returning only a compact structured report to the parent.",
+		parameters: ReportParams,
+		async execute(_toolCallId, params) {
+			const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
+			if (!taskDirectory) throw new Error("PI_HERDR_SUBAGENTS_TASK_DIR is not set");
+			mkdirSync(taskDirectory, { recursive: true, mode: 0o700 });
+			let attempt = 1;
+			const task = JSON.parse(readFileSync(resolve(taskDirectory, "task.json"), "utf8")) as { attempt?: unknown };
+			if (Number.isInteger(task.attempt) && Number(task.attempt) > 1) attempt = Number(task.attempt);
+			const resultPath = resultPathForAttempt(taskDirectory, attempt);
+			if (attempt > 1) mkdirSync(resolve(taskDirectory, "turns"), { recursive: true, mode: 0o700 });
+			writeAtomic(resultPath, params.result);
+			const documents = (params.documents ?? []).map((document) => ({
+				path: resolve(process.cwd(), document.path),
+				description: document.description,
+			}));
+			if (!documents.some((document) => document.path === resultPath)) {
+				documents.unshift({ path: resultPath, description: "Complete task result" });
+			}
+			const report = {
+				status: params.status,
+				summary: params.summary,
+				documents,
+				...(params.error ? { error: params.error } : {}),
+				...(params.question ? { question: params.question } : {}),
+				reportedAt: new Date().toISOString(),
+			};
+			writeAtomic(resolve(taskDirectory, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+			return {
+				content: [{ type: "text" as const, text: `${params.status}: ${params.summary}` }],
+				details: report,
+				terminate: true,
+			};
+		},
+	});
+}

package/packages/{tiny-subagent → herdr-subagents}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "@maxiaochao/pi-tiny-subagent",
-  "version": "0.1.1",
-  "description": "A tiny Pi subagent tool with package-local personas and detailed process errors.",
+  "name": "@maxiaochao/pi-herdr-subagents",
+  "version": "0.2.1",
+  "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -12,6 +12,7 @@
     "extensions",
     "src",
     "agents",
+    "tests",
     "docs",
     "README.md",
     "TESTING.md",
@@ -21,11 +22,11 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
-    "directory": "packages/tiny-subagent"
+    "directory": "packages/herdr-subagents"
   },
   "pi": {
     "extensions": [
-      "./extensions/tiny-subagent.ts"
+      "./extensions/herdr-subagents.ts"
     ]
   },
   "peerDependencies": {
@@ -36,7 +37,7 @@
   },
   "scripts": {
     "test": "node --experimental-strip-types tests/run-tests.mjs",
-    "load-test": "pi -ne -ns --no-session -e ./extensions/tiny-subagent.ts"
+    "load-test": "env -u PI_HERDR_SUBAGENTS_CHILD pi -ne -ns --no-session -e ./tests/extension-contract.ts && env -u PI_HERDR_SUBAGENTS_CHILD pi -ne -ns --no-session -e ./extensions/herdr-subagents.ts"
   },
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
+import type { PersonaAccess } from "./config.ts";
+import type { HerdrSubagentsDocument } from "./runner.ts";
+import { ensureRuntimeIgnored } from "./history.ts";
+import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { writeJsonAtomic } from "./state.ts";
+import type { OwnerIdentity } from "./ownership.ts";
+import { ownerRecord } from "./ownership.ts";
+import { RunPaneAllocator } from "./run-pane-allocator.ts";
+import { applyReport, applyTaskStatus, settleAttemptFailure, type PersistedReport, type RunRecord, type TaskRecord, type TaskStatus } from "./records.ts";
+import { reportProtocolPrompt } from "./protocol.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+import { applyRunStatus } from "./run-status.ts";
+import { isAbortError } from "./errors.ts";
+
+export interface BatchTask {
+	name: string;
+	prompt: string;
+	agent: string;
+	access: PersonaAccess;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	skills: string[];
+	systemPrompt: string;
+}
+
+export interface BatchOptions {
+	runId?: string;
+	label: string;
+	concurrency: number;
+	maxConcurrency: number;
+	stalledWarningSeconds?: number;
+	cwd: string;
+	signal?: AbortSignal;
+	herdr?: HerdrAutomation;
+	owner?: OwnerIdentity;
+	onUpdate?: (result: BatchResult) => void;
+	onCleanupError?: (message: string) => void;
+}
+
+type BatchTaskStatus = Exclude<TaskStatus, "starting">;
+export interface BatchTaskResult {
+	index: number;
+	name: string;
+	status: Exclude<BatchTaskStatus, "queued" | "running">;
+	summary: string;
+	documents: HerdrSubagentsDocument[];
+	error?: string;
+	question?: string;
+	paneId: string;
+	recordDirectory: string;
+	sessionFile: string;
+}
+export interface BatchResult {
+	ok: boolean;
+	status: "starting" | "running" | "blocked" | "completed" | "partial" | "failed" | "cancelled";
+	runId: string;
+	label: string;
+	requestedConcurrency: number;
+	effectiveConcurrency: number;
+	tasks: BatchTaskResult[];
+	activity: Array<{ index: number; name: string; status: BatchTaskStatus; paneId?: string }>;
+	summary: string;
+	documents: HerdrSubagentsDocument[];
+	recordDirectory: string;
+	tabId?: string;
+}
+
+type TaskContext = {
+	taskId: string;
+	taskDirectory: string;
+	sessionFile: string;
+	reportFile: string;
+	taskFile: string;
+	systemPromptFile: string;
+	taskRecord: TaskRecord;
+};
+
+function timestamp(): string { return new Date().toISOString(); }
+export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchOptions): Promise<BatchResult> {
+	if (!tasks.length) throw new Error("At least one task is required.");
+	if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) throw new Error("Herdr Subagents must run from a Pi session inside Herdr.");
+	const runId = options.runId ?? randomUUID();
+	const requestedConcurrency = Math.max(1, Math.floor(options.concurrency));
+	const effectiveConcurrency = tasks.some((task) => task.access === "write") ? 1 : Math.min(requestedConcurrency, options.maxConcurrency, tasks.length);
+	const runDirectory = join(options.cwd, ".pi", "herdr-subagents", "runs", `${timestamp().replace(/[-:.]/g, "").replace("Z", "Z-")}${runId.slice(0, 8)}`);
+	const runFile = join(runDirectory, "run.json");
+	await ensureRuntimeIgnored(options.cwd);
+	await mkdir(join(runDirectory, "tasks"), { recursive: true, mode: 0o700 });
+	const contexts: TaskContext[] = await Promise.all(tasks.map(async (task, index) => {
+		const taskId = randomUUID();
+		const taskDirectory = join(runDirectory, "tasks", `${String(index + 1).padStart(2, "0")}-${taskId.slice(0, 8)}`);
+		const sessionFile = join(taskDirectory, "session.jsonl");
+		const systemPromptFile = join(taskDirectory, "system-prompt.md");
+		const taskRecord: TaskRecord = {
+			id: taskId, runId, order: index + 1, name: task.name, status: "queued", prompt: task.prompt,
+			agent: task.agent, access: task.access, model: task.model, thinking: task.thinking,
+			tools: task.tools, skills: task.skills, systemPrompt: reportProtocolPrompt(task.systemPrompt), sessionFile,
+		};
+		await mkdir(taskDirectory, { recursive: true, mode: 0o700 });
+		await writeFile(systemPromptFile, String(taskRecord.systemPrompt), { encoding: "utf8", mode: 0o600 });
+		const taskFile = join(taskDirectory, "task.json");
+		await writeJsonAtomic(taskFile, taskRecord);
+		return { taskId, taskDirectory, sessionFile, reportFile: join(taskDirectory, "report.json"), taskFile, systemPromptFile, taskRecord };
+	}));
+	const runRecord: RunRecord = {
+		id: runId, label: options.label, status: "starting", cwd: options.cwd, ...ownerRecord(options.owner), requestedConcurrency,
+		effectiveConcurrency, stalledWarningSeconds: options.stalledWarningSeconds, startedAt: timestamp(), taskIds: contexts.map((context) => context.taskId), paneIds: [],
+	};
+	await writeJsonAtomic(runFile, runRecord);
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const results = new Array<BatchTaskResult>(tasks.length);
+	const activity: BatchResult["activity"] = tasks.map((task, index) => ({ index, name: task.name, status: "queued" }));
+	let tabId: string | undefined;
+	const paneAllocator = new RunPaneAllocator({ herdr, run: runRecord, runFile, signal: options.signal, onCleanupError: options.onCleanupError });
+	const emit = (status: BatchResult["status"], summary: string) => options.onUpdate?.({
+		ok: false, status, runId, label: options.label, requestedConcurrency, effectiveConcurrency,
+		tasks: results.filter(Boolean), activity: activity.map((entry) => ({ ...entry })), summary,
+		documents: results.filter(Boolean).flatMap((result) => result.documents), recordDirectory: runDirectory, tabId,
+	});
+	const allocatePane = async (index: number): Promise<string> => {
+		const paneId = await paneAllocator.allocate(contexts[index].taskDirectory);
+		tabId = paneAllocator.tabId;
+		return paneId;
+	};
+
+	emit("starting", `Starting up to ${effectiveConcurrency} interactive Pi Agent${effectiveConcurrency === 1 ? "" : "s"}...`);
+	let nextIndex = 0;
+	let settled = 0;
+	try {
+		const runOne = async (index: number): Promise<void> => {
+			const task = tasks[index];
+			const context = contexts[index];
+			let paneId = "";
+			let agentName = liveAgentName(context.taskId);
+			let report: PersistedReport;
+			let status: BatchTaskResult["status"];
+			try {
+				paneId = await allocatePane(index);
+				const paneLabel = `${String(index + 1).padStart(2, "0")} · ${task.name}`;
+				await herdr.renamePane(paneId, paneLabel, options.signal);
+				applyTaskStatus(context.taskRecord, "running");
+				Object.assign(context.taskRecord, { tabId, paneId, paneLabel, agentName, startedAt: timestamp() });
+				await writeJsonAtomic(context.taskFile, context.taskRecord);
+				activity[index] = { index, name: task.name, status: "running", paneId };
+				emit("running", `${settled}/${tasks.length} tasks settled.`);
+				const prompted = await promptLiveAgent({ herdr, task: { ...task, id: context.taskId, sessionFile: context.sessionFile }, paneId, prompt: task.prompt, systemPromptFile: context.systemPromptFile, agentName, signal: options.signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => emit("running", `${task.name} appears stalled; it is still running.`) });
+				agentName = prompted.agentName;
+				report = prompted.report;
+				status = applyReport(context.taskRecord, report);
+			} catch (error) {
+				const settled = await settleAttemptFailure(context.taskRecord, context.reportFile, {
+					cancelled: isAbortError(error, options.signal),
+					error: error instanceof Error ? error.message : String(error),
+					name: task.name,
+				});
+				report = settled.report;
+				status = settled.status;
+			}
+			Object.assign(context.taskRecord, { paneId, agentName });
+			await writeJsonAtomic(context.taskFile, context.taskRecord);
+			results[index] = { index, name: task.name, status, summary: report.summary, documents: report.documents, ...(report.error ? { error: report.error } : {}), ...(report.question ? { question: report.question } : {}), paneId, recordDirectory: context.taskDirectory, sessionFile: context.sessionFile };
+			activity[index] = { index, name: task.name, status, ...(paneId ? { paneId } : {}) };
+			settled += 1;
+			emit("running", `${settled}/${tasks.length} tasks settled.`);
+		};
+		const worker = async () => {
+			while (!options.signal?.aborted) {
+				const index = nextIndex++;
+				if (index >= tasks.length) return;
+				await runOne(index);
+				if (results[index]?.status === "blocked") return;
+			}
+		};
+		await Promise.all(Array.from({ length: effectiveConcurrency }, worker));
+		if (options.signal?.aborted) {
+			for (let index = 0; index < tasks.length; index += 1) {
+				if (activity[index].status !== "queued") continue;
+				activity[index].status = "cancelled";
+				Object.assign(contexts[index].taskRecord, { status: "cancelled", completedAt: timestamp(), error: "Parent Pi session closed." });
+				await writeJsonAtomic(contexts[index].taskFile, contexts[index].taskRecord);
+			}
+		}
+		const settledResults = results.filter(Boolean);
+		const blocked = settledResults.find((result) => result.status === "blocked");
+		const failed = settledResults.filter((result) => result.status === "failed").length;
+		const cancelled = options.signal?.aborted || activity.some((entry) => entry.status === "cancelled");
+		const status: BatchResult["status"] = cancelled ? "cancelled" : blocked || activity.some((entry) => entry.status === "queued") ? "blocked" : failed === 0 ? "completed" : failed === tasks.length ? "failed" : "partial";
+		const summary = status === "cancelled" ? "Subagent batch cancelled because the parent Pi session closed." : blocked ? `${blocked.name} needs input: ${blocked.question}` : failed ? `${tasks.length - failed}/${tasks.length} tasks completed; ${failed} failed.` : `${tasks.length}/${tasks.length} tasks completed.`;
+		applyRunStatus(runRecord, status, { question: blocked?.question });
+		await writeJsonAtomic(runFile, runRecord);
+		return { ok: status === "completed", status, runId, label: options.label, requestedConcurrency, effectiveConcurrency, tasks: settledResults, activity, summary, documents: settledResults.flatMap((result) => result.documents), recordDirectory: runDirectory, tabId };
+	} catch (error) {
+		applyRunStatus(runRecord, options.signal?.aborted ? "cancelled" : "failed", { error: error instanceof Error ? error.message : String(error) });
+		await writeJsonAtomic(runFile, runRecord);
+		throw error;
+	} finally {
+		const keepTab = !options.signal?.aborted && activity.some((entry) => entry.status === "blocked" || entry.status === "queued" || entry.status === "running");
+		if (tabId && !keepTab) {
+			try {
+				await cleanupRunTab({
+					herdr, tabId, runFile, runRecord, signal: options.signal, failureStatus: "failed",
+					errorPrefix: "Task results settled, but Herdr tab cleanup failed",
+					onError: (message) => { emit("failed", message); options.onCleanupError?.(message); },
+				});
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				const cleanupError = new Error(`Task results settled, but Herdr tab cleanup failed: ${message}`) as Error & { recordDirectory: string; runId: string };
+				cleanupError.recordDirectory = runDirectory;
+				cleanupError.runId = runId;
+				throw cleanupError;
+			}
+		}
+	}
+}