@yandy0725/pi-subagents 0.1.0

package/src/ui/agent-widget.ts

@@ -0,0 +1,311 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/**
+ * agent-widget.ts — Persistent widget showing running/completed agents above the editor.
+ *
+ * Displays a tree of agents with animated spinners, live stats, and activity descriptions.
+ * Uses the callback form of setWidget for themed rendering.
+ */
+
+import type { AgentTypeRegistry } from "../config/agent-types";
+import type { Subagent } from "../lifecycle/subagent";
+import type { SubagentManager, SubagentManagerObserver } from "../lifecycle/subagent-manager";
+import type { CompactionInfo } from "../types";
+import { ERROR_STATUSES, type Theme } from "../ui/display";
+import { renderWidgetLines, type WidgetAgent } from "../ui/widget-renderer";
+
+// ---- Types ----
+
+/** Minimal agent shape needed for widget lifecycle decisions. */
+interface AgentSummary {
+	readonly id: string;
+	readonly status: string;
+	readonly completedAt?: number;
+}
+
+/** Lightweight state snapshot used by AgentWidget.update() to decide what to show. */
+export interface WidgetState {
+	readonly runningCount: number;
+	readonly queuedCount: number;
+	readonly hasFinished: boolean;
+	/** True when runningCount > 0 || queuedCount > 0. Included for call-site readability. */
+	readonly hasActive: boolean;
+}
+
+/**
+ * Count agents by status and return a lightweight state snapshot.
+ * Pure function — no IO, no side effects. Exported for direct unit testing.
+ */
+export function assembleWidgetState(
+	agents: readonly AgentSummary[],
+	shouldShowFinished: (agentId: string, status: string) => boolean,
+): WidgetState {
+	let runningCount = 0;
+	let queuedCount = 0;
+	let hasFinished = false;
+	for (const a of agents) {
+		if (a.status === "running") {
+			runningCount++;
+		} else if (a.status === "queued") {
+			queuedCount++;
+		} else if (a.completedAt && shouldShowFinished(a.id, a.status)) {
+			hasFinished = true;
+		}
+	}
+	const hasActive = runningCount > 0 || queuedCount > 0;
+	return { runningCount, queuedCount, hasFinished, hasActive };
+}
+
+export type UICtx = {
+	setStatus(key: string, text: string | undefined): void;
+	setWidget(
+		key: string,
+		content: undefined | ((tui: any, theme: Theme) => { render(): string[]; invalidate(): void }),
+		options?: { placement?: "aboveEditor" | "belowEditor" },
+	): void;
+};
+
+// ---- Widget manager ----
+
+export class AgentWidget implements SubagentManagerObserver {
+	private uiCtx: UICtx | undefined;
+	private widgetFrame = 0;
+	private widgetInterval: ReturnType<typeof setInterval> | undefined;
+	/** Tracks how many turns each finished agent has survived. Key: agent ID, Value: turns since finished. */
+	private finishedTurnAge = new Map<string, number>();
+	/** How many extra turns errors/aborted agents linger (completed agents clear after 1 turn). */
+	private static readonly ERROR_LINGER_TURNS = 2;
+
+	/** Whether the widget callback is currently registered with the TUI. */
+	private widgetRegistered = false;
+	/** Cached TUI reference from widget factory callback, used for requestRender(). */
+	private tui: any | undefined;
+	/** Last status bar text, used to avoid redundant setStatus calls. */
+	private lastStatusText: string | undefined;
+
+	constructor(
+		private manager: SubagentManager,
+		private registry: AgentTypeRegistry,
+	) {}
+
+	/** Set the UI context (grabbed from first tool execution). */
+	setUICtx(ctx: UICtx) {
+		if (ctx !== this.uiCtx) {
+			// UICtx changed — the widget registered on the old context is gone.
+			// Force re-registration on next update().
+			this.uiCtx = ctx;
+			this.widgetRegistered = false;
+			this.tui = undefined;
+			this.lastStatusText = undefined;
+		}
+	}
+
+	/**
+	 * Called on each new turn (tool_execution_start).
+	 * Ages finished agents and clears those that have lingered long enough.
+	 */
+	onTurnStart() {
+		// Age all finished agents
+		for (const [id, age] of this.finishedTurnAge) {
+			this.finishedTurnAge.set(id, age + 1);
+		}
+		// Trigger a widget refresh (will filter out expired agents)
+		this.update();
+	}
+
+	// ---- SubagentManagerObserver: react to lifecycle, self-drive the timer ----
+
+	/** A subagent started running — ensure the update loop is live and render. */
+	onSubagentStarted(_record: Subagent) {
+		this.startLoop();
+	}
+
+	/** A background subagent was created (queued) — ensure the loop is live and render. */
+	onSubagentCreated(_record: Subagent) {
+		this.startLoop();
+	}
+
+	/** A subagent completed — render so the finished state is seeded and shown. */
+	onSubagentCompleted(_record: Subagent) {
+		this.update();
+	}
+
+	/** A subagent's session compacted — render to refresh the compaction count. */
+	onSubagentCompacted(_record: Subagent, _info: CompactionInfo) {
+		this.update();
+	}
+
+	/** Start the update timer (if not already running) and render immediately. */
+	private startLoop() {
+		this.ensureTimer();
+		this.update();
+	}
+
+	/** Ensure the widget update timer is running. */
+	private ensureTimer() {
+		this.widgetInterval ??= setInterval(() => this.update(), 80);
+	}
+
+	/** Check if a finished agent should still be shown in the widget. */
+	private shouldShowFinished(agentId: string, status: string): boolean {
+		const age = this.finishedTurnAge.get(agentId) ?? 0;
+		const maxAge = ERROR_STATUSES.has(status) ? AgentWidget.ERROR_LINGER_TURNS : 1;
+		return age < maxAge;
+	}
+
+	/**
+	 * Background agents only — the widget's sole audience (ADR-0004 Decision A).
+	 * Foreground runs are rendered by the `subagent` tool's inline `onUpdate` stream,
+	 * so funneling both `listAgents()` call sites through this accessor applies the
+	 * background predicate exactly once at the source.
+	 */
+	private listBackgroundAgents(): Subagent[] {
+		return this.manager.listAgents().filter((record) => record.invocation?.runInBackground === true);
+	}
+
+	/** Project a live Subagent record onto a pure-data WidgetAgent snapshot. */
+	private toWidgetAgent(record: Subagent): WidgetAgent {
+		return {
+			id: record.id,
+			type: record.type,
+			status: record.status,
+			description: record.description,
+			toolUses: record.toolUses,
+			startedAt: record.startedAt,
+			completedAt: record.completedAt,
+			error: record.error,
+			lifetimeUsage: record.lifetimeUsage,
+			compactionCount: record.compactionCount,
+			turnCount: record.turnCount,
+			maxTurns: record.maxTurns,
+			activeTools: record.activeTools,
+			responseText: record.responseText,
+			contextPercent: record.getContextPercent(),
+		};
+	}
+
+	/** Delegate rendering to the pure widget-renderer module. */
+	private renderWidget(tui: any, theme: Theme): string[] {
+		return renderWidgetLines({
+			agents: this.listBackgroundAgents().map((r) => this.toWidgetAgent(r)),
+			registry: this.registry,
+			spinnerFrame: this.widgetFrame,
+			terminalWidth: tui.terminal.columns,
+			theme,
+			shouldShowFinished: (id, status) => this.shouldShowFinished(id, status),
+		});
+	}
+
+	/**
+	 * Unregister the widget, clear the status bar, stop the interval timer, and
+	 * purge stale `finishedTurnAge` entries for agents no longer in `backgroundAgents`.
+	 * Called only from `update`'s idle path — not from `dispose`.
+	 */
+	private clearWidget(backgroundAgents: readonly AgentSummary[]): void {
+		if (this.widgetRegistered) {
+			this.uiCtx!.setWidget("agents", undefined);
+			this.widgetRegistered = false;
+			this.tui = undefined;
+		}
+		if (this.lastStatusText !== undefined) {
+			this.uiCtx!.setStatus("subagents", undefined);
+			this.lastStatusText = undefined;
+		}
+		if (this.widgetInterval) {
+			clearInterval(this.widgetInterval);
+			this.widgetInterval = undefined;
+		}
+		for (const [id] of this.finishedTurnAge) {
+			if (!backgroundAgents.some((a) => a.id === id)) this.finishedTurnAge.delete(id);
+		}
+	}
+
+	/**
+	 * Compute the status bar text from the current widget state and call
+	 * `setStatus` only when it differs from the last cached value.
+	 */
+	private updateStatusBar(state: WidgetState): void {
+		let newStatusText: string | undefined;
+		if (state.hasActive) {
+			const statusParts: string[] = [];
+			if (state.runningCount > 0) statusParts.push(`${state.runningCount} running`);
+			if (state.queuedCount > 0) statusParts.push(`${state.queuedCount} queued`);
+			const total = state.runningCount + state.queuedCount;
+			newStatusText = `${statusParts.join(", ")} agent${total === 1 ? "" : "s"}`;
+		}
+		if (newStatusText !== this.lastStatusText) {
+			this.uiCtx!.setStatus("subagents", newStatusText);
+			this.lastStatusText = newStatusText;
+		}
+	}
+
+	/**
+	 * Seed linger tracking for any newly-observed finished agent.
+	 * The widget owns detection of completions it observes via `listAgents()`,
+	 * so no external bookkeeping call is needed.
+	 * Idempotent — only seeds when an entry is absent, so repeated updates within
+	 * a turn neither reset nor advance the age.
+	 */
+	private seedFinishedAgents(agents: readonly AgentSummary[]): void {
+		for (const a of agents) {
+			if (a.completedAt && !this.finishedTurnAge.has(a.id)) {
+				this.finishedTurnAge.set(a.id, 0);
+			}
+		}
+	}
+
+	/** Force an immediate widget update. */
+	update() {
+		if (!this.uiCtx) return;
+
+		const backgroundAgents = this.listBackgroundAgents();
+		this.seedFinishedAgents(backgroundAgents);
+		const state = assembleWidgetState(backgroundAgents, (id, status) => this.shouldShowFinished(id, status));
+
+		if (!state.hasActive && !state.hasFinished) {
+			this.clearWidget(backgroundAgents);
+			return;
+		}
+
+		this.updateStatusBar(state);
+		this.widgetFrame++;
+
+		// Register widget callback once; subsequent updates use requestRender()
+		// which re-invokes render() without replacing the component (avoids layout thrashing).
+		if (!this.widgetRegistered) {
+			this.uiCtx.setWidget(
+				"agents",
+				(tui, theme) => {
+					this.tui = tui;
+					return {
+						render: () => this.renderWidget(tui, theme),
+						invalidate: () => {
+							// Theme changed — force re-registration so factory captures fresh theme.
+							this.widgetRegistered = false;
+							this.tui = undefined;
+						},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
+			this.widgetRegistered = true;
+		} else {
+			// Widget already registered — just request a re-render of existing components.
+			this.tui?.requestRender();
+		}
+	}
+
+	// fallow-ignore-next-line unused-class-member
+	dispose() {
+		if (this.widgetInterval) {
+			clearInterval(this.widgetInterval);
+			this.widgetInterval = undefined;
+		}
+		if (this.uiCtx) {
+			this.uiCtx.setWidget("agents", undefined);
+			this.uiCtx.setStatus("subagents", undefined);
+		}
+		this.widgetRegistered = false;
+		this.tui = undefined;
+		this.lastStatusText = undefined;
+	}
+}

package/src/ui/display.ts

@@ -0,0 +1,174 @@
+/**
+ * display.ts — Pure formatting helpers and display utilities for agent UI.
+ *
+ * All functions are stateless and dependency-free (no SDK, no widget lifecycle).
+ * Consumed by the widget, the menu, tool modules, and the notification renderer.
+ */
+
+import type { AgentConfigLookup } from "../config/agent-types";
+import type { AgentInvocation, SubagentType } from "../types";
+
+// ---- Types ----
+
+export type Theme = {
+	fg(color: string, text: string): string;
+	bold(text: string): string;
+};
+
+/** Metadata attached to Agent tool results for custom rendering. */
+export interface AgentDetails {
+	displayName: string;
+	description: string;
+	subagentType: string;
+	toolUses: number;
+	tokens: string;
+	durationMs: number;
+	status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+	/** Human-readable description of what the agent is currently doing. */
+	activity?: string;
+	/** Current spinner frame index (for animated running indicator). */
+	spinnerFrame?: number;
+	/** Short model name if different from parent (e.g. "haiku", "sonnet"). */
+	modelName?: string;
+	/** Notable config tags (e.g. ["thinking: high", "inherit context"]). */
+	tags?: string[];
+	/** Current turn count. */
+	turnCount?: number;
+	/** Effective max turns (undefined = unlimited). */
+	maxTurns?: number;
+	agentId?: string;
+	error?: string;
+}
+
+// ---- Constants ----
+
+/** Braille spinner frames for animated running indicator. */
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
+export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+
+/** Tool name → human-readable action for activity descriptions. */
+const TOOL_DISPLAY: Record<string, string> = {
+	read: "reading",
+	bash: "running command",
+	edit: "editing",
+	write: "writing",
+	grep: "searching",
+	find: "finding files",
+	ls: "listing",
+};
+
+// ---- Pure formatters ----
+
+/** Format a token count compactly: "33.8k token", "1.2M token". */
+export function formatTokens(count: number): string {
+	if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M token`;
+	if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k token`;
+	return `${count} token`;
+}
+
+/**
+ * Token count with optional context-fill % and compaction-count annotations.
+ * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
+ * Compaction count rendered as `↻N` in dim.
+ *
+ *   "12.3k token"               — no annotations
+ *   "12.3k token (45%)"         — percent only
+ *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ↻2)"    — both
+ */
+export function formatSessionTokens(tokens: number, percent: number | null, theme: Theme, compactions = 0): string {
+	const tokenStr = formatTokens(tokens);
+	const annot: string[] = [];
+	if (percent !== null) {
+		const color = percent >= 85 ? "error" : percent >= 70 ? "warning" : "dim";
+		annot.push(theme.fg(color, `${Math.round(percent)}%`));
+	}
+	if (compactions > 0) {
+		annot.push(theme.fg("dim", `↻${compactions}`));
+	}
+	if (annot.length === 0) return tokenStr;
+	const sep = theme.fg("dim", " · ");
+	return `${tokenStr} ${theme.fg("dim", "(")}${annot.join(sep)}${theme.fg("dim", ")")}`;
+}
+
+/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+export function formatTurns(turnCount: number, maxTurns?: number | null): string {
+	return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+}
+
+/** Format milliseconds as human-readable duration. */
+export function formatMs(ms: number): string {
+	return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** Format duration from start/completed timestamps. */
+export function formatDuration(startedAt: number, completedAt?: number): string {
+	if (completedAt) return formatMs(completedAt - startedAt);
+	return `${formatMs(Date.now() - startedAt)} (running)`;
+}
+
+// ---- Display helpers ----
+
+/** Get display name for any agent type (built-in or custom). */
+export function getDisplayName(type: SubagentType, registry: AgentConfigLookup): string {
+	const config = registry.resolveAgentConfig(type);
+	return config.displayName ?? config.name;
+}
+
+/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
+export function getPromptModeLabel(type: SubagentType, registry: AgentConfigLookup): string | undefined {
+	const config = registry.resolveAgentConfig(type);
+	return config.promptMode === "append" ? "twin" : undefined;
+}
+
+/** Mode label is not included — callers add it where they want it. */
+export function buildInvocationTags(invocation: AgentInvocation | undefined): { modelName?: string; tags: string[] } {
+	const tags: string[] = [];
+	if (!invocation) return { tags };
+	if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
+	if (invocation.inheritContext) tags.push("inherit context");
+	if (invocation.runInBackground) tags.push("background");
+	if (invocation.maxTurns != null) tags.push(`max turns: ${invocation.maxTurns}`);
+	return { modelName: invocation.modelName, tags };
+}
+
+/** Truncate text to a single line, max `len` chars. */
+function truncateLine(text: string, len = 60): string {
+	const line =
+		text
+			.split("\n")
+			.find((l) => l.trim())
+			?.trim() ?? "";
+	if (line.length <= len) return line;
+	return line.slice(0, len) + "…";
+}
+
+/** Build a human-readable activity string from currently-running tools or response text. */
+export function describeActivity(activeTools: ReadonlyMap<string, string>, responseText?: string): string {
+	if (activeTools.size > 0) {
+		const groups = new Map<string, number>();
+		for (const toolName of activeTools.values()) {
+			const action = TOOL_DISPLAY[toolName] ?? toolName;
+			groups.set(action, (groups.get(action) ?? 0) + 1);
+		}
+
+		const parts: string[] = [];
+		for (const [action, count] of groups) {
+			if (count > 1) {
+				parts.push(`${action} ${count} ${action === "searching" ? "patterns" : "files"}`);
+			} else {
+				parts.push(action);
+			}
+		}
+		return parts.join(", ") + "…";
+	}
+
+	// No tools active — show truncated response text if available
+	if (responseText && responseText.trim().length > 0) {
+		return truncateLine(responseText);
+	}
+
+	return "thinking…";
+}

package/src/ui/session-navigation.ts

@@ -0,0 +1,147 @@
+/**
+ * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
+ *
+ * Splits the unit-testable core of the `/subagents:sessions` command from its TUI
+ * wiring (`session-navigator.ts`): which subagents are navigable and how a picked
+ * agent's transcript is sourced (live, in this slice).
+ *
+ * The `TranscriptSource` seam decouples *how messages are sourced* (live record
+ * here; a file snapshot in a follow-up) from *how they render* — the renderer
+ * (`session-navigator.ts`, which mounts Pi's per-entry components) talks only to
+ * this seam. Rendering lives in the SDK/TUI module because the per-entry
+ * components require a `TUI`, `cwd`, and markdown theme.
+ */
+
+import {
+	buildSessionContext,
+	parseSessionEntries,
+	type SessionEntry,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentConfigLookup } from "../config/agent-types";
+import type { EvictedSubagent } from "../lifecycle/subagent-manager";
+import type { SubagentStatus } from "../lifecycle/subagent-state";
+import type { AgentSessionEvent, SessionMessage, SubagentType } from "../types";
+import { formatDuration, getDisplayName } from "../ui/display";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The record fields the navigator reads to label and live-source a transcript. */
+export interface NavigableSubagent {
+	readonly id: string;
+	readonly type: SubagentType;
+	readonly description: string;
+	readonly status: SubagentStatus;
+	readonly startedAt: number;
+	readonly completedAt: number | undefined;
+	readonly toolUses: number;
+	readonly activeTools: ReadonlyMap<string, string>;
+	readonly responseText: string;
+	readonly agentMessages: readonly SessionMessage[];
+	isSessionReady(): boolean;
+	subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+	getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+/**
+ * A navigable entry plus the label shown in the picker.
+ *
+ * A `live` entry sources its transcript from the in-memory record; an `evicted`
+ * entry sources it from the persisted session file (the record is gone).
+ */
+export type NavigationEntry =
+	| { readonly kind: "live"; readonly label: string; readonly record: NavigableSubagent }
+	| { readonly kind: "evicted"; readonly label: string; readonly outputFile: string };
+
+/** The fields `buildLabel` reads — shared by a live record and an evicted descriptor. */
+interface LabelFields {
+	readonly type: SubagentType;
+	readonly description: string;
+	readonly status: SubagentStatus;
+	readonly startedAt: number;
+	readonly completedAt: number | undefined;
+	readonly toolUses: number;
+}
+
+/** Running-agent streaming state, surfaced by a live source. */
+export interface StreamingState {
+	readonly activeTools: ReadonlyMap<string, string>;
+	readonly responseText: string;
+}
+
+/** Liveness-agnostic transcript source consumed by the renderer. */
+export interface TranscriptSource {
+	/** Current message history. */
+	getMessages(): readonly SessionMessage[];
+	/** Subscribe to changes; returns an unsubscribe, or undefined for a static snapshot. */
+	subscribe(onChange: () => void): (() => void) | undefined;
+	/** Running-agent streaming state, or undefined when not streaming. */
+	streaming(): StreamingState | undefined;
+	/** Resolve a registered tool definition by name, for Pi's tool-execution components. */
+	getToolDefinition(name: string): ToolDefinition | undefined;
+}
+
+/**
+ * Label every navigable subagent for the picker: live records with a viewable
+ * session, then agents evicted by the cleanup sweep (deduped against live ids).
+ */
+export function listNavigableAgents(
+	agents: readonly NavigableSubagent[],
+	evicted: readonly EvictedSubagent[],
+	registry: AgentConfigLookup,
+): NavigationEntry[] {
+	const live = agents
+		.filter((record) => record.isSessionReady())
+		.map((record): NavigationEntry => ({ kind: "live", record, label: buildLabel(record, registry) }));
+	const liveIds = new Set(agents.map((record) => record.id));
+	const evictedEntries = evicted
+		.filter((descriptor) => !liveIds.has(descriptor.id))
+		.map(
+			(descriptor): NavigationEntry => ({
+				kind: "evicted",
+				outputFile: descriptor.outputFile,
+				label: buildLabel(descriptor, registry, true),
+			}),
+		);
+	return [...live, ...evictedEntries];
+}
+
+/**
+ * Source a transcript from a persisted child-session JSONL snapshot.
+ *
+ * For an agent evicted from the manager's map by the 10-minute cleanup sweep:
+ * the in-memory record (and its message history) is gone, but the session file
+ * survives on disk. Reads the file, drops the `SessionHeader`, and resolves the
+ * message list via Pi's own parser. A static snapshot — no subscription, no
+ * streaming, no live tool registry. `readFile` is injected so this module makes
+ * no `fs` calls.
+ */
+export function fileSnapshotSource(outputFile: string, readFile: (path: string) => string): TranscriptSource {
+	const entries = parseSessionEntries(readFile(outputFile));
+	const sessionEntries = entries.filter((entry): entry is SessionEntry => entry.type !== "session");
+	const { messages } = buildSessionContext(sessionEntries);
+	return {
+		getMessages: () => messages,
+		subscribe: () => undefined,
+		streaming: () => undefined,
+		getToolDefinition: () => undefined,
+	};
+}
+
+/** Source a transcript live from an in-memory record (this slice's only source). */
+export function liveSource(record: NavigableSubagent): TranscriptSource {
+	return {
+		getMessages: () => record.agentMessages,
+		subscribe: (onChange) => record.subscribeToUpdates(() => onChange()),
+		streaming: () =>
+			record.status === "running" ? { activeTools: record.activeTools, responseText: record.responseText } : undefined,
+		getToolDefinition: (name) => record.getToolDefinition(name),
+	};
+}
+
+function buildLabel(fields: LabelFields, registry: AgentConfigLookup, evicted = false): string {
+	const name = getDisplayName(fields.type, registry);
+	const duration = formatDuration(fields.startedAt, fields.completedAt);
+	const marker = evicted ? " · evicted (snapshot)" : "";
+	return `${name} (${fields.description}) · ${fields.toolUses} tools · ${fields.status} · ${duration}${marker}`;
+}