@maxiaochao/pi-toolkit 0.9.6 → 0.10.0

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

@@ -0,0 +1,210 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { appendFile, mkdir, readFile, rm, rmdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.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, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskRecord, type TaskStatus } from "./records.ts";
+import { continuationSystemPrompt } from "./protocol.ts";
+import { isAbortError } from "./errors.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface HistoricalTask { order: number; id: string; name: string; agent: string; status: TaskStatus; summary?: string; question?: string; documents: PersistedDocument[]; recordDirectory: string; sessionFile: string; model?: string; thinking?: string; tools?: string[]; skills: string[]; access?: string; }
+export interface HistoricalRun { id: string; label: string; status: RunStatus; startedAt: string; completedAt?: string; effectiveConcurrency?: number; cleanupPendingTabIds?: string[]; tasks: HistoricalTask[]; recordDirectory: string; }
+
+export async function ensureRuntimeIgnored(cwd: string): Promise<void> {
+	const piDirectory = join(cwd, ".pi");
+	await mkdir(piDirectory, { recursive: true, mode: 0o700 });
+	const dotGit = join(cwd, ".git");
+	let ignoreFile = join(piDirectory, ".gitignore");
+	let line = "herdr-subagents/runs/";
+	if (existsSync(dotGit)) {
+		let gitDirectory = dotGit;
+		if (!statSync(dotGit).isDirectory()) {
+			const configured = readFileSync(dotGit, "utf8").match(/^gitdir:\s*(.+)$/m)?.[1]?.trim();
+			if (configured) gitDirectory = isAbsolute(configured) ? configured : join(cwd, configured);
+		}
+		const commonDirectoryFile = join(gitDirectory, "commondir");
+		const commonDirectory = existsSync(commonDirectoryFile) ? join(gitDirectory, readFileSync(commonDirectoryFile, "utf8").trim()) : gitDirectory;
+		ignoreFile = join(commonDirectory, "info", "exclude");
+		line = "/.pi/herdr-subagents/runs/";
+		await mkdir(join(commonDirectory, "info"), { recursive: true });
+	}
+	const current = existsSync(ignoreFile) ? await readFile(ignoreFile, "utf8") : "";
+	if (current.split(/\r?\n/).includes(line)) return;
+	await appendFile(ignoreFile, `${current && !current.endsWith("\n") ? "\n" : ""}${line}\n`, { encoding: "utf8", mode: 0o600 });
+}
+
+export async function listSubagentHistory(cwd: string): Promise<HistoricalRun[]> {
+	const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+	if (!existsSync(runsDirectory)) return [];
+	const history: HistoricalRun[] = [];
+	for (const entry of readdirSync(runsDirectory).sort().reverse()) {
+		const directory = join(runsDirectory, entry);
+		try {
+			const run = await readRunRecord(join(directory, "run.json"));
+			const tasks: HistoricalTask[] = [];
+			let projectedStatus = run.status;
+			const tasksDirectory = join(directory, "tasks");
+			if (existsSync(tasksDirectory)) for (const taskEntry of readdirSync(tasksDirectory).sort()) {
+				const taskDirectory = join(tasksDirectory, taskEntry);
+				let task: TaskRecord;
+				try { task = await readTaskRecord(join(taskDirectory, "task.json")); }
+				catch (error) {
+					projectedStatus = "failed";
+					tasks.push({ order: tasks.length + 1, id: taskEntry, name: taskEntry, agent: "unknown", status: "failed", summary: `Invalid durable task: ${error instanceof Error ? error.message : String(error)}`, documents: [], recordDirectory: taskDirectory, sessionFile: join(taskDirectory, "session.jsonl"), skills: [] });
+					continue;
+				}
+				let report: { summary?: string; question?: string; documents: Array<{ path: string; description: string }> } = { documents: [] };
+				let historyStatus = task.status;
+				const reportFile = join(taskDirectory, "report.json");
+				if (existsSync(reportFile)) {
+					try { report = await readReport(reportFile); }
+					catch (error) {
+						historyStatus = "failed";
+						report = { summary: `Invalid durable report: ${error instanceof Error ? error.message : String(error)}`, documents: [] };
+					}
+				} else if (["completed", "failed", "blocked"].includes(task.status)) {
+					historyStatus = "failed";
+					report = { summary: `Missing structured report: ${reportFile}`, documents: [] };
+				}
+				tasks.push({ order: task.order ?? tasks.length + 1, id: task.id, name: task.name ?? task.agent ?? "worker", agent: task.agent ?? "worker", status: historyStatus, summary: report.summary, question: report.question, documents: report.documents ?? [], recordDirectory: taskDirectory, sessionFile: task.sessionFile, model: task.model, thinking: task.thinking, tools: task.tools, skills: task.skills ?? [], access: task.access });
+			}
+			history.push({ id: run.id, label: run.label, status: projectedStatus, startedAt: run.startedAt, completedAt: run.completedAt, effectiveConcurrency: run.effectiveConcurrency, cleanupPendingTabIds: run.cleanupPendingTabIds, tasks, recordDirectory: directory });
+		} catch (error) {
+			history.push({ id: entry, label: "Unreadable Subagent run", status: "failed", startedAt: "", tasks: [{ order: 1, id: `${entry}-invalid`, name: "Invalid durable run", agent: "unknown", status: "failed", summary: `Could not read Subagent history ${directory}: ${error instanceof Error ? error.message : String(error)}`, documents: [], recordDirectory: directory, sessionFile: join(directory, "session.jsonl"), skills: [] }], recordDirectory: directory });
+		}
+	}
+	return history;
+}
+
+export function historyText(history: HistoricalRun[]): string {
+	if (!history.length) return "No Subagent history in this project.";
+	return history.flatMap((run) => [`${run.id} · ${run.label} · ${run.status} · ${run.tasks.length} tasks`, ...run.tasks.map((task) => `  ${task.order}. ${task.name}: ${task.status}${task.summary ? ` — ${task.summary}` : ""}`)]).join("\n");
+}
+
+export async function cleanSubagentRun(cwd: string, runId: string): Promise<boolean> {
+	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
+	if (!run) return false;
+	if (isActiveStatus(run.status)) throw new Error(`Subagent run '${runId}' is still active and cannot be cleaned.`);
+	if (run.cleanupPendingTabIds?.length) throw new Error(`Subagent run '${runId}' is still waiting to clean up Herdr tabs ${run.cleanupPendingTabIds.join(", ")}.`);
+	await rm(run.recordDirectory, { recursive: true, force: false });
+	return true;
+}
+
+export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; stalledWarningSeconds?: number; onStalled?: (message: string) => void; }
+
+export async function resumeHistoricalTask(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions = {}): Promise<{ runId: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string }> {
+	const runDirectory = await findRunDirectory(join(cwd, ".pi", "herdr-subagents", "runs"), runId);
+	if (!runDirectory) throw new Error(`Unknown Subagent run '${runId}'.`);
+	const lockDirectory = join(runDirectory, ".resume.lock");
+	try { await mkdir(lockDirectory); }
+	catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Subagent run '${runId}' already has a historical resume in progress (lock: ${lockDirectory}).`);
+		throw error;
+	}
+	try { return await resumeHistoricalTaskLocked(cwd, runId, taskNumber, prompt, options); }
+	finally { await rmdir(lockDirectory); }
+}
+
+async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions): Promise<{ runId: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string }> {
+	const herdr = options.herdr ?? new CliHerdrAutomation();
+	const { signal, onCleanupError } = options;
+	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
+	const historical = run?.tasks.find((task) => task.order === taskNumber);
+	if (!run || !historical) throw new Error(`Unknown historical task ${runId}#${taskNumber}.`);
+	if (isActiveStatus(run.status)) throw new Error(`Subagent run '${runId}' is still active. Use action 'respond' for blocked work or wait for it to settle before resuming history.`);
+	if (run.cleanupPendingTabIds?.length) throw new Error(`Subagent run '${runId}' is still waiting to clean up Herdr tabs ${run.cleanupPendingTabIds.join(", ")}.`);
+	if (!existsSync(historical.sessionFile)) throw new Error(`Historical task ${runId}#${taskNumber} has no saved Pi session.`);
+	const taskFile = join(historical.recordDirectory, "task.json");
+	const task = await readTaskRecord(taskFile);
+	const attempt = Number(task.attempt ?? 1) + 1;
+	const turnsDirectory = join(historical.recordDirectory, "turns");
+	await mkdir(turnsDirectory, { recursive: true, mode: 0o700 });
+	const initialTurnFile = join(turnsDirectory, "01.json");
+	if (!existsSync(initialTurnFile)) {
+		const initialReportFile = join(historical.recordDirectory, "report.json");
+		let initialReport;
+		try { initialReport = await readReport(initialReportFile); }
+		catch (error) { initialReport = { status: "failed" as const, summary: `Previous structured report was unavailable: ${error instanceof Error ? error.message : String(error)}`, documents: [] }; }
+		await writeJsonAtomic(initialTurnFile, { attempt: 1, prompt: task.prompt, status: task.status, summary: initialReport.summary, question: initialReport.question, error: initialReport.error, documents: initialReport.documents ?? [], sessionFile: historical.sessionFile, startedAt: task.startedAt, completedAt: task.completedAt });
+	}
+	const turnFile = join(turnsDirectory, `${String(attempt).padStart(2, "0")}.json`);
+	const followupPrompt = join(historical.recordDirectory, "followup-system-prompt.md");
+	await writeTextAtomic(followupPrompt, `${continuationSystemPrompt(task.systemPrompt, "Continue the requested historical work.", "followup")}\n`);
+	let tab: { tabId: string; paneId: string } | undefined;
+	let failedAttempt: { status: "cancelled" | "failed"; report: PersistedReport; error: unknown } | undefined;
+	const agentName = liveAgentName(historical.id, attempt);
+	try {
+		let report: PersistedReport;
+		let status: "blocked" | "completed" | "failed";
+		try {
+			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: historical.recordDirectory };
+			tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd, label: `SA · ${run.label}`, env, focus: false, signal: options.signal });
+			const paneLabel = `${String(historical.order).padStart(2, "0")} · ${historical.name}`;
+			await herdr.renamePane(tab.paneId, paneLabel, options.signal);
+			applyTaskStatus(task, "running");
+			Object.assign(task, { attempt, currentTurnFile: turnFile, tabId: tab.tabId, paneId: tab.paneId, paneLabel, agentName });
+			const activeRunFile = join(run.recordDirectory, "run.json");
+			const activeRunRecord = await readRunRecord(activeRunFile);
+			applyRunStatus(activeRunRecord, "running");
+			Object.assign(activeRunRecord, { ...ownerRecord(options.owner), tabId: tab.tabId, paneIds: [...new Set([...(activeRunRecord.paneIds ?? []), tab.paneId])] });
+			await Promise.all([
+				writeJsonAtomic(taskFile, task),
+				writeJsonAtomic(turnFile, { attempt, prompt, status: "running", sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, startedAt: new Date().toISOString() }),
+				writeJsonAtomic(activeRunFile, activeRunRecord),
+			]);
+			report = (await promptLiveAgent({ herdr, task: { ...task, id: historical.id, sessionFile: historical.sessionFile }, paneId: tab.paneId, prompt, systemPromptFile: followupPrompt, agentName, signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => options.onStalled?.(`${historical.name} appears stalled; it is still running.`) })).report;
+			status = applyReport(task, report);
+		} catch (error) {
+			const settled = await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
+				cancelled: isAbortError(error, signal),
+				error: error instanceof Error ? error.message : String(error),
+				name: `${historical.name} follow-up`,
+				replaceReport: true,
+			});
+			failedAttempt = { ...settled, error };
+			throw error;
+		}
+		await Promise.all([
+			writeJsonAtomic(taskFile, task),
+			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents ?? [], sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, completedAt: new Date().toISOString(), ...(report.question ? { question: report.question } : {}), ...(report.error ? { error: report.error } : {}) }),
+		]);
+		const runRecord = await readRunRecord(join(run.recordDirectory, "run.json"));
+		const aggregateStatus = aggregateTaskStatus((await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId)?.tasks.map((entry) => entry.status) ?? [status]);
+		applyRunStatus(runRecord, aggregateStatus, { question: report.question });
+		Object.assign(runRecord, { ...ownerRecord(options.owner), tabId: tab.tabId });
+		await writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord);
+		if (status !== "blocked") {
+			await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
+		}
+		return { runId, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		const completedAt = new Date().toISOString();
+		const settled = failedAttempt ?? await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
+			cancelled: isAbortError(error, signal),
+			error: message,
+			name: `${historical.name} follow-up`,
+			at: completedAt,
+			replaceReport: true,
+		});
+		const { status, report } = settled;
+		task.attempt = attempt;
+		const runRecord = await readRunRecord(join(run.recordDirectory, "run.json"));
+		const aggregateStatus = status === "cancelled" ? "cancelled" : aggregateTaskStatus(run.tasks.map((entry) => entry.id === historical.id ? status : entry.status));
+		applyRunStatus(runRecord, aggregateStatus, { error: message });
+		Object.assign(runRecord, { ...ownerRecord(options.owner), ...(tab ? { tabId: tab.tabId } : {}) });
+		await Promise.all([
+			writeJsonAtomic(taskFile, task),
+			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents, error: message, sessionFile: historical.sessionFile, ...(tab ? { tabId: tab.tabId, paneId: tab.paneId } : {}), completedAt }),
+			writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord),
+		]);
+		if (tab) await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError, failureStatus: "failed" });
+		throw error;
+	}
+}

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

