@maxiaochao/pi-toolkit 0.9.6 → 0.10.1

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

@@ -0,0 +1,250 @@
+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 { ensureRuntimeIgnored } from "./history.ts";
+import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { writeJsonAtomic } from "./state.ts";
+import { cleanupRunTab } from "./tab-cleanup.ts";
+import type { OwnerIdentity } from "./ownership.ts";
+import { ownerRecord } from "./ownership.ts";
+import { applyReport, applyTaskStatus, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type TaskRecord } from "./records.ts";
+import { reportProtocolPrompt } from "./protocol.ts";
+import { applyRunStatus } from "./run-status.ts";
+import { isAbortError } from "./errors.ts";
+
+const CHILD_ENV = "PI_HERDR_SUBAGENTS_CHILD";
+const TASK_DIRECTORY_ENV = "PI_HERDR_SUBAGENTS_TASK_DIR";
+
+export type HerdrSubagentsDocument = PersistedDocument;
+export type HerdrSubagentsReport = PersistedReport;
+
+export interface HerdrSubagentsOptions {
+	agent?: string;
+	label?: string;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	skills?: string[];
+	access?: "read" | "write";
+	systemPrompt?: string;
+	cwd?: string;
+	signal?: AbortSignal;
+	herdr?: HerdrAutomation;
+	owner?: OwnerIdentity;
+	onUpdate?: (result: HerdrSubagentsResult) => void;
+	onCleanupError?: (message: string) => void;
+	stalledWarningSeconds?: number;
+	onStalled?: (message: string) => void;
+}
+
+export interface HerdrSubagentsResult {
+	ok: boolean;
+	status: "starting" | "running" | "blocked" | "completed" | "failed" | "cancelled";
+	summary: string;
+	documents: HerdrSubagentsDocument[];
+	output: string;
+	errorMessage?: string;
+	runId?: string;
+	taskId?: string;
+	tabId?: string;
+	paneId?: string;
+	sessionFile?: string;
+	recordDirectory?: string;
+	model?: string;
+	cwd: string;
+	durationMs: number;
+}
+
+function compactText(report: HerdrSubagentsReport): string {
+	const lines = [report.summary];
+	if (report.documents.length > 0) {
+		lines.push("", "Documents:", ...report.documents.map((document) => `- ${document.description}: ${document.path}`));
+	}
+	if (report.error) lines.push("", `Error: ${report.error}`);
+	return lines.join("\n");
+}
+
+function failure(cwd: string, startedAt: number, errorMessage: string, fields: Partial<HerdrSubagentsResult> = {}): HerdrSubagentsResult {
+	return {
+		ok: false,
+		status: "failed",
+		summary: "Herdr Subagents failed.",
+		documents: [],
+		output: `Herdr Subagents failed.\nError: ${errorMessage}`,
+		errorMessage,
+		cwd,
+		durationMs: Date.now() - startedAt,
+		...fields,
+	};
+}
+
+async function writeJson(path: string, value: unknown): Promise<void> {
+	await writeJsonAtomic(path, value);
+}
+
+export async function runHerdrSubagents(prompt: string, options: HerdrSubagentsOptions = {}): Promise<HerdrSubagentsResult> {
+	const startedAt = Date.now();
+	const cwd = options.cwd ?? process.cwd();
+	if (process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) {
+		return failure(cwd, startedAt, "Herdr Subagents must run from a Pi session inside Herdr.");
+	}
+
+	const runId = randomUUID();
+	const taskId = randomUUID();
+	const agent = options.agent?.trim() || "worker";
+	const label = options.label?.trim() || agent;
+	const runDirectory = join(cwd, ".pi", "herdr-subagents", "runs", `${new Date().toISOString().replace(/[-:.]/g, "").replace("Z", "Z-")}${runId.slice(0, 8)}`);
+	const taskDirectory = join(runDirectory, "tasks", `01-${taskId.slice(0, 8)}`);
+	const sessionFile = join(taskDirectory, "session.jsonl");
+	const systemPromptFile = join(taskDirectory, "system-prompt.md");
+	const reportFile = join(taskDirectory, "report.json");
+	const runFile = join(runDirectory, "run.json");
+	const taskFile = join(taskDirectory, "task.json");
+	const startedAtIso = new Date(startedAt).toISOString();
+	const systemPrompt = reportProtocolPrompt(options.systemPrompt ?? "You are a focused worker subagent.");
+	const runRecord: RunRecord = {
+		id: runId,
+		label,
+		status: "starting",
+		cwd,
+		...ownerRecord(options.owner),
+		stalledWarningSeconds: options.stalledWarningSeconds,
+		taskIds: [taskId],
+		startedAt: startedAtIso,
+	};
+	const taskRecord: TaskRecord = {
+		id: taskId,
+		runId,
+		order: 1,
+		name: label,
+		status: "starting",
+		prompt,
+		agent,
+		...(options.model ? { model: options.model } : {}),
+		...(options.thinking ? { thinking: options.thinking } : {}),
+		...(options.tools ? { tools: options.tools } : {}),
+		...(options.skills ? { skills: options.skills } : {}),
+		...(options.access ? { access: options.access } : {}),
+		systemPrompt,
+		sessionFile,
+		startedAt: startedAtIso,
+	};
+	await ensureRuntimeIgnored(cwd);
+	await mkdir(taskDirectory, { recursive: true, mode: 0o700 });
+	await writeFile(systemPromptFile, systemPrompt, { encoding: "utf8", mode: 0o600 });
+	await Promise.all([writeJson(runFile, runRecord), writeJson(taskFile, taskRecord)]);
+
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	let tabId: string | undefined;
+	let paneId: string | undefined;
+	let result: HerdrSubagentsResult | undefined;
+	const common = (): Partial<HerdrSubagentsResult> => ({
+		runId,
+		taskId,
+		...(tabId ? { tabId } : {}),
+		...(paneId ? { paneId } : {}),
+		sessionFile,
+		recordDirectory: taskDirectory,
+		...(options.model ? { model: options.model } : {}),
+	});
+	const update = (status: HerdrSubagentsResult["status"], summary: string) => {
+		options.onUpdate?.({
+			ok: false,
+			status,
+			summary,
+			documents: [],
+			output: summary,
+			cwd,
+			durationMs: Date.now() - startedAt,
+			...common(),
+		});
+	};
+	update("starting", "Creating Herdr tab...");
+
+	let attempt: { status: "blocked" | "completed" | "failed" | "cancelled"; report: PersistedReport; error?: unknown };
+	try {
+		const tab = await herdr.createTab({
+			workspaceId: process.env.HERDR_WORKSPACE_ID,
+			cwd,
+			label: `SA · ${label}`,
+			env: {
+				[CHILD_ENV]: "1",
+				[TASK_DIRECTORY_ENV]: taskDirectory,
+			},
+			focus: false,
+			signal: options.signal,
+		});
+		tabId = tab.tabId;
+		paneId = tab.paneId;
+		const paneLabel = `01 · ${label}`;
+		await herdr.renamePane(paneId, paneLabel, options.signal);
+		applyRunStatus(runRecord, "running");
+		Object.assign(runRecord, { tabId, paneId });
+		applyTaskStatus(taskRecord, "running");
+		Object.assign(taskRecord, { tabId, paneId, paneLabel });
+		await Promise.all([writeJson(runFile, runRecord), writeJson(taskFile, taskRecord)]);
+
+		const name = liveAgentName(taskId);
+		taskRecord.agentName = name;
+		await writeJson(taskFile, taskRecord);
+		update("starting", "Starting child Pi in Herdr...");
+		update("running", "Child Pi is working...");
+		const report = (await promptLiveAgent({ herdr, task: { ...taskRecord, id: taskId, sessionFile }, paneId, prompt, systemPromptFile, agentName: name, signal: options.signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => options.onStalled?.(`${label} appears stalled; it is still running.`) })).report;
+		attempt = { status: applyReport(taskRecord, report), report };
+	} catch (error) {
+		const settled = await settleAttemptFailure(taskRecord, reportFile, {
+			cancelled: isAbortError(error, options.signal),
+			error: error instanceof Error ? error.message : String(error),
+			name: "Herdr Subagents",
+			summary: isAbortError(error, options.signal) ? "Herdr Subagents was cancelled." : "Herdr Subagents failed.",
+		});
+		attempt = { ...settled, error };
+	}
+	try {
+		if (!attempt.error) {
+			const { report, status: settledStatus } = attempt;
+			const completedAt = new Date().toISOString();
+			applyRunStatus(runRecord, settledStatus, { at: completedAt, error: report.error, question: report.question });
+			await Promise.all([writeJson(runFile, runRecord), writeJson(taskFile, taskRecord)]);
+			result = {
+				ok: report.status === "completed",
+				status: settledStatus,
+				summary: report.summary,
+				documents: report.documents,
+				output: compactText(report),
+				...(report.error || report.question ? { errorMessage: report.error ?? report.question } : {}),
+				cwd,
+				durationMs: Date.now() - startedAt,
+				...common(),
+			};
+		} else {
+			const errorMessage = attempt.error instanceof Error ? attempt.error.message : String(attempt.error);
+			const cancelled = attempt.status === "cancelled";
+			const completedAt = new Date().toISOString();
+			applyRunStatus(runRecord, cancelled ? "cancelled" : "failed", { at: completedAt, error: errorMessage });
+			await Promise.all([writeJson(runFile, runRecord), writeJson(taskFile, taskRecord)]);
+			result = cancelled
+				? { ...failure(cwd, startedAt, errorMessage, common()), status: "cancelled", summary: "Herdr Subagents cancelled.", output: `Herdr Subagents cancelled.\nError: ${errorMessage}` }
+				: failure(cwd, startedAt, errorMessage, common());
+		}
+	} finally {
+		if (tabId && result?.status !== "blocked") {
+			try {
+				await cleanupRunTab({ herdr, tabId, runFile, runRecord, signal: options.signal, onError: options.onCleanupError, failureStatus: "failed" });
+			} catch (error) {
+				const cleanupError = error instanceof Error ? error.message : String(error);
+				if (result?.ok) {
+					const errorMessage = `Task completed but Herdr tab cleanup failed: ${cleanupError}`;
+					const completedAt = new Date().toISOString();
+					applyRunStatus(runRecord, "failed", { at: completedAt, error: errorMessage });
+					applyTaskStatus(taskRecord, "failed", { at: completedAt, error: errorMessage });
+					await Promise.all([writeJson(runFile, runRecord), writeJson(taskFile, taskRecord)]);
+					result = failure(cwd, startedAt, errorMessage, common());
+				}
+			}
+		}
+	}
+
+	return result ?? failure(cwd, startedAt, "Herdr Subagents ended without a result.", common());
+}

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

