@jopqior/pi-subagents 1.0.0

package/src/ui/transcript-content.ts

@@ -0,0 +1,374 @@
+/**
+ * transcript-content.ts — the rows the `/subagents:sessions` overlay paints.
+ *
+ * Owns the transcript's content model: the `SessionMessage` → Pi-component
+ * mapping (mirroring Pi's own interactive-mode `renderSessionContext`), and the
+ * rendered rows those components produce at a given width. The overlay
+ * (`session-navigator.ts`) owns scroll state, chrome, and key handling, and
+ * asks this collaborator only for rows — it never reaches into the components.
+ *
+ * Lives in the SDK/TUI layer rather than the pure `session-navigation.ts` core
+ * because Pi's per-entry components require a `TUI`, `cwd`, and markdown theme.
+ */
+
+import {
+  AssistantMessageComponent,
+  BashExecutionComponent,
+  BranchSummaryMessageComponent,
+  CompactionSummaryMessageComponent,
+  parseSkillBlock,
+  SkillInvocationMessageComponent,
+  ToolExecutionComponent,
+  UserMessageComponent,
+} from "@earendil-works/pi-coding-agent";
+import { Container, type MarkdownTheme, Spacer, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentSessionEvent, SessionMessage } from "#src/types";
+import { describeActivity } from "#src/ui/display";
+import { GLYPHS } from "#src/ui/glyphs";
+import type { TranscriptSource } from "#src/ui/session-navigation";
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** The SDK/TUI environment Pi's per-entry components need, plus the transcript's source. */
+export interface TranscriptContentOptions {
+  tui: TUI;
+  cwd: string;
+  markdownTheme: MarkdownTheme;
+  source: TranscriptSource;
+}
+
+/**
+ * The transcript's renderable rows: settled history rendered through Pi's
+ * per-entry components, followed by the running agent's activity row.
+ *
+ * Settled rows are rendered once per width and cached, so a paint or a scroll
+ * costs a slice rather than a walk of the whole component tree. The activity
+ * row is recomputed per call — it is two rows, and it tracks live state the
+ * source updates without a rebuild.
+ *
+ * Settled history is held as one block of components per message, so a message
+ * that settles appends a block and a tool result touches only its own — neither
+ * discards the rest of the transcript's rendering. This is sound because the
+ * agent core pushes a finished message into its message array before notifying
+ * listeners, so at event time the settled prefix is already visible.
+ *
+ * The message currently being streamed is held as its own component, updated
+ * per delta exactly as Pi's interactive mode does, so a token never touches
+ * settled history. The two provably cannot overlap: the agent core keeps the
+ * in-flight message outside its message array until it settles.
+ */
+export class TranscriptContent {
+  private readonly options: TranscriptContentOptions;
+  /** Settled history, one block per message that produced components. */
+  private blocks: SettledBlock[] = [];
+  /** How many source messages have been consumed into `blocks`. */
+  private consumedCount = 0;
+  /** The last consumed message; a mismatch means history was rewritten. */
+  private lastConsumed: SessionMessage | undefined;
+  /** Whether any consumed block holds components, driving user-message spacing. */
+  private hasVisibleContent = false;
+  /** In-flight tool components by tool-call id, pairing a later result to its block. */
+  private readonly pendingTools = new Map<string, PendingTool>();
+  /** Width `blocks` and `settledRows` were rendered at. */
+  private settledWidth: number | undefined;
+  /** Concatenation of every block's rows, or undefined when the cache is cold. */
+  private settledRows: readonly string[] | undefined;
+  /** The message being streamed right now, rendered below settled history. */
+  private inFlight: AssistantMessageComponent | undefined;
+  /** Width `inFlightRows` was rendered at. */
+  private inFlightWidth: number | undefined;
+  private inFlightRows: readonly string[] | undefined;
+
+  constructor(options: TranscriptContentOptions) {
+    this.options = options;
+    this.consumeSettled();
+  }
+
+  /** Total content rows at `width`: settled history plus the live tail. */
+  lineCount(width: number): number {
+    if (width <= 0) return 0;
+    return this.settled(width).length + this.tail(width).length;
+  }
+
+  /** Rows `[start, start + count)` at `width`, clamped to what exists. */
+  slice(width: number, start: number, count: number): string[] {
+    if (width <= 0) return [];
+    const settled = this.settled(width);
+    const end = start + count;
+    const rows = settled.slice(start, Math.min(end, settled.length));
+    if (end > settled.length) {
+      const tail = this.tail(width);
+      rows.push(...tail.slice(Math.max(0, start - settled.length), end - settled.length));
+    }
+    return rows;
+  }
+
+  /**
+   * Route one session event to the narrowest update it allows. A delta on the
+   * in-flight message touches only that component. A run or compaction boundary
+   * may have rewritten or mutated history in place, so it rebuilds wholesale.
+   * Everything else consumes whatever settled since the last check.
+   */
+  apply(event?: AgentSessionEvent): void {
+    const partial = inFlightAssistantMessage(event);
+    if (partial) {
+      this.updateInFlight(partial);
+      return;
+    }
+    if (event?.type === "agent_end" || event?.type === "compaction_end") {
+      this.reset();
+    } else if (event?.type === "message_end") {
+      this.clearInFlight();
+    }
+    this.consumeSettled();
+  }
+
+  /** Drop cached rendering held by the mounted components and by this object. */
+  invalidate(): void {
+    for (const block of this.blocks) {
+      block.container.invalidate();
+      block.rows = undefined;
+    }
+    this.settledRows = undefined;
+    this.inFlight?.invalidate();
+    this.inFlightRows = undefined;
+  }
+
+  // ---- Private ----
+
+  /** Settled rows at `width`; each block renders once per width and content change. */
+  private settled(width: number): readonly string[] {
+    if (this.settledWidth !== width) {
+      this.settledWidth = width;
+      for (const block of this.blocks) block.rows = undefined;
+      this.settledRows = undefined;
+    }
+    if (this.settledRows) return this.settledRows;
+    const rows: string[] = [];
+    for (const block of this.blocks) {
+      block.rows ??= block.container.render(width).map((row) => truncateToWidth(row, width));
+      rows.push(...block.rows);
+    }
+    this.settledRows = rows;
+    return rows;
+  }
+
+  /** Rows below settled history: the in-flight message, then the activity row. */
+  private tail(width: number): readonly string[] {
+    const rows = [...this.inFlightRendered(width)];
+    const streaming = this.options.source.streaming();
+    if (streaming) {
+      const activity = `${GLYPHS.streaming} ${describeActivity(streaming.activeTools, streaming.responseText)}`;
+      rows.push("", truncateToWidth(activity, width));
+    }
+    return rows;
+  }
+
+  /** The in-flight message's rows, re-rendered independently of settled history. */
+  private inFlightRendered(width: number): readonly string[] {
+    if (!this.inFlight) return [];
+    if (this.inFlightWidth !== width) {
+      this.inFlightWidth = width;
+      this.inFlightRows = undefined;
+    }
+    this.inFlightRows ??= this.inFlight.render(width).map((row) => truncateToWidth(row, width));
+    return this.inFlightRows;
+  }
+
+  private updateInFlight(message: AssistantSessionMessage): void {
+    if (this.inFlight) this.inFlight.updateContent(message);
+    else this.inFlight = new AssistantMessageComponent(message, false, this.options.markdownTheme);
+    this.inFlightRows = undefined;
+  }
+
+  private clearInFlight(): void {
+    this.inFlight = undefined;
+    this.inFlightRows = undefined;
+  }
+
+  /** Discard all settled state, so the next consume rebuilds from scratch. */
+  private reset(): void {
+    this.blocks = [];
+    this.consumedCount = 0;
+    this.lastConsumed = undefined;
+    this.hasVisibleContent = false;
+    this.pendingTools.clear();
+    this.settledRows = undefined;
+    this.clearInFlight();
+  }
+
+  /**
+   * Append blocks for every message that settled since the last check. When the
+   * consumed prefix no longer mirrors the source — history replaced wholesale by
+   * compaction or branching — start over rather than appending onto stale blocks.
+   */
+  private consumeSettled(): void {
+    const messages = this.options.source.getMessages();
+    if (this.hasRewrittenHistory(messages)) this.reset();
+    if (messages.length === this.consumedCount) return;
+    for (let i = this.consumedCount; i < messages.length; i++) this.consumeMessage(messages[i]);
+    this.consumedCount = messages.length;
+    this.lastConsumed = messages.at(-1);
+    this.settledRows = undefined;
+  }
+
+  private hasRewrittenHistory(messages: readonly SessionMessage[]): boolean {
+    if (messages.length < this.consumedCount) return true;
+    return this.consumedCount > 0 && messages[this.consumedCount - 1] !== this.lastConsumed;
+  }
+
+  /**
+   * Map one settled message onto its own block of Pi's per-entry components,
+   * mirroring Pi's own interactive-mode `renderSessionContext` mapping.
+   * `custom`-role messages produce no block — rendering them needs the child
+   * session's message-renderer registry, which the navigator does not hold.
+   */
+  private consumeMessage(message: SessionMessage): void {
+    switch (message.role) {
+      case "assistant":
+        this.consumeAssistant(message);
+        break;
+      case "toolResult":
+        this.consumeToolResult(message);
+        break;
+      case "user":
+        this.consumeUser(message);
+        break;
+      case "bashExecution":
+        this.consumeBashExecution(message);
+        break;
+      case "compactionSummary":
+        this.consumeSummary(new CompactionSummaryMessageComponent(message, this.options.markdownTheme));
+        break;
+      case "branchSummary":
+        this.consumeSummary(new BranchSummaryMessageComponent(message, this.options.markdownTheme));
+        break;
+    }
+  }
+
+  private consumeAssistant(message: AssistantSessionMessage): void {
+    const block = this.appendBlock();
+    block.container.addChild(new AssistantMessageComponent(message, false, this.options.markdownTheme));
+    for (const content of message.content) {
+      if (content.type !== "toolCall") continue;
+      const tool = new ToolExecutionComponent(
+        content.name,
+        content.id,
+        content.arguments,
+        { showImages: false },
+        this.options.source.getToolDefinition(content.name),
+        this.options.tui,
+        this.options.cwd,
+      );
+      tool.setExpanded(true);
+      block.container.addChild(tool);
+      this.pendingTools.set(content.id, { component: tool, block });
+    }
+    this.hasVisibleContent = true;
+  }
+
+  /** A tool result mutates the block holding its call; no other block changes. */
+  private consumeToolResult(message: Extract<SessionMessage, { role: "toolResult" }>): void {
+    const pending = this.pendingTools.get(message.toolCallId);
+    if (!pending) return;
+    pending.component.updateResult(message);
+    pending.block.rows = undefined;
+    this.settledRows = undefined;
+    this.pendingTools.delete(message.toolCallId);
+  }
+
+  private consumeUser(message: Extract<SessionMessage, { role: "user" }>): void {
+    const block = this.appendBlock();
+    addUserComponents(block.container, message.content, this.options.markdownTheme, this.hasVisibleContent);
+    if (block.container.children.length > 0) this.hasVisibleContent = true;
+  }
+
+  private consumeBashExecution(message: Extract<SessionMessage, { role: "bashExecution" }>): void {
+    const block = this.appendBlock();
+    const bash = new BashExecutionComponent(message.command, this.options.tui, message.excludeFromContext);
+    if (message.output) bash.appendOutput(message.output);
+    bash.setComplete(message.exitCode, message.cancelled, undefined, message.fullOutputPath);
+    block.container.addChild(bash);
+    this.hasVisibleContent = true;
+  }
+
+  /** Compaction and branch summaries share the same spacer-plus-expanded shape. */
+  private consumeSummary(
+    summary: CompactionSummaryMessageComponent | BranchSummaryMessageComponent,
+  ): void {
+    const block = this.appendBlock();
+    block.container.addChild(new Spacer(1));
+    summary.setExpanded(true);
+    block.container.addChild(summary);
+    this.hasVisibleContent = true;
+  }
+
+  private appendBlock(): SettledBlock {
+    const block: SettledBlock = { container: new Container(), rows: undefined };
+    this.blocks.push(block);
+    return block;
+  }
+}
+
+/** One settled message's components plus its rows at the current width. */
+interface SettledBlock {
+  readonly container: Container;
+  rows: readonly string[] | undefined;
+}
+
+/** A tool call awaiting its result, and the block whose rows it will invalidate. */
+interface PendingTool {
+  readonly component: ToolExecutionComponent;
+  readonly block: SettledBlock;
+}
+
+/** The assistant variant of a session message, as Pi's components consume it. */
+type AssistantSessionMessage = Extract<SessionMessage, { role: "assistant" }>;
+
+/**
+ * The in-flight assistant message a partial event carries, or undefined when the
+ * event is anything else. A partial for another role means a message settled
+ * elsewhere in the history, which only a rebuild can pick up.
+ */
+function inFlightAssistantMessage(event?: AgentSessionEvent): AssistantSessionMessage | undefined {
+  if (event?.type !== "message_start" && event?.type !== "message_update") return undefined;
+  return event.message.role === "assistant" ? event.message : undefined;
+}
+
+/**
+ * Render a user message (skill block + text) into the block, mirroring Pi.
+ * Whether a leading spacer is needed is a whole-transcript property, so the
+ * caller — which alone knows what precedes this block — supplies it.
+ */
+function addUserComponents(
+  container: Container,
+  content: string | readonly { type: string; text?: string }[],
+  markdownTheme: MarkdownTheme,
+  hasPrecedingContent: boolean,
+): void {
+  const text = userMessageText(content);
+  if (!text) return;
+  if (hasPrecedingContent) container.addChild(new Spacer(1));
+
+  const skillBlock = parseSkillBlock(text);
+  if (!skillBlock) {
+    container.addChild(new UserMessageComponent(text, markdownTheme));
+    return;
+  }
+  const skill = new SkillInvocationMessageComponent(skillBlock, markdownTheme);
+  skill.setExpanded(true);
+  container.addChild(skill);
+  if (skillBlock.userMessage) {
+    container.addChild(new Spacer(1));
+    container.addChild(new UserMessageComponent(skillBlock.userMessage, markdownTheme));
+  }
+}
+
+/** Concatenate the text blocks of a user message's content (mirrors Pi). */
+function userMessageText(content: string | readonly { type: string; text?: string }[]): string {
+  if (typeof content === "string") return content;
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text ?? "")
+    .join("");
+}