@@ -0,0 +1,87 @@
+import { existsSync } from "node:fs";
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { HerdrAutomation } from "./herdr.ts";
+import type { HerdrSubagentsReport } from "./runner.ts";
+import { parseReport } from "./records.ts";
+
+export interface LiveTaskRecord {
+	id: string;
+	name?: string;
+	agent?: string;
+	sessionFile: string;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	skills?: string[];
+}
+
+export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): string[] {
+	const args = [
+		"--approve",
+		"--session", task.sessionFile,
+		"--name", `Subagent: ${task.name ?? task.agent ?? "worker"}`,
+		"--no-extensions",
+		"--extension", fileURLToPath(new URL("../extensions/subagent-report.ts", import.meta.url)),
+		"--no-skills",
+		"--append-system-prompt", systemPromptFile,
+	];
+	if (task.model) args.push("--model", task.model);
+	if (task.thinking) args.push("--thinking", task.thinking);
+	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "subagent_report"])].join(","));
+	for (const skill of task.skills ?? []) args.push("--skill", skill);
+	return args;
+}
+
+export function liveAgentName(taskId: string, attempt = 1): string {
+	return `herdr-subagent-${taskId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 12)}-${attempt}`;
+}
+
+export async function promptLiveAgent(options: {
+	herdr: HerdrAutomation;
+	task: LiveTaskRecord;
+	paneId: string;
+	prompt: string;
+	systemPromptFile: string;
+	agentName?: string;
+	attempt?: number;
+	signal?: AbortSignal;
+	start?: boolean;
+	stalledWarningMs?: number;
+	onStalled?: () => void;
+}): Promise<{ report: HerdrSubagentsReport; agentName: string }> {
+	const taskDirectory = dirname(options.task.sessionFile);
+	const reportFile = join(taskDirectory, "report.json");
+	await rm(reportFile, { force: true });
+	const agentName = options.agentName ?? liveAgentName(options.task.id, options.attempt);
+	if (options.start !== false) {
+		await options.herdr.startAgent({
+			name: agentName,
+			kind: "pi",
+			paneId: options.paneId,
+			args: childPiArgs(options.task, options.systemPromptFile),
+			signal: options.signal,
+		});
+	}
+	const stalledTimer = options.stalledWarningMs ? setTimeout(() => options.onStalled?.(), options.stalledWarningMs) : undefined;
+	let promptError: unknown;
+	try { await options.herdr.promptAgent({ target: agentName, prompt: options.prompt, signal: options.signal }); }
+	catch (error) { promptError = error; }
+	finally { if (stalledTimer) clearTimeout(stalledTimer); }
+	if (!existsSync(reportFile)) {
+		if (promptError) throw promptError;
+		throw new Error("Child Pi settled but did not submit a subagent_report.");
+	}
+	let value: unknown;
+	try { value = JSON.parse(await readFile(reportFile, "utf8")); }
+	catch {
+		if (promptError) throw new Error(`${promptError instanceof Error ? promptError.message : String(promptError)}; Child Pi also submitted an invalid subagent_report.`);
+		throw new Error("Child Pi submitted an invalid subagent_report.");
+	}
+	try { return { report: parseReport(value, "child subagent_report") as HerdrSubagentsReport, agentName }; }
+	catch (error) {
+		const detail = `Child Pi submitted an invalid subagent_report: ${error instanceof Error ? error.message : String(error)}`;
+		throw new Error(promptError ? `${promptError instanceof Error ? promptError.message : String(promptError)}; ${detail}` : detail);
+	}
+}

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

