@ryan_nookpi/pi-extension-subagent 0.3.4 → 0.4.0

package/cli.ts

@@ -53,8 +53,9 @@ export const SUBAGENT_CLI_HELP_TEXT = [
 	"    subagent help",
 	"    subagent agents",
 	"    subagent runs",
-	"    subagent status <runId>",
-	"    subagent detail <runId>",
+	"    subagent status <runId|groupId>",
+	"    subagent detail <runId|groupId>",
+	"      (groupId = the b_.../p_... id returned by batch/chain launches; finished groups are retained briefly)",
 	"",
 	"  Execution:",
 	"    subagent run <agent> [--main|--isolated] -- <task>",
@@ -167,6 +168,11 @@ function parseInteger(raw: string): number | null {
 	return Number.isInteger(value) ? value : null;
 }
 
+/** Group IDs returned by batch (`b_...`) and chain (`p_...`) launches. */
+function isGroupId(raw: string): boolean {
+	return /^[bp]_/.test(raw);
+}
+
 function parseRunTarget(
 	raw: string,
 	knownRunIds: number[] | undefined,
@@ -462,33 +468,35 @@ export function parseSubagentToolCommand(
 			return { type: "params", params: { asyncAction: "list" } };
 
 		case "status": {
-			const runIdRaw = args[0];
-			if (!runIdRaw)
+			const idRaw = args[0];
+			if (!idRaw)
 				return {
 					type: "error",
-					message: `❌ status requires <runId>\n\n✓ Example: subagent status 22\n\nSee all runs with: subagent runs`,
+					message: `❌ status requires <runId|groupId>\n\n✓ Example: subagent status 22\n✓ Example: subagent status b_1712... (batch/chain)\n\nSee all runs with: subagent runs`,
 				};
-			const runId = parseInteger(runIdRaw);
+			if (isGroupId(idRaw)) return { type: "params", params: { asyncAction: "status", groupId: idRaw } };
+			const runId = parseInteger(idRaw);
 			if (runId === null)
 				return {
 					type: "error",
-					message: `❌ Invalid runId: "${runIdRaw}"\n\nThe runId must be a number. See all runs with: subagent runs`,
+					message: `❌ Invalid id: "${idRaw}"\n\nUse a numeric runId or a batch/chain groupId (b_.../p_...). See all runs with: subagent runs`,
 				};
 			return { type: "params", params: { asyncAction: "status", runId } };
 		}
 
 		case "detail": {
-			const runIdRaw = args[0];
-			if (!runIdRaw)
+			const idRaw = args[0];
+			if (!idRaw)
 				return {
 					type: "error",
-					message: `❌ detail requires <runId>\n\n✓ Example: subagent detail 22\n\nSee all runs with: subagent runs`,
+					message: `❌ detail requires <runId|groupId>\n\n✓ Example: subagent detail 22\n✓ Example: subagent detail b_1712... (batch/chain)\n\nSee all runs with: subagent runs`,
 				};
-			const runId = parseInteger(runIdRaw);
+			if (isGroupId(idRaw)) return { type: "params", params: { asyncAction: "detail", groupId: idRaw } };
+			const runId = parseInteger(idRaw);
 			if (runId === null)
 				return {
 					type: "error",
-					message: `❌ Invalid runId: "${runIdRaw}"\n\nThe runId must be a number. See all runs with: subagent runs`,
+					message: `❌ Invalid id: "${idRaw}"\n\nUse a numeric runId or a batch/chain groupId (b_.../p_...). See all runs with: subagent runs`,
 				};
 			return { type: "params", params: { asyncAction: "detail", runId } };
 		}

package/commands.ts

@@ -51,7 +51,7 @@ import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session
 import { SUBAGENT_COMMANDS, type SubagentCommandName } from "./registration-manifest.js";
 import { readSessionReplayItems, SubagentSessionReplayOverlay } from "./replay.js";
 import { invokeWithAutoRetry, MAX_SUBAGENT_AUTO_RETRIES } from "./retry.js";
-import { getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
+import { evictStaleFinishedGroups, getLatestRun, removeRun, trimCommandRunHistory } from "./run-utils.js";
 import {
 	getFinalOutput,
 	getLastNonEmptyLine,
@@ -824,6 +824,7 @@ function restoreRunsFromSession(store: SubagentStore, ctx: any, pi?: ExtensionAP
 	}
 
 	evictStalePendingGroupCompletions(STALE_PENDING_COMPLETION_MS);
+	evictStaleFinishedGroups(store);
 
 	// Fallback: if this session has no subagent markers at all, but we recently
 	// had in-memory runs for the same session file, reuse that snapshot so

package/constants.ts

@@ -30,6 +30,12 @@ export const SUBAGENT_STRONG_WAIT_MESSAGE =
 /** Maximum age (ms) for pending cross-session completions before eviction. */
 export const STALE_PENDING_COMPLETION_MS = 30 * 60 * 1_000;
 
+/** Max number of finished batch/chain group snapshots retained for `status`/`detail` queries. */
+export const MAX_FINISHED_GROUPS = 20;
+
+/** Max age (ms) a finished group snapshot is retained before eviction. */
+export const FINISHED_GROUP_TTL_MS = 30 * 60 * 1_000;
+
 /** Short label shown in the widget when inside a child session. */
 export const PARENT_HINT = "↩ parent (><)";
 

package/lifecycle.ts

@@ -114,6 +114,7 @@ export function shutdownSubagentRuns(store: SubagentStore, pi: ExtensionAPI, rea
 	store.globalLiveRuns.clear();
 	store.batchGroups.clear();
 	store.pipelines.clear();
+	store.finishedGroups.clear();
 	store.recentLaunchTimestamps.clear();
 	store.commandRuns.clear();
 	store.commandWidgetCtx = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryan_nookpi/pi-extension-subagent",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "Asynchronous subagent delegation for pi with run, batch, chain, and continuation workflows.",
   "license": "MIT",
   "repository": {

package/run-utils.ts

@@ -7,8 +7,15 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { FINISHED_GROUP_TTL_MS, MAX_FINISHED_GROUPS, STATUS_OUTPUT_PREVIEW_MAX_CHARS } from "./constants.js";
 import type { SubagentStore } from "./store.js";
-import type { CommandRunState } from "./types.js";
+import type {
+	BatchGroupState,
+	CommandRunState,
+	FinishedGroupMember,
+	FinishedGroupSnapshot,
+	PipelineState,
+} from "./types.js";
 import { updateCommandRunsWidget, type WidgetRenderCtx } from "./widget.js";
 
 export interface RemoveRunOptions {
@@ -201,3 +208,115 @@ export function trimCommandRunHistory(
 
 	return removedRunIds;
 }
+
+// ── Finished-group retention ────────────────────────────────────────────────
+// Batch/chain groups are deleted from the live store once their completion is
+// delivered. To keep `subagent status/detail <groupId>` working for a short
+// window afterward, we retain an immutable snapshot per finished group.
+
+function memberOutput(run: CommandRunState, fallback?: string): string {
+	return run.lastOutput?.trim() || run.lastLine?.trim() || fallback?.trim() || "(no output)";
+}
+
+/** Build a finished-group snapshot from a completed batch group. */
+export function snapshotBatchGroup(
+	store: SubagentStore,
+	batch: BatchGroupState,
+	terminalStatus: FinishedGroupSnapshot["terminalStatus"],
+): FinishedGroupSnapshot {
+	let failed = 0;
+	const members: FinishedGroupMember[] = batch.runIds.map((runId) => {
+		const run = store.commandRuns.get(runId);
+		if (!run) {
+			if (batch.failedRunIds.has(runId)) failed++;
+			return {
+				summaryLine: `#${runId} [gone] (run no longer available)`,
+				output: batch.pendingResults.get(runId)?.trim() || "(no output)",
+			};
+		}
+		if (run.status === "error" || batch.failedRunIds.has(runId)) failed++;
+		return { summaryLine: formatCommandRunSummary(run), output: memberOutput(run, batch.pendingResults.get(runId)) };
+	});
+	return {
+		groupId: batch.batchId,
+		kind: "batch",
+		terminalStatus,
+		finishedAt: Date.now(),
+		total: batch.runIds.length,
+		failed,
+		members,
+	};
+}
+
+/** Build a finished-group snapshot from a completed pipeline. */
+export function snapshotPipeline(
+	pipeline: PipelineState,
+	terminalStatus: FinishedGroupSnapshot["terminalStatus"],
+): FinishedGroupSnapshot {
+	const members: FinishedGroupMember[] = pipeline.stepResults.map((step, index) => ({
+		summaryLine: `Step ${index + 1} · #${step.runId} ${step.agent} · ${step.status}`,
+		output: step.output?.trim() || "(no output)",
+		task: step.task,
+	}));
+	return {
+		groupId: pipeline.pipelineId,
+		kind: "chain",
+		terminalStatus,
+		finishedAt: Date.now(),
+		total: pipeline.stepResults.length,
+		failed: pipeline.stepResults.filter((step) => step.status === "error").length,
+		members,
+	};
+}
+
+/** Retain a finished-group snapshot, evicting the oldest entries past the cap. */
+export function retireFinishedGroup(store: SubagentStore, snapshot: FinishedGroupSnapshot): void {
+	// Re-insert to refresh insertion order (most-recent last).
+	store.finishedGroups.delete(snapshot.groupId);
+	store.finishedGroups.set(snapshot.groupId, snapshot);
+	while (store.finishedGroups.size > MAX_FINISHED_GROUPS) {
+		const oldest = store.finishedGroups.keys().next().value;
+		if (oldest === undefined) break;
+		store.finishedGroups.delete(oldest);
+	}
+}
+
+/** Evict finished-group snapshots older than the retention TTL. Returns count removed. */
+export function evictStaleFinishedGroups(store: SubagentStore, now = Date.now()): number {
+	let removed = 0;
+	for (const [groupId, snapshot] of store.finishedGroups) {
+		if (now - snapshot.finishedAt > FINISHED_GROUP_TTL_MS) {
+			store.finishedGroups.delete(groupId);
+			removed++;
+		}
+	}
+	return removed;
+}
+
+function formatFinishedAge(finishedAt: number, now = Date.now()): string {
+	const seconds = Math.max(0, Math.round((now - finishedAt) / 1000));
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.round(seconds / 60);
+	return `${minutes}m ago`;
+}
+
+/** Render a retained finished-group snapshot for `status` (summary) or `detail` (with output). */
+export function formatFinishedGroupStatus(snapshot: FinishedGroupSnapshot, detailed: boolean): string {
+	const label = snapshot.kind === "batch" ? "subagent-batch" : "subagent-chain";
+	const failedSuffix = snapshot.failed > 0 ? `, ${snapshot.failed} failed` : "";
+	const header = `[${label}#${snapshot.groupId}] ${snapshot.terminalStatus} · ${snapshot.total} ${
+		snapshot.kind === "batch" ? "runs" : "steps"
+	}${failedSuffix} · finished ${formatFinishedAge(snapshot.finishedAt)}`;
+	const body = snapshot.members
+		.map((member) => {
+			if (!detailed) return member.summaryLine;
+			const output =
+				member.output.length > STATUS_OUTPUT_PREVIEW_MAX_CHARS
+					? `${member.output.slice(0, STATUS_OUTPUT_PREVIEW_MAX_CHARS)}\n\n... [truncated]`
+					: member.output;
+			const taskLine = member.task ? `Task: ${member.task}\n` : "";
+			return `${member.summaryLine}\n${taskLine}${output}`;
+		})
+		.join(detailed ? "\n\n" : "\n");
+	return `${header}\n\n${body}`;
+}

package/store.ts

@@ -5,7 +5,14 @@
 import type { Message } from "@earendil-works/pi-ai";
 import { visibleWidth } from "@earendil-works/pi-tui";
 import { getDisplayItems, getFinalOutput, getLastNonEmptyLine, getLatestActivityPreview } from "./runner.js";
-import type { BatchGroupState, CommandRunState, GlobalRunEntry, PipelineState, SingleResult } from "./types.js";
+import type {
+	BatchGroupState,
+	CommandRunState,
+	FinishedGroupSnapshot,
+	GlobalRunEntry,
+	PipelineState,
+	SingleResult,
+} from "./types.js";
 import type { WidgetRenderCtx } from "./widget.js";
 
 export const COLLAPSED_ITEM_COUNT = 10;
@@ -40,6 +47,8 @@ export interface SubagentStore {
 	batchGroups: Map<string, BatchGroupState>;
 	/** In-memory sequential pipelines launched via the tool. */
 	pipelines: Map<string, PipelineState>;
+	/** Retained snapshots of finished batch/chain groups, keyed by groupId (insertion-ordered). */
+	finishedGroups: Map<string, FinishedGroupSnapshot>;
 }
 
 export function createStore(): SubagentStore {
@@ -59,6 +68,7 @@ export function createStore(): SubagentStore {
 		recentLaunchTimestamps: new Map(),
 		batchGroups: new Map(),
 		pipelines: new Map(),
+		finishedGroups: new Map(),
 	};
 }
 

package/tool-execute.ts

@@ -41,7 +41,17 @@ import {
 import { clearPendingGroupCompletion, upsertPendingGroupCompletion } from "./group-pending.js";
 import { enqueueSubagentInvocation } from "./invocation-queue.js";
 import { appendDisplayTaskUpdate, getSessionFileSize } from "./persisted-session.js";
-import { clearFinishedRuns, formatCommandRunSummary, removeRun, trimCommandRunHistory } from "./run-utils.js";
+import {
+	clearFinishedRuns,
+	evictStaleFinishedGroups,
+	formatCommandRunSummary,
+	formatFinishedGroupStatus,
+	removeRun,
+	retireFinishedGroup,
+	snapshotBatchGroup,
+	snapshotPipeline,
+	trimCommandRunHistory,
+} from "./run-utils.js";
 import { getFinalOutput, getLastNonEmptyLine, runSingleAgent } from "./runner.js";
 import {
 	buildMainContextText,
@@ -54,10 +64,12 @@ import {
 import { formatStarterPackNotice, offerStarterPackIfEmpty } from "./starter-pack.js";
 import { type SubagentStore, updateRunFromResult } from "./store.js";
 import type {
+	BatchGroupState,
 	BatchOrChainItem,
 	CommandRunState,
 	OnUpdateCallback,
 	PendingCompletion,
+	PipelineState,
 	PipelineStepResult,
 	SingleResult,
 	SubagentDetails,
@@ -583,6 +595,47 @@ function formatPipelineSummary(
 	return `[subagent-chain#${pipelineId}] ${terminalStatus}\n\n${steps}`;
 }
 
+function previewOutput(output: string): string {
+	const trimmed = output.trim() || "(no output yet)";
+	return trimmed.length > STATUS_OUTPUT_PREVIEW_MAX_CHARS
+		? `${trimmed.slice(0, STATUS_OUTPUT_PREVIEW_MAX_CHARS)}\n\n... [truncated]`
+		: trimmed;
+}
+
+function formatBatchGroupStatus(store: SubagentStore, batch: BatchGroupState, detailed: boolean): string {
+	const total = batch.runIds.length;
+	const done = batch.completedRunIds.size;
+	const failed = batch.failedRunIds.size;
+	const header = `[subagent-batch#${batch.batchId}] running · ${done}/${total} finished${
+		failed > 0 ? `, ${failed} failed` : ""
+	}`;
+	const body = batch.runIds
+		.map((runId) => {
+			const run = store.commandRuns.get(runId);
+			if (!run) return `#${runId} (unavailable)`;
+			const summary = formatCommandRunSummary(run);
+			if (!detailed) return summary;
+			return `${summary}\n${previewOutput(run.lastOutput ?? run.lastLine ?? "")}`;
+		})
+		.join(detailed ? "\n\n" : "\n");
+	return `${header}\n\n${body}`;
+}
+
+function formatPipelineGroupStatus(store: SubagentStore, pipeline: PipelineState, detailed: boolean): string {
+	const finishedCount = pipeline.stepResults.length;
+	const header = `[subagent-chain#${pipeline.pipelineId}] running · step ${pipeline.currentIndex + 1} (${finishedCount} finished)`;
+	const parts = pipeline.stepResults.map((step, index) => {
+		const line = `Step ${index + 1} · #${step.runId} ${step.agent} · ${step.status}`;
+		return detailed ? `${line}\nTask: ${step.task}\n${previewOutput(step.output)}` : line;
+	});
+	const runningRunId = pipeline.stepRunIds[finishedCount];
+	if (runningRunId !== undefined) {
+		const run = store.commandRuns.get(runningRunId);
+		if (run) parts.push(`Step ${finishedCount + 1} · ${formatCommandRunSummary(run)}`);
+	}
+	return `${header}\n\n${parts.join(detailed ? "\n\n" : "\n")}`;
+}
+
 function toLaunchSummary(
 	runState: Pick<CommandRunState, "agent" | "id" | "batchId" | "pipelineId" | "pipelineStepIndex">,
 	mode: SubagentLaunchSummary["mode"],
@@ -842,6 +895,43 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 			};
 		}
 
+		if ((asyncAction === "status" || asyncAction === "detail") && typeof cmdParams.groupId === "string") {
+			evictStaleFinishedGroups(store);
+			const groupId = cmdParams.groupId;
+			const detailed = asyncAction === "detail";
+			const finished = store.finishedGroups.get(groupId);
+			if (finished) {
+				return {
+					content: [{ type: "text", text: withIdleRunWarning(formatFinishedGroupStatus(finished, detailed)) }],
+					details: makeDetails("single"),
+				};
+			}
+			const batch = store.batchGroups.get(groupId);
+			if (batch) {
+				return {
+					content: [{ type: "text", text: withIdleRunWarning(formatBatchGroupStatus(store, batch, detailed)) }],
+					details: makeDetails("single"),
+				};
+			}
+			const pipeline = store.pipelines.get(groupId);
+			if (pipeline) {
+				return {
+					content: [{ type: "text", text: withIdleRunWarning(formatPipelineGroupStatus(store, pipeline, detailed)) }],
+					details: makeDetails("single"),
+				};
+			}
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Unknown subagent group "${groupId}". Finished groups are retained only briefly; use \`subagent runs\` to inspect individual runs.`,
+					},
+				],
+				details: makeDetails("single"),
+				isError: true,
+			};
+		}
+
 		const rawRunIds = Array.isArray(cmdParams.runIds) ? cmdParams.runIds : undefined;
 		const invalidRunIds = (rawRunIds ?? []).filter((value) => !Number.isInteger(value));
 		if (invalidRunIds.length > 0) {
@@ -1471,6 +1561,9 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 				const orderedRuns = runStates.map(({ runState }) => runState);
 				const hasError = finalizedRuns.some((finalized) => finalized.isError);
 				const content = formatBatchSummary(batchId, orderedRuns, hasError ? "error" : "completed");
+				const batchForSnapshot = store.batchGroups.get(batchId);
+				if (batchForSnapshot)
+					retireFinishedGroup(store, snapshotBatchGroup(store, batchForSnapshot, hasError ? "error" : "completed"));
 				for (const { runState } of runStates) cleanupRunAfterFinalDelivery(runState.id);
 				clearPendingGroupCompletion("batch", batchId);
 				store.batchGroups.delete(batchId);
@@ -1525,6 +1618,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 									runSummaries: orderedRuns.map((run) => buildRunAnalyticsSummary(run)),
 								},
 							};
+							retireFinishedGroup(store, snapshotBatchGroup(store, batch, batchTerminalStatus));
 							if (isInOriginSession(ctx, batch.originSessionFile)) {
 								pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 								clearPendingGroupCompletion("batch", batchId);
@@ -1579,6 +1673,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 									runSummaries: orderedRuns.map((run) => buildRunAnalyticsSummary(run)),
 								},
 							};
+							retireFinishedGroup(store, snapshotBatchGroup(store, batch, "error"));
 							if (isInOriginSession(ctx, batch.originSessionFile)) {
 								pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 								clearPendingGroupCompletion("batch", batchId);
@@ -1754,6 +1849,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 				const hasError = pipeline.stepResults.some((step) => step.status === "error");
 				if (terminalStatus === "completed" && hasError) terminalStatus = "error";
 				const content = formatPipelineSummary(pipelineId, pipeline.stepResults, terminalStatus);
+				retireFinishedGroup(store, snapshotPipeline(pipeline, terminalStatus));
 				for (const runId of pipeline.stepRunIds) cleanupRunAfterFinalDelivery(runId);
 				clearPendingGroupCompletion("chain", pipelineId);
 				store.pipelines.delete(pipelineId);
@@ -1892,6 +1988,7 @@ export function createSubagentToolExecute(pi: ExtensionAPI, store: SubagentStore
 								runSummaries: orderedRuns.map((run) => buildRunAnalyticsSummary(run)),
 							},
 						};
+						retireFinishedGroup(store, snapshotPipeline(pipeline, terminalStatus));
 						if (isInOriginSession(ctx, pipeline.originSessionFile)) {
 							pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
 							clearPendingGroupCompletion("chain", pipelineId);

package/types.ts

@@ -183,6 +183,30 @@ export interface PipelineState {
 	pendingCompletion?: PendingCompletion;
 }
 
+/** A single member (batch run or chain step) captured in a finished-group snapshot. */
+export interface FinishedGroupMember {
+	/** Pre-rendered one-line summary, frozen at retirement time. */
+	summaryLine: string;
+	/** Full member output, truncated only when rendered. */
+	output: string;
+	/** Chain step task (omitted for batch runs). */
+	task?: string;
+}
+
+/**
+ * Immutable snapshot of a completed batch/chain group, retained briefly so
+ * `subagent status/detail <groupId>` still works after the live group is gone.
+ */
+export interface FinishedGroupSnapshot {
+	groupId: string;
+	kind: "batch" | "chain";
+	terminalStatus: "completed" | "error" | "stopped";
+	finishedAt: number;
+	total: number;
+	failed: number;
+	members: FinishedGroupMember[];
+}
+
 export const ListAgentsParams = Type.Object({});
 
 export const SubagentParams = Type.Object({