package/src/ui/widget-renderer.ts

@@ -0,0 +1,301 @@
+/**
+ * widget-renderer.ts — Pure rendering functions for the agent widget.
+ *
+ * All functions are stateless: they receive data and return formatted strings.
+ * No timers, no SDK types, no side effects. Consumed by AgentWidget.
+ */
+
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import {
+	isActiveStatus,
+	type SubagentStatus,
+} from "#src/lifecycle/subagent-state";
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import { getLifetimeTotal } from "#src/lifecycle/usage";
+import type { SubagentType } from "#src/types";
+import {
+	describeActivity,
+	formatMs,
+	formatSessionTokens,
+	formatTurns,
+	getDisplayName,
+	getPromptModeLabel,
+	PENDING_SELECTION_ACTIVITY,
+	type Theme,
+} from "#src/ui/display";
+import { GLYPHS, SPINNER } from "#src/ui/glyphs";
+
+// ── Data interfaces ──────────────────────────────────────────────────────────
+
+/** Minimal agent snapshot for rendering — no class methods, no mutation surface. */
+export interface WidgetAgent {
+	readonly id: string;
+	readonly type: SubagentType;
+	readonly status: SubagentStatus;
+	readonly description: string;
+	readonly toolUses: number;
+	readonly startedAt: number;
+	readonly completedAt?: number;
+	readonly error?: string;
+	readonly lifetimeUsage?: Readonly<LifetimeUsage>;
+	readonly compactionCount: number;
+	// Live activity (folded from the former WidgetActivity — precomputed by AgentWidget)
+	readonly turnCount: number;
+	readonly maxTurns?: number;
+	readonly activeTools: ReadonlyMap<string, string>;
+	readonly responseText: string;
+	/** True while this run is waiting for a human model/thinking selection. */
+	readonly awaitingSelection?: boolean;
+	/** Context-window utilisation (0–100), or null when unavailable. */
+	readonly contextPercent: number | null;
+}
+
+// ── Per-agent rendering ──────────────────────────────────────────────────────
+
+/** Render a single finished agent line (no tree connector prefix). */
+export function renderFinishedLine(
+	agent: WidgetAgent,
+	registry: AgentConfigLookup,
+	theme: Theme,
+): string {
+	const name = getDisplayName(agent.type, registry);
+	const modeLabel = getPromptModeLabel(agent.type, registry);
+	const duration = formatMs((agent.completedAt ?? Date.now()) - agent.startedAt);
+
+	let icon: string;
+	let statusText: string;
+	if (agent.status === "completed") {
+		icon = theme.fg("success", GLYPHS.success);
+		statusText = "";
+	} else if (agent.status === "steered") {
+		icon = theme.fg("warning", GLYPHS.success);
+		statusText = theme.fg("warning", " (turn limit)");
+	} else if (agent.status === "stopped") {
+		icon = theme.fg("dim", GLYPHS.stopped);
+		statusText = theme.fg("dim", " stopped");
+	} else if (agent.status === "error") {
+		icon = theme.fg("error", GLYPHS.failure);
+		const errMsg = agent.error ? `: ${agent.error.slice(0, 60)}` : "";
+		statusText = theme.fg("error", ` error${errMsg}`);
+	} else {
+		// aborted
+		icon = theme.fg("error", GLYPHS.failure);
+		statusText = theme.fg("warning", " aborted");
+	}
+
+	const parts: string[] = [];
+	parts.push(formatTurns(agent.turnCount, agent.maxTurns));
+	if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool use${agent.toolUses === 1 ? "" : "s"}`);
+	parts.push(duration);
+
+	const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+	return `${icon} ${theme.fg("dim", name)}${modeTag}  ${theme.fg("dim", agent.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", parts.join(" · "))}${statusText}`;
+}
+
+/** Render a single running agent as header + activity line pair (no tree connector prefix). */
+export function renderRunningLines(
+	agent: WidgetAgent,
+	registry: AgentConfigLookup,
+	spinnerFrame: number,
+	theme: Theme,
+): [header: string, activity: string] {
+	const name = getDisplayName(agent.type, registry);
+	const modeLabel = getPromptModeLabel(agent.type, registry);
+	const modeTag = modeLabel ? ` ${theme.fg("dim", `(${modeLabel})`)}` : "";
+	const elapsed = formatMs(Date.now() - agent.startedAt);
+
+	const tokens = getLifetimeTotal(agent.lifetimeUsage);
+	const tokenText = tokens > 0 ? formatSessionTokens(tokens, agent.contextPercent, theme, agent.compactionCount) : "";
+
+	const parts: string[] = [];
+	parts.push(formatTurns(agent.turnCount, agent.maxTurns));
+	if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool use${agent.toolUses === 1 ? "" : "s"}`);
+	if (tokenText) parts.push(tokenText);
+	parts.push(elapsed);
+	const statsText = parts.join(" · ");
+
+	const frame = SPINNER[spinnerFrame % SPINNER.length];
+	const activityText = agent.awaitingSelection
+		? PENDING_SELECTION_ACTIVITY
+		: describeActivity(agent.activeTools, agent.responseText);
+
+	const header = `${theme.fg("accent", frame)} ${theme.bold(name)}${modeTag}  ${theme.fg("muted", agent.description)} ${theme.fg("dim", "·")} ${theme.fg("dim", statsText)}`;
+	const activityLine = theme.fg("dim", `  ${GLYPHS.subLine}  ${activityText}`);
+
+	return [header, activityLine];
+}
+
+// ── Full widget rendering ────────────────────────────────────────────────────
+
+/** Maximum number of rendered lines before overflow collapse kicks in. */
+const MAX_WIDGET_LINES = 12;
+
+interface AgentCategories {
+	running: WidgetAgent[];
+	queued: WidgetAgent[];
+	finished: WidgetAgent[];
+}
+
+/** Partition agents into rendering buckets. */
+function categorizeAgents(
+	agents: readonly WidgetAgent[],
+	shouldShowFinished: (agentId: string, status: string) => boolean,
+): AgentCategories {
+	return {
+		running: agents.filter(a => a.status === "running"),
+		queued: agents.filter(a => a.status === "queued"),
+		finished: agents.filter(
+			a => !isActiveStatus(a.status) && a.completedAt != null
+				&& shouldShowFinished(a.id, a.status),
+		),
+	};
+}
+
+interface WidgetSections {
+	finishedLines: string[];
+	runningLines: [string, string][];
+	queuedLine: string | undefined;
+}
+
+/** Render each agent bucket into pre-formatted lines with ├─ tree connectors. */
+function buildSections(
+	categories: AgentCategories,
+	registry: AgentConfigLookup,
+	spinnerFrame: number,
+	theme: Theme,
+	truncate: (line: string) => string,
+): WidgetSections {
+	const finishedLines: string[] = [];
+	for (const a of categories.finished) {
+		finishedLines.push(truncate(theme.fg("dim", "\u251C\u2500") + " " + renderFinishedLine(a, registry, theme)));
+	}
+
+	const runningLines: [string, string][] = [];
+	for (const a of categories.running) {
+		const [header, act] = renderRunningLines(a, registry, spinnerFrame, theme);
+		runningLines.push([
+			truncate(theme.fg("dim", "\u251C\u2500") + ` ${header}`),
+			truncate(theme.fg("dim", "\u2502  ") + act),
+		]);
+	}
+
+	const queuedLine = categories.queued.length > 0
+		? truncate(theme.fg("dim", "\u251C\u2500") + ` ${theme.fg("muted", GLYPHS.queued)} ${theme.fg("dim", `${categories.queued.length} queued`)}`)
+		: undefined;
+
+	return { finishedLines, runningLines, queuedLine };
+}
+
+/**
+ * Assemble widget lines when total body fits within MAX_WIDGET_LINES.
+ * Fixes the last tree connector: ├─ → └─, and │ → space for the running-agent activity line.
+ */
+function assembleWithinBudget(heading: string, sections: WidgetSections): string[] {
+	const { finishedLines, runningLines, queuedLine } = sections;
+	const lines: string[] = [heading, ...finishedLines];
+	for (const pair of runningLines) lines.push(...pair);
+	if (queuedLine) lines.push(queuedLine);
+
+	// Fix last connector: swap \u251C\u2500 \u2192 \u2514\u2500.
+	if (lines.length > 1) {
+		const last = lines.length - 1;
+		lines[last] = lines[last].replace("\u251C\u2500", "\u2514\u2500");
+		if (runningLines.length > 0 && !queuedLine) {
+			if (last >= 2) {
+				lines[last - 1] = lines[last - 1].replace("\u251C\u2500", "\u2514\u2500");
+				lines[last] = lines[last].replace("\u2502  ", "   ");
+			}
+		}
+	}
+	return lines;
+}
+
+/**
+ * Assemble widget lines when total body exceeds MAX_WIDGET_LINES.
+ * Prioritizes running > queued > finished and appends an overflow indicator.
+ */
+function assembleOverflow(
+	heading: string,
+	sections: WidgetSections,
+	maxBody: number,
+	truncate: (line: string) => string,
+	theme: Theme,
+): string[] {
+	const { finishedLines, runningLines, queuedLine } = sections;
+	const lines: string[] = [heading];
+	let budget = maxBody - 1;
+	let hiddenRunning = 0;
+	let hiddenFinished = 0;
+
+	for (const pair of runningLines) {
+		if (budget >= 2) {
+			lines.push(...pair);
+			budget -= 2;
+		} else {
+			hiddenRunning++;
+		}
+	}
+
+	if (queuedLine && budget >= 1) {
+		lines.push(queuedLine);
+		budget--;
+	}
+
+	for (const fl of finishedLines) {
+		if (budget >= 1) {
+			lines.push(fl);
+			budget--;
+		} else {
+			hiddenFinished++;
+		}
+	}
+
+	const overflowParts: string[] = [];
+	if (hiddenRunning > 0) overflowParts.push(`${hiddenRunning} running`);
+	if (hiddenFinished > 0) overflowParts.push(`${hiddenFinished} finished`);
+	const overflowText = overflowParts.join(", ");
+	lines.push(truncate(theme.fg("dim", "\u2514\u2500") + ` ${theme.fg("dim", `+${hiddenRunning + hiddenFinished} more (${overflowText})`)}`));
+	return lines;
+}
+
+/** Pure rendering of the widget body. Returns lines to display. */
+export function renderWidgetLines(params: {
+	agents: readonly WidgetAgent[];
+	registry: AgentConfigLookup;
+	spinnerFrame: number;
+	terminalWidth: number;
+	theme: Theme;
+	shouldShowFinished: (agentId: string, status: string) => boolean;
+}): string[] {
+	const { agents, registry, spinnerFrame, terminalWidth, theme, shouldShowFinished } = params;
+
+	const { running, queued, finished } = categorizeAgents(agents, shouldShowFinished);
+
+	const hasActive = running.length > 0 || queued.length > 0;
+	const hasFinished = finished.length > 0;
+
+	if (!hasActive && !hasFinished) return [];
+
+	const truncate = (line: string) => truncateToWidth(line, terminalWidth);
+	const headingColor = hasActive ? "accent" : "dim";
+	const headingIcon = hasActive ? GLYPHS.agentsActive : GLYPHS.agentsIdle;
+
+	const { finishedLines, runningLines, queuedLine } = buildSections(
+		{ running, queued, finished },
+		registry,
+		spinnerFrame,
+		theme,
+		truncate,
+	);
+
+	// Assemble with overflow cap (heading takes 1 line).
+	const maxBody = MAX_WIDGET_LINES - 1;
+	const totalBody = finishedLines.length + runningLines.length * 2 + (queuedLine ? 1 : 0);
+	const heading = truncate(theme.fg(headingColor, headingIcon) + " " + theme.fg(headingColor, "Agents"));
+
+	if (totalBody <= maxBody) {
+		return assembleWithinBudget(heading, { finishedLines, runningLines, queuedLine });
+	}
+	return assembleOverflow(heading, { finishedLines, runningLines, queuedLine }, maxBody, truncate, theme);
+}