@@ -0,0 +1,18 @@
+import type { BatchResult } from "./batch-runner.ts";
+import type { HerdrAutomation } from "./herdr.ts";
+
+export function activityCounts(run: Pick<BatchResult, "activity">): Record<"running" | "queued" | "blocked" | "failed" | "completed", number> {
+	const count = (status: string) => run.activity.filter((task) => task.status === status).length;
+	return { running: count("running"), queued: count("queued"), blocked: count("blocked"), failed: count("failed"), completed: count("completed") };
+}
+
+export function activeRunText(run: Pick<BatchResult, "label" | "runId" | "activity">): string {
+	return [`${run.label} (${run.runId})`, ...run.activity.map((task) => `${task.index + 1}. ${task.name}: ${task.status}`)].join("\n");
+}
+
+export async function focusActiveTask(run: Pick<BatchResult, "activity"> | undefined, taskNumber: number, herdr: HerdrAutomation): Promise<boolean> {
+	const task = run?.activity.find((candidate) => candidate.index === taskNumber - 1);
+	if (!task?.paneId) return false;
+	await herdr.focusPane(task.paneId);
+	return true;
+}

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

@@ -0,0 +1,17 @@
+export interface OwnerIdentity {
+	sessionId?: string;
+	processId?: number;
+}
+
+export function ownerRecord(owner?: OwnerIdentity): { ownerSessionId?: string; ownerProcessId?: number } {
+	return {
+		...(owner?.sessionId ? { ownerSessionId: owner.sessionId } : {}),
+		...(owner?.processId ? { ownerProcessId: owner.processId } : {}),
+	};
+}
+
+export function isProcessAlive(pid: unknown): boolean {
+	if (!Number.isInteger(pid) || Number(pid) <= 0) return false;
+	try { process.kill(Number(pid), 0); return true; }
+	catch { return false; }
+}

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

