@maxiaochao/pi-toolkit 0.10.2 → 0.10.4

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

@@ -1,4 +1,8 @@
+import { readFile } from "node:fs/promises";
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { BatchResult } from "./batch-runner.ts";
+import type { TaskActivity } from "./records.ts";
 
 type FleetKey = "up" | "down" | "enter" | "escape";
 type KeyMatcher = (data: string, key: FleetKey) => boolean;
@@ -7,6 +11,8 @@ const legacyKeys: Record<FleetKey, string> = { up: "\u001b[A", down: "\u001b[B",
 const legacyMatchesKey: KeyMatcher = (data, key) => data === legacyKeys[key];
 
 export interface FleetInputResult { consume?: boolean; focusTask?: number; changed?: boolean; }
+export interface FleetTaskMetrics { tokens?: number; }
+export type FleetMetrics = ReadonlyMap<number, FleetTaskMetrics>;
 
 export function fleetEditorHasFocus(focused: unknown, isEditor: (value: unknown) => boolean): boolean {
 	return isEditor(focused);
@@ -25,6 +31,7 @@ export class FleetSelection {
 
 	handle(data: string, editorText: string, taskCount: number): FleetInputResult {
 		if (taskCount === 0) { this.reset(); return {}; }
+		this.selected = this.selectedIndex(taskCount);
 		if (!this.selecting) {
 			if (!this.matchesKey(data, "down") || editorText.length !== 0) return {};
 			this.selecting = true;
@@ -36,21 +43,125 @@ export class FleetSelection {
 			this.selected = (this.selected + delta + taskCount) % taskCount;
 			return { consume: true, changed: true };
 		}
-		if (this.matchesKey(data, "enter")) return { consume: true, focusTask: this.selected + 1 };
+		if (this.matchesKey(data, "enter")) return { consume: true, focusTask: this.selectedIndex(taskCount) + 1 };
 		if (this.matchesKey(data, "escape")) { this.selecting = false; return { consume: true, changed: true }; }
 		this.selecting = false;
 		return { changed: true };
 	}
 }
 
-export function fleetLines(batch: Pick<BatchResult, "label" | "activity">, selection: FleetSelection): string[] {
+function finiteTokenPart(value: unknown): number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+function usageTokens(value: unknown): number {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return 0;
+	const usage = value as Record<string, unknown>;
+	return finiteTokenPart(usage.input) + finiteTokenPart(usage.output) + finiteTokenPart(usage.cacheRead) + finiteTokenPart(usage.cacheWrite);
+}
+
+/** Match Pi's cumulative footer semantics without trusting an incomplete JSONL tail. */
+export function aggregateSessionTokens(jsonl: string): number {
+	let total = 0;
+	for (const line of jsonl.split(/\r?\n/)) {
+		if (!line.trim()) continue;
+		let entry: Record<string, unknown>;
+		try {
+			const parsed: unknown = JSON.parse(line);
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+			entry = parsed as Record<string, unknown>;
+		} catch { continue; }
+		if (entry.type === "usage") total += usageTokens(entry.usage);
+		else if (entry.type === "compaction" || entry.type === "branch_summary") total += usageTokens(entry.usage);
+		else if (entry.type === "message") {
+			const message = entry.message;
+			if (!message || typeof message !== "object" || Array.isArray(message)) continue;
+			const record = message as Record<string, unknown>;
+			if (record.role === "assistant" || record.role === "toolResult") total += usageTokens(record.usage);
+		}
+	}
+	return total;
+}
+
+export async function readSessionTokens(path: string): Promise<number | undefined> {
+	try { return aggregateSessionTokens(await readFile(path, "utf8")); }
+	catch { return undefined; }
+}
+
+export function formatFleetDuration(task: TaskActivity, now = Date.now()): string | undefined {
+	if (!task.startedAt || task.status === "queued" || task.status === "starting") return undefined;
+	let elapsed = typeof task.elapsedMs === "number" && Number.isFinite(task.elapsedMs) ? Math.max(0, task.elapsedMs) : undefined;
+	if (task.status === "running" && task.activeStartedAt) {
+		const activeStarted = Date.parse(task.activeStartedAt);
+		if (Number.isFinite(activeStarted) && now >= activeStarted) elapsed = (elapsed ?? 0) + (now - activeStarted);
+	}
+	if (elapsed === undefined) {
+		const started = Date.parse(task.startedAt);
+		const terminal = task.completedAt ?? (task.status === "blocked" ? task.updatedAt : undefined);
+		const ended = terminal ? Date.parse(terminal) : now;
+		if (!Number.isFinite(started) || !Number.isFinite(ended) || ended < started) return undefined;
+		elapsed = ended - started;
+	}
+	const seconds = Math.floor(elapsed / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+	return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+
+export function formatFleetTokens(tokens: number): string {
+	if (tokens < 1_000) return `${tokens} tok`;
+	if (tokens < 10_000) return `${(tokens / 1_000).toFixed(1)}k tok`;
+	if (tokens < 1_000_000) return `${Math.round(tokens / 1_000)}k tok`;
+	return `${(tokens / 1_000_000).toFixed(1)}m tok`;
+}
+
+function statusSummary(activity: TaskActivity[]): string {
 	const counts = new Map<string, number>();
-	for (const task of batch.activity) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
-	const summary = ["running", "queued", "blocked", "failed", "completed", "cancelled"]
+	for (const task of activity) counts.set(task.status, (counts.get(task.status) ?? 0) + 1);
+	return ["running", "queued", "blocked", "failed", "completed", "cancelled"]
 		.filter((status) => counts.has(status)).map((status) => `${status} ${counts.get(status)}`).join(" · ");
+}
+
+function fitColumns(left: string, right: string, width: number): string {
+	if (width <= 0) return "";
+	if (!right) return truncateToWidth(left, width);
+	const rightWidth = visibleWidth(right);
+	if (rightWidth + 2 >= width) return truncateToWidth(left, width);
+	const fittedLeft = truncateToWidth(left, width - rightWidth - 1);
+	const gap = " ".repeat(Math.max(1, width - visibleWidth(fittedLeft) - rightWidth));
+	return truncateToWidth(fittedLeft + gap + right, width);
+}
+
+type FleetTheme = Pick<Theme, "fg" | "bold">;
+const plainTheme: FleetTheme = { fg: (_color, text) => text, bold: (text) => text } as FleetTheme;
+
+export function fleetLines(
+	batch: Pick<BatchResult, "label" | "activity">,
+	selection: FleetSelection,
+	options: { width?: number; now?: number; metrics?: FleetMetrics; theme?: FleetTheme } = {},
+): string[] {
+	const width = Math.max(1, options.width ?? 120);
+	const theme = options.theme ?? plainTheme;
 	const selected = selection.selectedIndex(batch.activity.length);
-	return [
-		`Subagents · ${batch.label} · ${summary}`,
-		...batch.activity.map((task, index) => `${selection.isSelecting() && index === selected ? "›" : " "} ${String(task.index + 1).padStart(2, "0")} · ${task.name}  ${task.status}`),
-	];
+	const title = `─ ${theme.bold("Fleet")} · ${batch.label} · ${statusSummary(batch.activity)} `;
+	const titleWidth = visibleWidth(title);
+	const lines = [truncateToWidth(title + "─".repeat(Math.max(0, width - titleWidth)), width)];
+	const rows = batch.activity.map((task, index) => {
+		const chosen = selection.isSelecting() && index === selected;
+		const circle = task.status === "queued" || task.status === "starting" ? "○" : "●";
+		const color = task.status === "completed" ? "success" : task.status === "running" ? "warning" : task.status === "failed" ? "error" : task.status === "blocked" ? "warning" : task.status === "cancelled" ? "dim" : "accent";
+		const marker = chosen ? theme.fg("accent", "›") : " ";
+		const persona = theme.fg("muted", task.agent || "worker");
+		const left = `${marker} ${theme.fg(color, circle)} ${persona}  ${task.name}  ${theme.fg("dim", task.status)}`;
+		const duration = formatFleetDuration(task, options.now);
+		const tokens = task.status === "queued" || task.status === "starting" ? undefined : options.metrics?.get(task.index)?.tokens;
+		const right = [duration, tokens === undefined ? undefined : formatFleetTokens(tokens)].filter(Boolean).join("  ");
+		return { left, right: theme.fg("dim", right) };
+	});
+	const maxLeft = Math.max(0, ...rows.map(({ left }) => visibleWidth(left)));
+	const maxRight = Math.max(0, ...rows.map(({ right }) => visibleWidth(right)));
+	const contentWidth = Math.min(width, maxLeft + (maxRight ? 2 + maxRight : 0));
+	for (const row of rows) lines.push(fitColumns(row.left, row.right, contentWidth));
+	return lines;
 }

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

@@ -8,7 +8,7 @@ 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 { applyReport, applyTaskStatus, isActiveStatus, projectTaskActivity, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
 import { continuationSystemPrompt } from "./protocol.ts";
 import { isAbortError } from "./errors.ts";
 import { findRunDirectory } from "./run-locator.ts";
@@ -96,9 +96,10 @@ export async function cleanSubagentRun(cwd: string, runId: string): Promise<bool
 	return true;
 }
 
-export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; stalledWarningSeconds?: number; onStalled?: (message: string) => void; }
+export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?: AbortSignal; owner?: OwnerIdentity; onCleanupError?: (message: string) => void; stalledWarningSeconds?: number; onStalled?: (message: string) => void; onUpdate?: (result: ResumeHistoricalTaskResult) => void; }
+export interface ResumeHistoricalTaskResult { runId: string; label: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string; activity: TaskActivity[]; }
 
-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 }> {
+export async function resumeHistoricalTask(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions = {}): Promise<ResumeHistoricalTaskResult> {
 	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");
@@ -111,7 +112,7 @@ export async function resumeHistoricalTask(cwd: string, runId: string, taskNumbe
 	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 }> {
+async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions): Promise<ResumeHistoricalTaskResult> {
 	const herdr = options.herdr ?? new CliHerdrAutomation();
 	const { signal, onCleanupError } = options;
 	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
@@ -158,6 +159,8 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 				writeJsonAtomic(turnFile, { attempt, prompt, status: "running", sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, startedAt: new Date().toISOString() }),
 				writeJsonAtomic(activeRunFile, activeRunRecord),
 			]);
+			const runningActivity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
+			options.onUpdate?.({ runId, label: run.label, status: "running", summary: `${historical.name} is continuing.`, documents: [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity: runningActivity });
 			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) {
@@ -182,7 +185,8 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		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 };
+		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
+		return { runId, label: run.label, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity };
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		const completedAt = new Date().toISOString();
@@ -204,6 +208,8 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 			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),
 		]);
+		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
+		options.onUpdate?.({ runId, label: run.label, status, summary: report.summary, documents: report.documents, tabId: tab?.tabId ?? "", paneId: tab?.paneId ?? "", sessionFile: historical.sessionFile, activity });
 		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/parameters.ts

@@ -16,8 +16,8 @@ export const HerdrSubagentsParams = Type.Object({
 }, { additionalProperties: false });
 
 export const HerdrSubagentsControlParams = Type.Object({
-	action: StringEnum(["list", "respond", "history", "resume", "cleanup"] as const, { description: "Control operation to perform." }),
-	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, or cleanup." })),
+	action: StringEnum(["list", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, cancel, 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: "Follow-up prompt used by resume." })),

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

@@ -23,7 +23,7 @@ async function closeRunTab(run: RunRecord, runFile: string, herdr: HerdrAutomati
 	}
 }
 
-export interface CancelActiveRunsOptions { reason?: string; owner?: OwnerIdentity; }
+export interface CancelActiveRunsOptions { reason?: string; owner?: OwnerIdentity; runId?: string; }
 
 export async function cancelActiveSubagentRuns(cwd: string, herdr: HerdrAutomation, options: CancelActiveRunsOptions = {}): Promise<CancellationResult> {
 	const reason = options.reason ?? "Parent Pi session closed.";
@@ -39,6 +39,7 @@ export async function cancelActiveSubagentRuns(cwd: string, herdr: HerdrAutomati
 			result.cleanupErrors.push(`Could not inspect Subagent run ${runFile}: ${error instanceof Error ? error.message : String(error)}`);
 			continue;
 		}
+		if (options.runId && run.id !== options.runId) continue;
 		if (!isActiveStatus(run.status)) continue;
 		if (options.owner?.sessionId && run.ownerSessionId !== options.owner.sessionId) continue;
 		const now = new Date().toISOString();

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

@@ -64,6 +64,8 @@ export interface TaskRecord {
 	systemPrompt?: string;
 	sessionFile?: string;
 	startedAt?: string;
+	activeStartedAt?: string;
+	elapsedMs?: number;
 	updatedAt?: string;
 	completedAt?: string;
 	tabId?: string;
@@ -76,6 +78,38 @@ export interface TaskRecord {
 	error?: string;
 }
 
+export interface TaskActivity {
+	index: number;
+	name: string;
+	status: TaskStatus;
+	agent: string;
+	prompt?: string;
+	paneId?: string;
+	sessionFile?: string;
+	startedAt?: string;
+	activeStartedAt?: string;
+	elapsedMs?: number;
+	completedAt?: string;
+	updatedAt?: string;
+}
+
+export function projectTaskActivity(task: TaskRecord, index = task.order - 1): TaskActivity {
+	return {
+		index,
+		name: String(task.name ?? task.agent ?? `Task ${index + 1}`),
+		status: task.status,
+		agent: String(task.agent ?? "worker"),
+		...(task.prompt ? { prompt: task.prompt } : {}),
+		...(task.paneId ? { paneId: task.paneId } : {}),
+		...(task.sessionFile ? { sessionFile: task.sessionFile } : {}),
+		...(task.startedAt ? { startedAt: task.startedAt } : {}),
+		...(task.activeStartedAt ? { activeStartedAt: task.activeStartedAt } : {}),
+		...(typeof task.elapsedMs === "number" ? { elapsedMs: task.elapsedMs } : {}),
+		...(task.completedAt ? { completedAt: task.completedAt } : {}),
+		...(task.updatedAt ? { updatedAt: task.updatedAt } : {}),
+	};
+}
+
 export interface TurnRecord {
 	attempt: number;
 	prompt?: string;
@@ -184,7 +218,25 @@ export function applyLifecycleStatus<T extends { status: string; question?: stri
 }
 
 export function applyTaskStatus<T extends TaskRecord | TurnRecord>(record: T, status: TaskStatus, options: { question?: string; error?: string; at?: string } = {}): T {
-	return applyLifecycleStatus(record, status, options);
+	const at = options.at ?? new Date().toISOString();
+	if ("order" in record) {
+		if (record.status === "running" && status !== "running") {
+			const activeStarted = Date.parse(record.activeStartedAt ?? record.startedAt ?? "");
+			const ended = Date.parse(at);
+			if (Number.isFinite(activeStarted) && Number.isFinite(ended) && ended >= activeStarted) record.elapsedMs = Math.max(0, Number(record.elapsedMs ?? 0)) + (ended - activeStarted);
+			delete record.activeStartedAt;
+		} else if (status === "running" && record.status !== "running") {
+			if (!(typeof record.elapsedMs === "number" && Number.isFinite(record.elapsedMs))) {
+				const frozenAt = record.status === "blocked" ? record.updatedAt : isSettledRunStatus(record.status) ? record.completedAt : undefined;
+				const started = Date.parse(record.startedAt ?? "");
+				const ended = Date.parse(frozenAt ?? "");
+				if (Number.isFinite(started) && Number.isFinite(ended) && ended >= started) record.elapsedMs = ended - started;
+			}
+			record.startedAt ??= at;
+			record.activeStartedAt = at;
+		}
+	}
+	return applyLifecycleStatus(record, status, { ...options, at });
 }
 
 export async function settleAttemptFailure<T extends TaskRecord | TurnRecord>(

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

@@ -2,6 +2,11 @@ import type { HerdrAutomation } from "./herdr.ts";
 import { readRunRecord, type RunRecord } from "./records.ts";
 import { writeJsonAtomic } from "./state.ts";
 
+function isMissingTabError(error: unknown): boolean {
+	const detail = error instanceof Error ? `${error.message}\n${(error as { stderr?: unknown }).stderr ?? ""}` : String(error);
+	return /tab[_ -]?not[_ -]?found|unknown tab/i.test(detail);
+}
+
 export async function cleanupRunTab(options: {
 	herdr: HerdrAutomation;
 	tabId: string;
@@ -52,17 +57,28 @@ export async function cleanupRunTab(options: {
 				.then(() => options.herdr.closeTab(options.tabId, options.signal))
 				.then(() => finishClosed(true))
 				.catch(async (error) => {
+					if (isMissingTabError(error)) { await finishClosed(true); return; }
 					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); }
+					} catch (closeError) {
+						if (isMissingTabError(closeError)) { await finishClosed(true); return; }
+						await reportFailure(closeError, true);
+					}
 				});
 			return { deferred: true };
 		}
 		await options.herdr.closeTab(options.tabId, options.signal);
 		await finishClosed();
 	}
-	catch (error) { await reportFailure(error); throw error; }
+	catch (error) {
+		if (isMissingTabError(error)) {
+			await finishClosed();
+			return { deferred: false };
+		}
+		await reportFailure(error);
+		throw error;
+	}
 	return { deferred: false };
 }

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

@@ -1,4 +1,4 @@
-import type { HerdrAutomation } from "./herdr.ts";
+import { CliHerdrAutomation, 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";
@@ -6,6 +6,8 @@ import { respondToBlockedTask } from "./blocking.ts";
 import { cleanSubagentRun, historyText, listSubagentHistory, resumeHistoricalTask } from "./history.ts";
 import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./validation.ts";
 import type { OwnerIdentity } from "./ownership.ts";
+import { cancelActiveSubagentRuns } from "./reconcile.ts";
+import { cancelQueuedRuns, loadQueuedRuns } from "./queued-runs.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
 
@@ -17,7 +19,7 @@ export interface HerdrSubagentsRunParams {
 }
 
 export interface HerdrSubagentsControlToolParams {
-	action: "list" | "respond" | "history" | "resume" | "cleanup";
+	action: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	runId?: string;
 	answer?: string;
 	task?: number;
@@ -26,7 +28,7 @@ export interface HerdrSubagentsControlToolParams {
 
 /** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
-	action?: "list" | "respond" | "history" | "resume" | "cleanup";
+	action?: "list" | "respond" | "history" | "resume" | "cancel" | "cleanup";
 	prompt?: string;
 	agent?: string;
 	label?: string;
@@ -51,6 +53,7 @@ export interface HerdrSubagentsToolDependencies {
 	configurationPaths?: ConfigurationPaths;
 	owner?: OwnerIdentity;
 	runId?: string;
+	cancelRun?: (runId: string) => Promise<{ cancelled: boolean; queued?: boolean; cleanupErrors?: string[] }>;
 }
 
 export type HerdrSubagentsDetails = HerdrSubagentsResult & {
@@ -125,10 +128,34 @@ const actionHandlers = {
 			return errorResponse(text, { action: "cleanup", runId: params.runId, cleaned: false });
 		}
 	},
+	async cancel({ params, ctx, dependencies }: ToolExecutionContext) {
+		const runId = (params.runId as string).trim();
+		try {
+			let result: { cancelled: boolean; queued?: boolean; cleanupErrors?: string[] };
+			if (dependencies.cancelRun) result = await dependencies.cancelRun(runId);
+			else {
+				const reason = "Subagent run cancelled by user.";
+				const queued = (await loadQueuedRuns(ctx.cwd)).some((run) => run.runId === runId);
+				if (queued) {
+					await cancelQueuedRuns(ctx.cwd, [runId], { reason, owner: dependencies.owner });
+					result = { cancelled: true, queued: true };
+				} else {
+					const cancellation = await cancelActiveSubagentRuns(ctx.cwd, dependencies.herdr ?? new CliHerdrAutomation(), { reason, owner: dependencies.owner, runId });
+					result = { cancelled: cancellation.cancelledRuns > 0, cleanupErrors: cancellation.cleanupErrors };
+				}
+			}
+			const suffix = result.cleanupErrors?.length ? ` Cleanup warnings: ${result.cleanupErrors.join("; ")}` : "";
+			const text = result.cancelled ? `Cancelled Subagent run ${runId}.${suffix}` : `Subagent run '${runId}' is not active or queued.`;
+			return { content: [{ type: "text", text }], details: { action: "cancel", runId, ...result }, ...(result.cancelled ? {} : { isError: true }) };
+		} catch (error) {
+			return errorResponse(error instanceof Error ? error.message : String(error), { action: "cancel", runId, cancelled: 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,
+				onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: partial }),
 				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 } }),
 			});

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

@@ -3,6 +3,7 @@ import type { HerdrSubagentsControlToolParams, HerdrSubagentsRunParams } from ".
 export const HERDR_ACTIONS = {
 	list: { allowed: ["action"], includeRunId: false },
 	history: { allowed: ["action"], includeRunId: false },
+	cancel: { allowed: ["action", "runId"], includeRunId: true },
 	cleanup: { allowed: ["action", "runId"], includeRunId: true },
 	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
 	resume: { allowed: ["action", "runId", "task", "prompt"], includeRunId: true },
@@ -18,7 +19,7 @@ export function validateControlParams(params: HerdrSubagentsControlToolParams):
 	if (!allowed) return "Provide a valid control action.";
 	const extra = Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsControlToolParams));
 	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 === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
 	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;

package/packages/herdr-subagents/tests/extension-contract.ts

@@ -103,9 +103,23 @@ async function verifyPublicUiWiring() {
 		await background.tool.execute("second", { background: true, tasks: [{ name: "queued task", prompt: "two" }] }, undefined, undefined, { cwd, ui: background.ui });
 		if (background.widgetCalls !== activeWidgetCalls || !background.renderedLines.some((line) => line.includes("active task"))) throw new Error("queued background run replaced the active Fleet widget");
 		releaseFirst?.({ content: [{ type: "text", text: "done" }], details: { ...runningDetails, status: "completed" } });
-		await new Promise((resolve) => setTimeout(resolve, 10));
+			await new Promise((resolve) => setTimeout(resolve, 10));
+
+			let cancelledSignal: AbortSignal | undefined;
+			const cancellable = harness(async (params, signal, _onUpdate, _ctx, dependencies) => {
+				if (params.action === "cancel") {
+					const result = await dependencies.cancelRun(params.runId);
+					return { content: [{ type: "text", text: "cancelled" }], details: { action: "cancel", runId: params.runId, ...result } };
+				}
+				cancelledSignal = signal;
+				return await new Promise((_resolve, reject) => signal.addEventListener("abort", () => reject(signal.reason), { once: true }));
+			});
+			await startHarness(cancellable, cwd);
+			const cancellableRun = await cancellable.tool?.execute("cancellable", { background: true, tasks: [{ name: "cancel me", prompt: "wait" }] }, undefined, undefined, { cwd, ui: cancellable.ui });
+			const cancelled = await cancellable.controlTool?.execute("cancel", { action: "cancel", runId: cancellableRun.details.runId }, undefined, undefined, { cwd, ui: cancellable.ui });
+			if (!cancelledSignal?.aborted || cancelled?.details?.cancelled !== true) throw new Error("cancel control did not abort the selected live background run");
 
-		const rejectedCwd = join(cwd, "rejected-background");
+			const rejectedCwd = join(cwd, "rejected-background");
 		mkdirSync(rejectedCwd, { recursive: true });
 		const rejectedBackground = harness(async () => ({ content: [{ type: "text", text: "Unknown persona" }], details: { errorMessage: "Unknown persona" }, isError: true }));
 		await startHarness(rejectedBackground, rejectedCwd);