@@ -0,0 +1,11 @@
+import { rename, writeFile } from "node:fs/promises";
+
+export async function writeTextAtomic(path: string, content: string, mode = 0o600): Promise<void> {
+	const temporary = `${path}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
+	await writeFile(temporary, content, { encoding: "utf8", mode });
+	await rename(temporary, path);
+}
+
+export async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
+	await writeTextAtomic(path, `${JSON.stringify(value, null, 2)}\n`);
+}

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

@@ -0,0 +1,68 @@
+import type { HerdrAutomation } from "./herdr.ts";
+import { readRunRecord, type RunRecord } from "./records.ts";
+import { writeJsonAtomic } from "./state.ts";
+
+export async function cleanupRunTab(options: {
+	herdr: HerdrAutomation;
+	tabId: string;
+	runFile: string;
+	runRecord: RunRecord;
+	signal?: AbortSignal;
+	onError?: (message: string) => void;
+	onClosed?: (runRecord: RunRecord) => void | Promise<void>;
+	failureStatus?: "failed";
+	errorPrefix?: string;
+}): Promise<{ deferred: boolean }> {
+	const mergeLatest = async (update: (run: RunRecord) => void | Promise<void>, requirePending = false, clearPending = true) => {
+		const latest = await readRunRecord(options.runFile);
+		if (requirePending && !latest.cleanupPendingTabIds?.includes(options.tabId)) return;
+		if (clearPending) {
+			latest.cleanupPendingTabIds = latest.cleanupPendingTabIds?.filter((tabId) => tabId !== options.tabId);
+			if (!latest.cleanupPendingTabIds?.length) delete latest.cleanupPendingTabIds;
+		}
+		await update(latest);
+		await writeJsonAtomic(options.runFile, latest);
+		const mutableRecord = options.runRecord as unknown as Record<string, unknown>;
+		for (const key of Object.keys(mutableRecord)) if (!(key in latest)) delete mutableRecord[key];
+		Object.assign(options.runRecord, latest);
+	};
+	const reportFailure = async (error: unknown, requirePending = false) => {
+		const detail = error instanceof Error ? error.message : String(error);
+		try {
+			await mergeLatest((latest) => Object.assign(latest, { cleanupPendingTabIds: [...new Set([...(latest.cleanupPendingTabIds ?? []), options.tabId])], cleanupError: detail, ...(options.failureStatus ? { status: options.failureStatus } : {}) }), requirePending, false);
+		} catch (persistError) {
+			options.onError?.(`${options.errorPrefix ?? "Herdr tab cleanup failed"}: ${detail}; could not persist cleanup state: ${persistError instanceof Error ? persistError.message : String(persistError)}`);
+			return;
+		}
+		options.onError?.(`${options.errorPrefix ?? "Herdr tab cleanup failed"}: ${detail}`);
+	};
+	const finishClosed = async (requirePending = false) => mergeLatest(async (latest) => options.onClosed?.(latest), requirePending);
+	try {
+		if (options.signal?.aborted) {
+			await options.herdr.closeTab(options.tabId);
+			await finishClosed();
+			return { deferred: false };
+		}
+		if (await options.herdr.isTabFocused(options.tabId, options.signal)) {
+			const latest = await readRunRecord(options.runFile);
+			latest.cleanupPendingTabIds = [...new Set([...(latest.cleanupPendingTabIds ?? []), options.tabId])];
+			await writeJsonAtomic(options.runFile, latest);
+			Object.assign(options.runRecord, latest);
+			void options.herdr.waitForTabUnfocused(options.tabId, options.signal)
+				.then(() => options.herdr.closeTab(options.tabId, options.signal))
+				.then(() => finishClosed(true))
+				.catch(async (error) => {
+					if (!options.signal?.aborted) { await reportFailure(error, true); return; }
+					try {
+						await options.herdr.closeTab(options.tabId);
+						await finishClosed(true);
+					} catch (closeError) { await reportFailure(closeError, true); }
+				});
+			return { deferred: true };
+		}
+		await options.herdr.closeTab(options.tabId, options.signal);
+		await finishClosed();
+	}
+	catch (error) { await reportFailure(error); throw error; }
+	return { deferred: false };
+}

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

@@ -0,0 +1,217 @@
+import type { HerdrAutomation } from "./herdr.ts";
+import { loadSubagentConfiguration, type ConfigurationPaths, type SubagentConfiguration } from "./config.ts";
+import { runHerdrSubagents, type HerdrSubagentsResult } from "./runner.ts";
+import { runHerdrSubagentsBatch, type BatchResult, type BatchTask } from "./batch-runner.ts";
+import { respondToBlockedTask } from "./blocking.ts";
+import { cleanSubagentRun, historyText, listSubagentHistory, resumeHistoricalTask } from "./history.ts";
+import { HERDR_ACTIONS, validateToolParams } from "./validation.ts";
+import type { OwnerIdentity } from "./ownership.ts";
+
+export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
+
+export interface HerdrSubagentsToolParams {
+	action?: "list" | "respond" | "history" | "resume" | "cleanup";
+	prompt?: string;
+	agent?: string;
+	label?: string;
+	model?: string;
+	tasks?: HerdrSubagentsTaskParams[];
+	concurrency?: number;
+	background?: boolean;
+	runId?: string;
+	answer?: string;
+	task?: number;
+}
+
+export interface HerdrSubagentsToolContext {
+	cwd: string;
+	model?: { provider: string; id: string };
+	thinkingLevel?: string;
+}
+
+export interface HerdrSubagentsToolDependencies {
+	agentsDirectory: string;
+	herdr?: HerdrAutomation;
+	configurationPaths?: ConfigurationPaths;
+	owner?: OwnerIdentity;
+	runId?: string;
+}
+
+export type HerdrSubagentsDetails = HerdrSubagentsResult & {
+	agent: string;
+	description: string;
+	prompt: string;
+	personaPath: string;
+};
+
+export type HerdrSubagentsBatchDetails = BatchResult & { prompts: string[] };
+
+type ToolResponse = {
+	content: Array<{ type: "text"; text: string }>;
+	details: unknown;
+	isError?: boolean;
+};
+
+function modelId(ctx: HerdrSubagentsToolContext): string | undefined {
+	return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+}
+
+export function listText(discovery: SubagentConfiguration): string {
+	const lines = ["Available Herdr Subagents personas:"];
+	if (discovery.personas.length === 0) lines.push("- (none)");
+	for (const agent of discovery.personas) {
+		const model = agent.model ?? "unresolved";
+		const tools = agent.tools?.join(", ") ?? "Pi default built-in tools";
+		const skills = agent.skills.join(", ") || "none";
+		lines.push(`- ${agent.name}: ${agent.description} (source: ${agent.source}; access: ${agent.access}; model: ${model} [${agent.modelSource}]; thinking: ${agent.thinking ?? "default"}; tools: ${tools}; skills: ${skills})`);
+	}
+	if (discovery.diagnostics.length > 0) {
+		lines.push("", "Persona diagnostics:", ...discovery.diagnostics.map((diagnostic) => `- ${diagnostic}`));
+	}
+	return lines.join("\n");
+}
+
+function summaryText(result: HerdrSubagentsResult): string {
+	if (result.ok) return result.output;
+	const lines = [result.summary];
+	if (result.errorMessage) lines.push(`Error: ${result.errorMessage}`);
+	if (result.recordDirectory) lines.push(`Task record: ${result.recordDirectory}`);
+	return lines.join("\n");
+}
+
+interface ToolExecutionContext {
+	params: HerdrSubagentsToolParams;
+	signal?: AbortSignal;
+	onUpdate?: (response: ToolResponse) => void;
+	ctx: HerdrSubagentsToolContext;
+	dependencies: HerdrSubagentsToolDependencies;
+	discovery: SubagentConfiguration;
+}
+
+type ActionHandler = (execution: ToolExecutionContext) => Promise<ToolResponse>;
+
+const errorResponse = (text: string, details: Record<string, unknown> = {}): ToolResponse => ({
+	content: [{ type: "text", text }], details: { ...details, errorMessage: text }, isError: true,
+});
+
+const actionHandlers = {
+	async history({ ctx }: ToolExecutionContext) {
+		const history = await listSubagentHistory(ctx.cwd);
+		return { content: [{ type: "text", text: historyText(history) }], details: { action: "history", runs: history } };
+	},
+	async cleanup({ params, ctx }: ToolExecutionContext) {
+		try {
+			const cleaned = await cleanSubagentRun(ctx.cwd, params.runId as string);
+			const text = cleaned ? `Removed Subagent run ${params.runId}.` : `Unknown Subagent run '${params.runId}'.`;
+			return { content: [{ type: "text", text }], details: { action: "cleanup", runId: params.runId, cleaned }, ...(cleaned ? {} : { isError: true }) };
+		} catch (error) {
+			const text = error instanceof Error ? error.message : String(error);
+			return errorResponse(text, { action: "cleanup", runId: params.runId, cleaned: false });
+		}
+	},
+	async resume({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext) {
+		try {
+			const result = await resumeHistoricalTask(ctx.cwd, params.runId as string, params.task as number, (params.prompt as string).trim(), {
+				herdr: dependencies.herdr, signal, owner: dependencies.owner, stalledWarningSeconds: discovery.settings.stalledWarningSeconds,
+				onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "resume", runId: params.runId, stalled: true } }),
+				onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "resume", runId: params.runId, cleanupError: text } }),
+			});
+			return { content: [{ type: "text", text: result.summary }], details: result, ...(result.status === "failed" || result.status === "cancelled" ? { isError: true } : {}) };
+		} catch (error) { return errorResponse(error instanceof Error ? error.message : String(error)); }
+	},
+	async respond({ params, signal, onUpdate, ctx, dependencies }: ToolExecutionContext) {
+		try {
+			const result = await respondToBlockedTask(ctx.cwd, (params.runId as string).trim(), (params.answer as string).trim(), {
+				herdr: dependencies.herdr, taskNumber: params.task, signal, owner: dependencies.owner,
+				onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: partial }),
+				onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, stalled: true } }),
+				onWarning: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, warning: text } }),
+				onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, cleanupError: text } }),
+			});
+			const text = [result.summary, ...(result.question ? [`Question: ${result.question}`] : []), ...result.documents.map((document) => `${document.description}: ${document.path}`)].join("\n");
+			return { content: [{ type: "text", text }], details: result, ...(result.status === "failed" || result.status === "partial" || result.status === "cancelled" ? { isError: true } : {}) };
+		} catch (error) { return errorResponse(error instanceof Error ? error.message : String(error)); }
+	},
+	async list({ discovery }: ToolExecutionContext) {
+		return { content: [{ type: "text", text: listText(discovery) }], details: { action: "list", agents: discovery.personas, diagnostics: discovery.diagnostics, settings: discovery.settings } };
+	},
+} satisfies Record<keyof typeof HERDR_ACTIONS, ActionHandler>;
+
+async function executeBatch({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext): Promise<ToolResponse> {
+	const tasks = params.tasks as HerdrSubagentsTaskParams[];
+	const resolved: BatchTask[] = [];
+	for (const task of tasks) {
+		const personaName = task.agent?.trim() || "worker";
+		const persona = discovery.personas.find((candidate) => candidate.name === personaName);
+		if (!persona) return errorResponse(`Unknown persona '${personaName}'.\n\n${listText(discovery)}`);
+		resolved.push({ name: task.name, prompt: task.prompt, agent: persona.name, access: persona.access, model: task.model?.trim() || persona.model, thinking: persona.thinking ?? (persona.modelSource === "parent session" && !task.model ? ctx.thinkingLevel : undefined), tools: persona.tools, skills: persona.skills, systemPrompt: persona.systemPrompt });
+	}
+	try {
+		const result = await runHerdrSubagentsBatch(resolved, {
+			runId: dependencies.runId,
+			label: params.label?.trim() || "batch",
+			concurrency: params.concurrency ?? discovery.settings.defaultConcurrency,
+			maxConcurrency: discovery.settings.maxConcurrency,
+			stalledWarningSeconds: discovery.settings.stalledWarningSeconds,
+			cwd: ctx.cwd,
+			signal,
+			herdr: dependencies.herdr,
+			owner: dependencies.owner,
+			onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "batch", runId: dependencies.runId, cleanupError: text } }),
+			onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: { ...partial, prompts: tasks.map((task) => task.prompt) } }),
+		});
+		const lines = [result.summary, ...result.tasks.map((task) => `- ${task.name}: ${task.status} — ${task.summary}`)];
+		if (result.documents.length) lines.push("", "Documents:", ...result.documents.map((document) => `- ${document.description}: ${document.path}`));
+		return { content: [{ type: "text", text: lines.join("\n") }], details: { ...result, prompts: tasks.map((task) => task.prompt) }, ...(result.ok ? {} : { isError: true }) };
+	} catch (error) {
+		const text = error instanceof Error ? error.message : String(error);
+		const diagnostic = error as { recordDirectory?: string; runId?: string };
+		return errorResponse(text, { ...(diagnostic.recordDirectory ? { recordDirectory: diagnostic.recordDirectory } : {}), ...(diagnostic.runId ? { runId: diagnostic.runId } : {}) });
+	}
+}
+
+async function executeSingle({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext): Promise<ToolResponse> {
+	const prompt = params.prompt as string;
+	const selectedName = params.agent?.trim() || "worker";
+	const persona = discovery.personas.find((agent) => agent.name === selectedName);
+	if (!persona) return errorResponse(`Unknown persona '${selectedName}'.\n\n${listText(discovery)}`);
+	const explicitModel = params.model?.trim();
+	const selectedModel = explicitModel || persona.model || modelId(ctx);
+	const selectedThinking = persona.thinking ?? (!explicitModel && persona.modelSource === "parent session" ? ctx.thinkingLevel : undefined);
+	const details = (result: HerdrSubagentsResult): HerdrSubagentsDetails => ({ ...result, agent: persona.name, description: persona.description, prompt, personaPath: persona.filePath });
+	const result = await runHerdrSubagents(prompt, {
+		agent: persona.name,
+		label: params.label,
+		...(selectedModel ? { model: selectedModel } : {}),
+		...(selectedThinking ? { thinking: selectedThinking } : {}),
+		...(persona.tools ? { tools: persona.tools } : {}),
+		skills: persona.skills,
+		access: persona.access,
+		owner: dependencies.owner,
+		systemPrompt: persona.systemPrompt,
+		cwd: ctx.cwd,
+		signal,
+		herdr: dependencies.herdr,
+		stalledWarningSeconds: discovery.settings.stalledWarningSeconds,
+		onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { status: "running", stalled: true } }),
+		onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { status: "failed", cleanupError: text } }),
+		onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: details(partial) }),
+	});
+	return { content: [{ type: "text", text: summaryText(result) }], details: details(result), ...(result.ok ? {} : { isError: true }) };
+}
+
+export async function executeHerdrSubagents(
+	params: HerdrSubagentsToolParams,
+	signal: AbortSignal | undefined,
+	onUpdate: ((response: ToolResponse) => void) | undefined,
+	ctx: HerdrSubagentsToolContext,
+	dependencies: HerdrSubagentsToolDependencies,
+): Promise<ToolResponse> {
+	const validationError = validateToolParams(params);
+	if (validationError) return { content: [{ type: "text", text: validationError }], details: { errorMessage: validationError }, isError: true };
+	const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
+	const execution = { params, signal, onUpdate, ctx, dependencies, discovery };
+	if (params.action) return actionHandlers[params.action](execution);
+
+	return params.tasks ? executeBatch(execution) : executeSingle(execution);
+}

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

@@ -0,0 +1,38 @@
+import type { HerdrSubagentsToolParams } from "./tool.ts";
+
+const executionFields = ["prompt", "agent", "label", "model", "tasks", "concurrency", "background"] as const;
+
+export const HERDR_ACTIONS = {
+	list: { allowed: ["action"], includeRunId: false },
+	history: { allowed: ["action"], includeRunId: false },
+	cleanup: { allowed: ["action", "runId"], includeRunId: true },
+	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
+	resume: { allowed: ["action", "runId", "task", "prompt"], includeRunId: true },
+} as const satisfies Record<string, { allowed: readonly (keyof HerdrSubagentsToolParams)[]; includeRunId: boolean }>;
+
+export function validateToolParams(params: HerdrSubagentsToolParams): string | undefined {
+	const present = (key: keyof HerdrSubagentsToolParams) => params[key] !== undefined;
+	const extraField = (allowed: readonly (keyof HerdrSubagentsToolParams)[]) => Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsToolParams));
+	if (params.action) {
+		const extra = extraField(HERDR_ACTIONS[params.action].allowed);
+		if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
+		if (params.action === "cleanup" && !params.runId?.trim()) return "runId is required for action 'cleanup'.";
+		if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer are required for action 'respond'.";
+		if (params.action === "resume" && (!params.runId?.trim() || !params.task || !params.prompt?.trim())) return "runId, task, and prompt are required for action 'resume'.";
+		return undefined;
+	}
+	if (params.prompt && params.tasks) return "Provide either prompt or tasks, not both.";
+	if (params.prompt) {
+		const extra = extraField(["prompt", "agent", "label", "model"]);
+		if (extra) return `Field '${extra}' is not valid for single-task execution.`;
+		return undefined;
+	}
+	if (params.tasks) {
+		if (!params.tasks.length) return "tasks must contain at least one task.";
+		const extra = extraField(["tasks", "label", "concurrency", "background"]);
+		if (extra) return `Field '${extra}' is not valid for batch execution.`;
+		return undefined;
+	}
+	const supplied = executionFields.find((key) => present(key));
+	return supplied ? `Field '${supplied}' requires prompt or tasks.` : "Provide an action, prompt, or non-empty tasks list.";
+}