@@ -0,0 +1,21 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+export const HerdrSubagentsParams = Type.Object({
+	action: Type.Optional(StringEnum(["list", "respond", "history", "resume", "cleanup"] as const, { description: "Operation mode. Omit it to execute one task or a batch." })),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, or cleanup." })),
+	answer: Type.Optional(Type.String({ minLength: 1, description: "Answer sent to a blocked task when action is respond." })),
+	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number selected for respond or resume." })),
+	prompt: Type.Optional(Type.String({ minLength: 1, description: "Task prompt for single execution, or follow-up prompt for resume." })),
+	agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for single execution. Defaults to worker." })),
+	label: Type.Optional(Type.String({ minLength: 1, maxLength: 48, description: "Short Herdr run-tab label." })),
+	model: Type.Optional(Type.String({ minLength: 1, description: "Optional Pi model override, for example provider/model:high." })),
+	tasks: Type.Optional(Type.Array(Type.Object({
+		name: Type.String({ minLength: 1, maxLength: 48, description: "Short task name shown in the pane and task list." }),
+		prompt: Type.String({ minLength: 1, description: "Self-contained prompt for this task." }),
+		agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for this task. Defaults to worker." })),
+		model: Type.Optional(Type.String({ minLength: 1, description: "Optional model override for this task." })),
+	}), { minItems: 1, description: "Ordered tasks for bounded-concurrency batch execution." })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneously active Agents in a batch." })),
+	background: Type.Optional(Type.Boolean({ description: "Return a run ID immediately while the batch continues in this parent session." })),
+}, { additionalProperties: false });

package/packages/{tiny-subagent → herdr-subagents}/src/personas.ts

@@ -17,6 +17,9 @@ export interface AgentDefinition {
 	description: string;
 	model?: string;
 	tools?: string[];
+	access?: "read" | "write";
+	thinking?: string;
+	skills?: string[];
 	systemPrompt: string;
 	filePath: string;
 }
@@ -70,24 +73,32 @@ export function parseAgentMarkdown(content: string, filePath = "<memory>"): Agen
 	}
 
 	const model = fields.get("model")?.trim() || undefined;
