@ferris1225/pi-subagents 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Focused sub-agent delegation for pi: explore / plan / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/index.ts

@@ -16,7 +16,7 @@
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { getConfigPath, loadConfig } from "./config.ts";
@@ -32,12 +32,13 @@ import {
 	isFailedResult,
 	mapWithConcurrencyLimit,
 	runSingleAgent,
-	truncateParallelOutput,
 	type OnUpdateCallback,
 	type SingleResult,
 	type SubagentDetails,
+	type SubagentLiveEvent,
 	type UsageStats,
 } from "./spawn.ts";
+import { monitor, statusColor, statusIcon, statusLabel } from "./monitor.ts";
 
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
@@ -121,6 +122,7 @@ export default function (pi: ExtensionAPI): void {
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
+			monitor.beginTurn();
 			const config = await loadConfig(configPath);
 			const discovery = discoverAgents(ctx.cwd, {
 				scope: config.agentScope,
@@ -186,6 +188,27 @@ export default function (pi: ExtensionAPI): void {
 				};
 
 				const results = await mapWithConcurrencyLimit(params.tasks, MAX_CONCURRENCY, async (t, index) => {
+					const resolvedModel = agents.find((a) => a.name === t.agent)?.model;
+					const runId = monitor.addRun(t.agent, resolvedModel);
+					const onLive = (e: SubagentLiveEvent): void => {
+						switch (e.kind) {
+							case "status":
+								monitor.setStatus(runId, e.status);
+								break;
+							case "usage":
+								monitor.setUsage(runId, e.usage, e.model);
+								break;
+							case "tool_start":
+								monitor.appendTranscript(runId, { kind: "tool", text: `▸ ${e.toolName}(${typeof e.args === "object" ? JSON.stringify(e.args).slice(0, 120) : String(e.args).slice(0, 120)})` });
+								break;
+							case "tool_end":
+								monitor.appendTranscript(runId, { kind: e.isError ? "error" : "status", text: `${e.isError ? "✗" : "✓"} ${e.toolName}` });
+								break;
+							case "text_delta":
+								monitor.appendTextDelta(runId, e.delta);
+								break;
+						}
+					};
 					const perTaskUpdate: OnUpdateCallback | undefined = onUpdate
 						? (partial) => {
 								const current = partial.details?.results[0];
@@ -195,16 +218,23 @@ export default function (pi: ExtensionAPI): void {
 								}
 							}
 						: undefined;
-					const result = await runSingleAgent({
-						defaultCwd: ctx.cwd,
-						agent: agents.find((a) => a.name === t.agent),
-						agentName: t.agent,
-						task: t.task,
-						cwd: t.cwd,
-						signal,
-						onUpdate: perTaskUpdate,
-						makeDetails: makeDetails("parallel"),
-					});
+					let result: SingleResult;
+					try {
+						result = await runSingleAgent({
+							defaultCwd: ctx.cwd,
+							agent: agents.find((a) => a.name === t.agent),
+							agentName: t.agent,
+							task: t.task,
+							cwd: t.cwd,
+							signal,
+							onUpdate: perTaskUpdate,
+							onLive,
+							makeDetails: makeDetails("parallel"),
+						});
+					} catch (err) {
+						monitor.setStatus(runId, "failed");
+						throw err;
+					}
 					allResults[index] = result;
 					emitParallelUpdate();
 					return result;
@@ -212,7 +242,7 @@ export default function (pi: ExtensionAPI): void {
 
 				const successCount = results.filter((r) => !isFailedResult(r)).length;
 				const summaries = results.map((r) => {
-					const output = truncateParallelOutput(getResultOutput(r));
+					const output = getResultOutput(r);
 					const status = isFailedResult(r) ? "failed" : "completed";
 					const usage = formatUsage(r.usage);
 					return `### [${r.agent}] ${status}${usage ? ` (${usage})` : ""}\n\n${output}`;
@@ -229,16 +259,44 @@ export default function (pi: ExtensionAPI): void {
 			}
 
 			// ---- Single mode ----
-			const result = await runSingleAgent({
-				defaultCwd: ctx.cwd,
-				agent: agents.find((a) => a.name === params.agent),
-				agentName: params.agent as string,
-				task: params.task as string,
-				cwd: params.cwd,
-				signal,
-				onUpdate,
-				makeDetails: makeDetails("single"),
-			});
+			const resolvedModel = agents.find((a) => a.name === params.agent)?.model;
+			const runId = monitor.addRun(params.agent as string, resolvedModel);
+			const onLive = (e: SubagentLiveEvent): void => {
+				switch (e.kind) {
+					case "status":
+						monitor.setStatus(runId, e.status);
+						break;
+					case "usage":
+						monitor.setUsage(runId, e.usage, e.model);
+						break;
+					case "tool_start":
+						monitor.appendTranscript(runId, { kind: "tool", text: `▸ ${e.toolName}(${typeof e.args === "object" ? JSON.stringify(e.args).slice(0, 120) : String(e.args).slice(0, 120)})` });
+						break;
+					case "tool_end":
+						monitor.appendTranscript(runId, { kind: e.isError ? "error" : "status", text: `${e.isError ? "✗" : "✓"} ${e.toolName}` });
+						break;
+					case "text_delta":
+						monitor.appendTextDelta(runId, e.delta);
+						break;
+				}
+			};
+			let result: SingleResult;
+			try {
+				result = await runSingleAgent({
+					defaultCwd: ctx.cwd,
+					agent: agents.find((a) => a.name === params.agent),
+					agentName: params.agent as string,
+					task: params.task as string,
+					cwd: params.cwd,
+					signal,
+					onUpdate,
+					onLive,
+					makeDetails: makeDetails("single"),
+				});
+			} catch (err) {
+				monitor.setStatus(runId, "failed");
+				throw err;
+			}
 
 			if (isFailedResult(result)) {
 				return {
@@ -275,13 +333,27 @@ export default function (pi: ExtensionAPI): void {
 		renderResult(result, _options, theme) {
 			const details = result.details as SubagentDetails | undefined;
 			if (!details || details.results.length === 0) return new Text(theme.fg("dim", "(no output)"), 0, 0);
-			const usage = formatUsage(aggregateUsage(details.results));
-			const header =
-				details.mode === "parallel"
-					? `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`
-					: `${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", details.results[0].agent)}`;
-			const suffix = usage ? `  ${theme.fg("dim", usage)}` : "";
-			return new Text(header + suffix, 0, 0);
+
+			if (details.mode === "single") {
+				const r = details.results[0];
+				const icon = statusIcon(isFailedResult(r) ? "failed" : "done", theme);
+				const usage = formatUsage(r.usage);
+				const model = r.model ?? "?";
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${usage ? ` · ${usage}` : ""}`)}`;
+				return new Text(line, 0, 0);
+			}
+
+			// Parallel mode: header + one compact line per agent
+			const lines: string[] = [
+				`${theme.fg("toolTitle", theme.bold("subagent "))}${theme.fg("accent", `parallel (${details.results.length})`)}`,
+			];
+			for (const r of details.results) {
+				const icon = statusIcon(isFailedResult(r) ? "failed" : "done", theme);
+				const usage = formatUsage(r.usage);
+				const model = r.model ?? "?";
+				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${usage ? ` · ${usage}` : ""}`)}`);
+			}
+			return new Text(lines.join("\n"), 0, 0);
 		},
 	});
 
@@ -292,6 +364,44 @@ export default function (pi: ExtensionAPI): void {
 		},
 	});
 
+	// Persistent widget above the editor showing live sub-agent status.
+	pi.on("session_start", (_e, ctx) => {
+		if (ctx.mode !== "tui") return;
+		ctx.ui.setWidget(
+			"pi-subagents",
+			(tui, theme) => {
+				const unsub = monitor.subscribe(() => tui.requestRender());
+				// Tick once a second so elapsed time stays live while runs are active.
+				const timer = setInterval(() => {
+					if (monitor.getRuns().some((r) => r.status === "queued" || r.status === "running")) {
+						tui.requestRender();
+					}
+				}, 1000);
+				return {
+					render(width: number): string[] {
+						const runs = monitor.getRuns();
+						if (runs.length === 0) return [];
+						const lines: string[] = [];
+						for (const r of runs) {
+							const icon = statusIcon(r.status, theme);
+							const label = theme.fg(statusColor(r.status), statusLabel(r.status));
+							lines.push(truncateToWidth(` ${icon} ${monitor.summarize(r)} · ${label}`, width, ""));
+							const activity = monitor.lastActivity(r);
+							if (activity) lines.push(truncateToWidth(theme.fg("dim", `   ${activity}`), width, ""));
+						}
+						return lines;
+					},
+					invalidate() {},
+					dispose() {
+						unsub();
+						clearInterval(timer);
+					},
+				};
+			},
+			{ placement: "aboveEditor" },
+		);
+	});
+
 	// Proactive dispatch: inject the delegation directive into the parent system prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
 		const config = await loadConfig(configPath);

package/src/monitor.ts

@@ -0,0 +1,238 @@
+/**
+ * Sub-agent monitor: a module-level singleton store that tracks subagent runs
+ * for the current turn.
+ *
+ * The store notifies subscribers on every mutation so the persistent widget
+ * above the editor can re-render. Each run carries timing information
+ * (started/ended) and a transcript whose most recent entry is surfaced as the
+ * run's current activity.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { UsageStats } from "./spawn.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type RunStatus = "queued" | "running" | "done" | "failed";
+
+export interface TranscriptLine {
+	kind: "tool" | "text" | "status" | "error";
+	text: string;
+}
+
+export interface RunView {
+	id: number;
+	agent: string;
+	model?: string;
+	status: RunStatus;
+	usage: UsageStats;
+	transcript: TranscriptLine[];
+	/** Epoch ms when the run started executing (set on first "running" status). */
+	startedAt?: number;
+	/** Epoch ms when the run finished (set on "done"/"failed"). */
+	endedAt?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+
+function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
+	return String(count);
+}
+
+export function formatUsageCompact(usage: UsageStats): string {
+	const parts: string[] = [];
+	if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+	if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+	if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+	if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+	return parts.join(" ");
+}
+
+export function formatDuration(ms: number): string {
+	const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+	if (totalSeconds < 60) return `${totalSeconds}s`;
+	const minutes = Math.floor(totalSeconds / 60);
+	const seconds = totalSeconds % 60;
+	if (minutes < 60) return `${minutes}m${String(seconds).padStart(2, "0")}s`;
+	const hours = Math.floor(minutes / 60);
+	return `${hours}h${String(minutes % 60).padStart(2, "0")}m`;
+}
+
+/** Elapsed wall time of a run: live while running, final once finished. */
+export function formatElapsed(run: RunView, now: number = Date.now()): string {
+	if (run.startedAt === undefined) return "";
+	const end = run.endedAt ?? now;
+	return formatDuration(end - run.startedAt);
+}
+
+// ---------------------------------------------------------------------------
+// MonitorStore
+// ---------------------------------------------------------------------------
+
+export class MonitorStore {
+	private runs: RunView[] = [];
+	private nextId = 1;
+	private subscribers = new Set<() => void>();
+
+	beginTurn(): void {
+		// Clear finished runs from a previous turn, but keep any still-active
+		// (queued/running) ones so a concurrent sub-agent call is not wiped.
+		this.runs = this.runs.filter((r) => r.status === "queued" || r.status === "running");
+		this.notify();
+	}
+
+	addRun(agent: string, model?: string): number {
+		const id = this.nextId++;
+		this.runs.push({
+			id,
+			agent,
+			model,
+			status: "queued",
+			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			transcript: [],
+		});
+		this.notify();
+		return id;
+	}
+
+	setStatus(id: number, status: RunStatus): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.status = status;
+		if (status === "running" && run.startedAt === undefined) {
+			run.startedAt = Date.now();
+		} else if ((status === "done" || status === "failed") && run.endedAt === undefined) {
+			run.endedAt = Date.now();
+		}
+		this.notify();
+	}
+	setUsage(id: number, usage: UsageStats, model?: string): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.usage = { ...usage };
+		if (model) run.model = model;
+		this.notify();
+	}
+
+	appendTranscript(id: number, line: TranscriptLine): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.transcript.push(line);
+		this.notify();
+	}
+
+	/** Append streamed assistant text, merging consecutive deltas into coherent
+	 * lines (split only on real newlines) instead of one line per token fragment. */
+	appendTextDelta(id: number, delta: string): void {
+		const run = this.find(id);
+		if (!run || delta.length === 0) return;
+		const segments = delta.split("\n");
+		for (let i = 0; i < segments.length; i++) {
+			const seg = segments[i];
+			const last = run.transcript[run.transcript.length - 1];
+			if (i === 0 && last && last.kind === "text") {
+				last.text += seg;
+			} else {
+				run.transcript.push({ kind: "text", text: seg });
+			}
+		}
+		this.notify();
+	}
+
+	getRuns(): RunView[] {
+		return this.runs;
+	}
+
+	subscribe(cb: () => void): () => void {
+		this.subscribers.add(cb);
+		return () => {
+			this.subscribers.delete(cb);
+		};
+	}
+
+	summarize(run: RunView): string {
+		const usage = formatUsageCompact(run.usage);
+		const parts = [run.agent];
+		if (run.model) parts.push(run.model);
+		if (usage) parts.push(usage);
+		const elapsed = formatElapsed(run);
+		if (elapsed) parts.push(elapsed);
+		return parts.join(" · ");
+	}
+
+	/** Text of the most recent transcript entry (what the run is doing now). */
+	lastActivity(run: RunView): string | undefined {
+		for (let i = run.transcript.length - 1; i >= 0; i--) {
+			const text = run.transcript[i].text.trim();
+			if (text.length > 0) return text;
+		}
+		return undefined;
+	}
+
+	private find(id: number): RunView | undefined {
+		return this.runs.find((r) => r.id === id);
+	}
+
+	private notify(): void {
+		for (const cb of this.subscribers) {
+			try {
+				cb();
+			} catch {
+				/* subscriber errors must not break the store */
+			}
+		}
+	}
+}
+
+export const monitor = new MonitorStore();
+
+// ---------------------------------------------------------------------------
+// Status icons
+// ---------------------------------------------------------------------------
+
+export function statusIcon(status: RunStatus, theme: Theme): string {
+	switch (status) {
+		case "running":
+			return theme.fg("accent", "●");
+		case "done":
+			return theme.fg("success", "✓");
+		case "failed":
+			return theme.fg("error", "✗");
+		default:
+			return theme.fg("dim", "○");
+	}
+}
+
+/** User-facing status label shown in the widget. */
+export function statusLabel(status: RunStatus): string {
+	switch (status) {
+		case "queued":
+			return "ready";
+		case "running":
+			return "running";
+		case "done":
+			return "done";
+		case "failed":
+			return "stopped";
+	}
+}
+
+/** Theme color matching the status label. */
+export function statusColor(status: RunStatus): "accent" | "success" | "error" | "dim" {
+	switch (status) {
+		case "running":
+			return "accent";
+		case "done":
+			return "success";
+		case "failed":
+			return "error";
+		default:
+			return "dim";
+	}
+}

package/src/spawn.ts

@@ -20,7 +20,6 @@ import type { AgentConfig, AgentSource } from "./agents.ts";
 
 export const MAX_PARALLEL_TASKS = 8;
 export const MAX_CONCURRENCY = 4;
-export const PER_TASK_OUTPUT_CAP = 50 * 1024;
 /** Max nesting depth for sub-agent -> sub-agent spawning (recursion guard). */
 export const MAX_SUBAGENT_DEPTH = 2;
 export const DEPTH_ENV_VAR = "PI_SUBAGENT_DEPTH";
@@ -55,6 +54,13 @@ export interface SubagentDetails {
 
 export type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
 
+export type SubagentLiveEvent =
+	| { kind: "status"; status: "queued" | "running" | "done" | "failed" }
+	| { kind: "usage"; usage: UsageStats; model?: string }
+	| { kind: "tool_start"; toolName: string; args: unknown }
+	| { kind: "tool_end"; toolName: string; isError: boolean }
+	| { kind: "text_delta"; delta: string };
+
 function emptyUsage(): UsageStats {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
@@ -82,15 +88,6 @@ export function getResultOutput(result: SingleResult): string {
 	return getFinalOutput(result.messages) || "(no output)";
 }
 
-export function truncateParallelOutput(output: string): string {
-	const byteLength = Buffer.byteLength(output, "utf8");
-	if (byteLength <= PER_TASK_OUTPUT_CAP) return output;
-	let truncated = output.slice(0, PER_TASK_OUTPUT_CAP);
-	while (Buffer.byteLength(truncated, "utf8") > PER_TASK_OUTPUT_CAP) truncated = truncated.slice(0, -1);
-	const omitted = byteLength - Buffer.byteLength(truncated, "utf8");
-	return `${truncated}\n\n[Output truncated: ${omitted} bytes omitted. Full output preserved in tool details.]`;
-}
-
 export async function mapWithConcurrencyLimit<TIn, TOut>(
 	items: TIn[],
 	concurrency: number,
@@ -148,13 +145,14 @@ export interface RunSingleOptions {
 	cwd?: string;
 	signal?: AbortSignal;
 	onUpdate?: OnUpdateCallback;
+	onLive?: (e: SubagentLiveEvent) => void;
 	makeDetails: (results: SingleResult[]) => SubagentDetails;
 	env?: NodeJS.ProcessEnv;
 }
 
 /** Spawn one agent as an isolated pi child process and collect its output. */
 export async function runSingleAgent(options: RunSingleOptions): Promise<SingleResult> {
-	const { agent, agentName, task, cwd, signal, onUpdate, makeDetails } = options;
+	const { agent, agentName, task, cwd, signal, onUpdate, onLive, makeDetails } = options;
 
 	if (!agent) {
 		return {
@@ -230,6 +228,42 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 					return;
 				}
 
+				// Live event: agent started
+				if (event.type === "agent_start" || event.type === "turn_start") {
+					if (onLive) {
+						try {
+							onLive({ kind: "status", status: "running" });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
+				// Live event: streamed assistant text
+				if (event.type === "message_update" && event.assistantMessageEvent?.type === "text_delta") {
+					if (onLive) {
+						try {
+							onLive({ kind: "text_delta", delta: event.assistantMessageEvent.delta ?? "" });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
+				// Live event: tool execution started
+				if (event.type === "tool_execution_start") {
+					if (onLive) {
+						try {
+							onLive({ kind: "tool_start", toolName: event.toolName ?? "unknown", args: event.args });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
+				// Live event: tool execution ended
+				if (event.type === "tool_execution_end") {
+					if (onLive) {
+						try {
+							onLive({ kind: "tool_end", toolName: event.toolName ?? "unknown", isError: Boolean(event.isError) });
+						} catch { /* never throw from event handling */ }
+					}
+				}
+
 				if (event.type === "message_end" && event.message) {
 					const msg = event.message as Message;
 					currentResult.messages.push(msg);
@@ -248,6 +282,12 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 						if ((msg as any).stopReason) currentResult.stopReason = (msg as any).stopReason;
 						if ((msg as any).errorMessage) currentResult.errorMessage = (msg as any).errorMessage;
 					}
+					// Live event: usage snapshot after accumulation
+					if (onLive) {
+						try {
+							onLive({ kind: "usage", usage: { ...currentResult.usage }, model: currentResult.model });
+						} catch { /* never throw from event handling */ }
+					}
 					emitUpdate();
 				}
 
@@ -256,7 +296,6 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 					emitUpdate();
 				}
 			};
-
 			proc.stdout.on("data", (data) => {
 				buffer += data.toString();
 				const lines = buffer.split("\n");
@@ -270,6 +309,13 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 
 			proc.on("close", (code) => {
 				if (buffer.trim()) processLine(buffer);
+				// Live event: final status derived from exit code
+				if (onLive) {
+					try {
+						const failed = (code ?? 0) !== 0 || currentResult.stopReason === "error" || currentResult.stopReason === "aborted";
+						onLive({ kind: "status", status: failed ? "failed" : "done" });
+					} catch { /* never throw from event handling */ }
+				}
 				resolve(code ?? 0);
 			});
 
@@ -289,7 +335,14 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		});
 
 		currentResult.exitCode = exitCode;
-		if (wasAborted) throw new Error("Subagent was aborted");
+		if (wasAborted) {
+			if (onLive) {
+				try {
+					onLive({ kind: "status", status: "failed" });
+				} catch { /* never throw from event handling */ }
+			}
+			throw new Error("Subagent was aborted");
+		}
 		return currentResult;
 	} finally {
 		if (tmpPromptPath)