+	const rawAccess = fields.get("access")?.trim();
+	if (rawAccess && rawAccess !== "read" && rawAccess !== "write") throw new Error("frontmatter access must be read or write");
+	const access = rawAccess as "read" | "write" | undefined;
+	const thinking = fields.get("thinking")?.trim() || undefined;
+	const skills = fields.has("skills") ? parseList(fields.get("skills") ?? "") : undefined;
 	return {
 		name,
 		description,
 		...(model ? { model } : {}),
 		...(tools ? { tools } : {}),
+		...(access ? { access } : {}),
+		...(thinking ? { thinking } : {}),
+		...(skills ? { skills } : {}),
 		systemPrompt: lines.slice(end + 1).join("\n").trim(),
 		filePath,
 	};
 }
 
-export function discoverPackageAgents(agentsDir: string): AgentDiscovery {
+export function discoverPackageAgents(agentsDir: string, optional = false): AgentDiscovery {
 	const agents: AgentDefinition[] = [];
 	const diagnostics: string[] = [];
 	let entries: string[];
 	try {
 		entries = readdirSync(agentsDir).filter((entry) => entry.endsWith(".md")).sort();
 	} catch (error) {
-		return { agents, diagnostics: [`Cannot read persona directory ${agentsDir}: ${error instanceof Error ? error.message : String(error)}`] };
+		return { agents, diagnostics: optional ? [] : [`Cannot read persona directory ${agentsDir}: ${error instanceof Error ? error.message : String(error)}`] };
 	}
 
 	const names = new Set<string>();

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

@@ -0,0 +1,23 @@
+export type ReportPromptKind = "initial" | "resumed" | "followup";
+
+const TURN_INTRO: Record<ReportPromptKind, string> = {
+	initial: "",
+	resumed: "This is a resumed turn.",
+	followup: "This is a new turn in the same logical task.",
+};
+
+export function reportProtocolPrompt(systemPrompt: string, kind: ReportPromptKind = "initial"): string {
+	return [
+		TURN_INTRO[kind],
+		systemPrompt.trim(),
+		"",
+		"When this turn is finished, call subagent_report exactly once for this turn.",
+		"Put the complete final answer in result, a concise parent-facing paragraph in summary, and list any useful document paths.",
+		"Use status=needs-input with question when missing information prevents progress, or status=failed with an error when the task cannot be completed.",
+	].filter((line, index) => line || index > 1).join("\n").trim();
+}
+
+export function continuationSystemPrompt(originalPrompt: string | undefined, instruction: string, kind: Exclude<ReportPromptKind, "initial">): string {
+	if (!originalPrompt?.trim()) return reportProtocolPrompt(instruction, kind);
+	return [TURN_INTRO[kind], originalPrompt.trim(), "", instruction.trim()].join("\n").trim();
+}

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

@@ -0,0 +1,70 @@
+import { existsSync, readdirSync } from "node:fs";
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import type { HerdrSubagentsToolParams } from "./tool.ts";
+import { isProcessAlive, ownerRecord, type OwnerIdentity } from "./ownership.ts";
+import { writeJsonAtomic } from "./state.ts";
+import { findRunDirectory } from "./run-locator.ts";
+
+export interface QueuedRunRecord { runId: string; cwd: string; ownerSessionId?: string; ownerProcessId?: number; params: HerdrSubagentsToolParams; queuedAt: string; }
+function queueDirectory(cwd: string): string { return join(cwd, ".pi", "herdr-subagents", "queue"); }
+
+export async function persistQueuedRun(cwd: string, runId: string, params: HerdrSubagentsToolParams, owner?: OwnerIdentity): Promise<void> {
+	const directory = queueDirectory(cwd);
+	await mkdir(directory, { recursive: true, mode: 0o700 });
+	await writeJsonAtomic(join(directory, `${runId}.json`), { runId, cwd, ...ownerRecord(owner), params: { ...params, background: true }, queuedAt: new Date().toISOString() });
+}
+
+export async function removeQueuedRun(cwd: string, runId: string): Promise<void> {
+	await rm(join(queueDirectory(cwd), `${runId}.json`), { force: true });
+}
+
+export async function loadQueuedRuns(cwd: string, onError?: (message: string) => void): Promise<QueuedRunRecord[]> {
+	const directory = queueDirectory(cwd);
+	if (!existsSync(directory)) return [];
+	const records: QueuedRunRecord[] = [];
+	for (const entry of readdirSync(directory).filter((name) => name.endsWith(".json")).sort()) {
+		const path = join(directory, entry);
+		try { records.push(JSON.parse(await readFile(path, "utf8")) as QueuedRunRecord); }
+		catch (error) {
+			const message = `Could not read queued Subagent run ${path}: ${error instanceof Error ? error.message : String(error)}`;
+			if (!onError) throw new Error(message);
+			onError(message);
+		}
+	}
+	return records.sort((left, right) => left.queuedAt.localeCompare(right.queuedAt));
+}
+
+export interface CancelQueuedRunsOptions { reason?: string; owner?: OwnerIdentity; onlyOrphaned?: boolean; onError?: (message: string) => void; }
+
+export async function cancelQueuedRuns(cwd: string, runIds: string[], options: CancelQueuedRunsOptions = {}): Promise<void> {
+	const reason = options.reason ?? "Parent Pi session closed.";
+	const selected = new Set(runIds);
+	for (const queued of await loadQueuedRuns(cwd, options.onError)) {
+		if (!selected.has(queued.runId)) continue;
+		if (!options.onlyOrphaned && options.owner?.sessionId && queued.ownerSessionId !== options.owner.sessionId) continue;
+		if (options.onlyOrphaned) {
+			const differentOwner = options.owner?.sessionId !== undefined && queued.ownerSessionId !== options.owner.sessionId;
+			if (!differentOwner) continue;
+			const ownedByAnotherLiveProcess = queued.ownerProcessId !== (options.owner?.processId ?? process.pid) && isProcessAlive(queued.ownerProcessId);
+			if (ownedByAnotherLiveProcess) continue;
+		}
+		const runsDirectory = join(cwd, ".pi", "herdr-subagents", "runs");
+		const alreadyPersisted = Boolean(await findRunDirectory(runsDirectory, queued.runId));
+		if (alreadyPersisted) { await removeQueuedRun(cwd, queued.runId); continue; }
+		const now = new Date().toISOString();
+		const runDirectory = join(cwd, ".pi", "herdr-subagents", "runs", `${now.replace(/[-:.]/g, "").replace("Z", "Z-")}${queued.runId.slice(0, 8)}`);
+		const tasks = queued.params.tasks ?? [];
+		await mkdir(join(runDirectory, "tasks"), { recursive: true, mode: 0o700 });
+		const taskIds: string[] = [];
+		for (const [index, task] of tasks.entries()) {
+			const id = `${queued.runId}-queued-${index + 1}`;
+			taskIds.push(id);
+			const directory = join(runDirectory, "tasks", `${String(index + 1).padStart(2, "0")}-queued`);
+			await mkdir(directory, { recursive: true, mode: 0o700 });
+			await writeJsonAtomic(join(directory, "task.json"), { id, runId: queued.runId, order: index + 1, name: task.name, prompt: task.prompt, agent: task.agent ?? "worker", model: task.model, status: "cancelled", error: reason, sessionFile: join(directory, "session.jsonl"), startedAt: queued.queuedAt, completedAt: now });
+		}
+		await writeJsonAtomic(join(runDirectory, "run.json"), { id: queued.runId, label: queued.params.label ?? "batch", status: "cancelled", cwd, ownerSessionId: queued.ownerSessionId, ownerProcessId: queued.ownerProcessId, taskIds, startedAt: queued.queuedAt, completedAt: now, error: reason });
+		await removeQueuedRun(cwd, queued.runId);
+	}
+}