@gotgenes/pi-subagents 17.3.0 → 17.5.0

package/src/lifecycle/subagent-manager.ts

@@ -14,12 +14,31 @@ import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { Subagent, type SubagentLifecycleObserver } from "#src/lifecycle/subagent";
 import type { SubagentSession } from "#src/lifecycle/subagent-session";
-import { SubagentState } from "#src/lifecycle/subagent-state";
+import { SubagentState, type SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
 import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
+/**
+ * A lightweight snapshot of a subagent evicted by the 10-minute cleanup sweep.
+ *
+ * The sweep frees the heavy in-memory session (its message history included);
+ * this descriptor retains only the fields the session navigator needs to label
+ * the agent in the picker, plus the persisted `outputFile` to source its
+ * transcript from disk. Carries no messages, so memory stays bounded.
+ */
+export interface EvictedSubagent {
+  readonly id: string;
+  readonly type: SubagentType;
+  readonly description: string;
+  readonly status: SubagentStatus;
+  readonly startedAt: number;
+  readonly completedAt: number | undefined;
+  readonly toolUses: number;
+  readonly outputFile: string;
+}
+
 /** Observer interface for agent lifecycle notifications. */
 export interface SubagentManagerObserver {
   onSubagentStarted(record: Subagent): void;
@@ -65,6 +84,8 @@ export interface AgentSpawnConfig {
 
 export class SubagentManager {
   private agents = new Map<string, Subagent>();
+  /** Descriptors of agents removed by the cleanup sweep, keyed by id — navigable from disk. */
+  private readonly evicted = new Map<string, EvictedSubagent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: SubagentManagerObserver;
   private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
@@ -220,6 +241,11 @@ export class SubagentManager {
     );
   }
 
+  /** Descriptors of agents evicted by the cleanup sweep, most recent first. */
+  listEvicted(): EvictedSubagent[] {
+    return [...this.evicted.values()].sort((a, b) => b.startedAt - a.startedAt);
+  }
+
   abort(id: string): boolean {
     const record = this.agents.get(id);
     if (!record) return false;
@@ -245,6 +271,9 @@ export class SubagentManager {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
       if ((record.completedAt ?? 0) >= cutoff) continue;
+      // Retain a navigable descriptor before freeing the heavy session. Only an
+      // agent with a persisted file can be sourced from disk after eviction.
+      if (record.outputFile) this.evicted.set(id, toEvictedSubagent(record, record.outputFile));
       this.removeRecord(id, record);
     }
   }
@@ -258,6 +287,8 @@ export class SubagentManager {
       if (record.status === "running" || record.status === "queued") continue;
       this.removeRecord(id, record);
     }
+    // Evicted descriptors belong to the session that swept them — a new session starts empty.
+    this.evicted.clear();
   }
 
   /** Whether any agents are still running or queued. */
@@ -314,5 +345,20 @@ export class SubagentManager {
       record.disposeSession();
     }
     this.agents.clear();
+    this.evicted.clear();
   }
 }
+
+/** Capture an evicted agent's navigable fields from its record. */
+function toEvictedSubagent(record: Subagent, outputFile: string): EvictedSubagent {
+  return {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    startedAt: record.startedAt,
+    completedAt: record.completedAt,
+    toolUses: record.toolUses,
+    outputFile,
+  };
+}

package/src/lifecycle/subagent-session.ts

@@ -13,6 +13,7 @@
 import {
   type AgentSession,
   type AgentSessionEvent,
+  type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
@@ -184,6 +185,11 @@ export class SubagentSession {
     return this._session.messages;
   }
 
+  /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
+  getToolDefinition(name: string): ToolDefinition | undefined {
+    return this._session.getToolDefinition(name);
+  }
+
   /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
   dispose(): void {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations

package/src/lifecycle/subagent.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
@@ -167,6 +167,11 @@ export class Subagent {
 		return this.subagentSession?.agentMessages ?? [];
 	}
 
+	/** Resolve a registered tool definition by name, or undefined if no session. */
+	getToolDefinition(name: string): ToolDefinition | undefined {
+		return this.subagentSession?.getToolDefinition(name);
+	}
+
 	constructor(init: SubagentInit) {
 		// Identity
 		this.id = init.id;

package/src/ui/session-navigation.ts

@@ -2,20 +2,22 @@
  * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
  *
  * Splits the unit-testable core of the `/subagent-sessions` command from its TUI
- * wiring (`session-navigator.ts`): which subagents are navigable, how a picked
- * agent's transcript is sourced (live, in this slice), and how the transcript
- * renders to plain text via Pi's own `serializeConversation`.
+ * 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* (text here; Pi's
- * per-entry components in a follow-up). The renderer talks only to this seam.
+ * 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 { serializeConversation } from "@earendil-works/pi-coding-agent";
+import { buildSessionContext, parseSessionEntries, type SessionEntry, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EvictedSubagent } from "#src/lifecycle/subagent-manager";
 import type { SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { AgentSessionEvent, SessionMessage, SubagentType } from "#src/types";
-import { describeActivity, formatDuration, getDisplayName } from "#src/ui/display";
+import { formatDuration, getDisplayName } from "#src/ui/display";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -33,12 +35,27 @@ export interface NavigableSubagent {
   readonly agentMessages: readonly SessionMessage[];
   isSessionReady(): boolean;
   subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+  getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
-/** A navigable entry: a record plus the label shown in the picker. */
-export interface NavigationEntry {
-  readonly record: NavigableSubagent;
-  readonly label: string;
+/**
+ * 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. */
@@ -55,16 +72,56 @@ export interface TranscriptSource {
   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;
 }
 
-/** Filter the agents to those with a viewable session and label each for the picker. */
+/**
+ * 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[] {
-  return agents
+  const live = agents
     .filter((record) => record.isSessionReady())
-    .map((record) => ({ record, label: buildLabel(record, registry) }));
+    .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). */
@@ -76,39 +133,13 @@ export function liveSource(record: NavigableSubagent): TranscriptSource {
       record.status === "running"
         ? { activeTools: record.activeTools, responseText: record.responseText }
         : undefined,
+    getToolDefinition: (name) => record.getToolDefinition(name),
   };
 }
 
-/** Render a source's transcript to plain text lines via Pi's `serializeConversation`. */
-export function renderTranscriptLines(source: TranscriptSource): string[] {
-  const messages = source.getMessages();
-  const lines =
-    messages.length === 0 ? ["(no messages yet)"] : serializeConversation(toMessages(messages)).split("\n");
-
-  const streaming = source.streaming();
-  if (streaming) {
-    lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
-  }
-  return lines;
-}
-
-/**
- * Bridge the session's `AgentMessage[]` to `serializeConversation`'s `Message[]`.
- *
- * `AgentMessage` is a superset of `Message` (it adds session-display variants such
- * as `BashExecutionMessage`); `serializeConversation` renders the shared shape and
- * best-effort text for the rest. `Message` is not re-exported from the public
- * `@earendil-works/pi-ai` barrel, so the parameter type is referenced via the
- * function signature rather than imported by name.
- */
-function toMessages(
-  messages: readonly SessionMessage[],
-): Parameters<typeof serializeConversation>[0] {
-  return messages as unknown as Parameters<typeof serializeConversation>[0];
-}
-
-function buildLabel(record: NavigableSubagent, registry: AgentConfigLookup): string {
-  const name = getDisplayName(record.type, registry);
-  const duration = formatDuration(record.startedAt, record.completedAt);
-  return `${name} (${record.description}) · ${record.toolUses} tools · ${record.status} · ${duration}`;
+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}`;
 }

package/src/ui/session-navigator.ts

@@ -1,26 +1,47 @@
 /**
  * session-navigator.ts — The `/subagent-sessions` command: pick a subagent and
- * read its transcript through Pi's own session-rendering text.
+ * read its transcript through Pi's own per-entry session components.
  *
  * SDK/TUI consumer half of native session navigation. The unit-testable core
- * (selection, sourcing, text rendering) lives in `session-navigation.ts`; this
- * module wires that core to the command picker and a read-only scrollable overlay.
+ * (selection, sourcing) lives in `session-navigation.ts`; this module wires that
+ * core to the command picker and a read-only scrollable overlay, and owns the
+ * renderer — it mounts Pi's interactive components (`AssistantMessageComponent`,
+ * `ToolExecutionComponent`, …) into a `Container`, mirroring Pi's own
+ * `renderSessionContext` mapping. Rendering lives here, not in the pure module,
+ * because the components require a `TUI`, `cwd`, and markdown theme.
  *
  * The overlay is strictly read-only — steering stays in the `steer_subagent` tool
- * and the widget. It consumes a `TranscriptSource`, so the renderer-upgrade and
- * evicted-agent-source follow-ups swap the source/renderer without touching it.
+ * and the widget. It consumes a `TranscriptSource`, so the evicted-agent-source
+ * follow-up swaps the source without touching the renderer or the overlay.
  */
 
-import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import type { AgentConfigLookup } from "#src/config/agent-types";
-import type { Theme } from "#src/ui/display";
 import {
-  listNavigableAgents,
-  liveSource,
-  type NavigableSubagent,
-  renderTranscriptLines,
-  type TranscriptSource,
-} from "#src/ui/session-navigation";
+  AssistantMessageComponent,
+  BashExecutionComponent,
+  BranchSummaryMessageComponent,
+  CompactionSummaryMessageComponent,
+  getMarkdownTheme,
+  parseSkillBlock,
+  SkillInvocationMessageComponent,
+  type ToolDefinition,
+  ToolExecutionComponent,
+  UserMessageComponent,
+} from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  Container,
+  type MarkdownTheme,
+  matchesKey,
+  Spacer,
+  type TUI,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { EvictedSubagent } from "#src/lifecycle/subagent-manager";
+import type { SessionMessage } from "#src/types";
+import { describeActivity, type Theme } from "#src/ui/display";
+import { fileSnapshotSource, listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -48,7 +69,13 @@ export interface SessionNavigatorUI {
 export interface SessionNavigatorParams {
   ui: SessionNavigatorUI;
   agents: readonly NavigableSubagent[];
+  /** Descriptors of agents evicted by the cleanup sweep, sourced from disk when picked. */
+  evicted: readonly EvictedSubagent[];
   registry: AgentConfigLookup;
+  /** Working directory for tool-call rendering (relative path display). */
+  cwd: string;
+  /** Reads a persisted session file for the file-snapshot source. */
+  readFile: (path: string) => string;
 }
 
 /** Options for the read-only transcript overlay. */
@@ -57,7 +84,8 @@ export interface TranscriptOverlayOptions {
   theme: Theme;
   source: TranscriptSource;
   done: (result: undefined) => void;
-  wrapText: (text: string, width: number) => string[];
+  cwd: string;
+  markdownTheme: MarkdownTheme;
 }
 
 /**
@@ -68,8 +96,8 @@ export interface TranscriptOverlayOptions {
  * manager, so it stays a reactive consumer with no inbound call into the core.
  */
 export class SessionNavigatorHandler {
-  async handle({ ui, agents, registry }: SessionNavigatorParams): Promise<void> {
-    const entries = listNavigableAgents(agents, registry);
+  async handle({ ui, agents, evicted, registry, cwd, readFile }: SessionNavigatorParams): Promise<void> {
+    const entries = listNavigableAgents(agents, evicted, registry);
     if (entries.length === 0) {
       ui.notify("No subagent sessions to view.", "info");
       return;
@@ -82,10 +110,17 @@ export class SessionNavigatorHandler {
     const entry = entries.find((candidate) => candidate.label === choice);
     if (!entry) return;
 
-    const source = liveSource(entry.record);
+    let source: TranscriptSource;
+    try {
+      source = entry.kind === "live" ? liveSource(entry.record) : fileSnapshotSource(entry.outputFile, readFile);
+    } catch {
+      ui.notify("Could not read the session transcript file.", "error");
+      return;
+    }
+    const markdownTheme = getMarkdownTheme();
     await ui.custom<undefined>(
       (tui, theme, _keybindings, done) =>
-        new TranscriptOverlay({ tui, theme, source, done, wrapText: wrapTextWithAnsi }),
+        new TranscriptOverlay({ tui, theme, source, done, cwd, markdownTheme }),
       {
         overlay: true,
         overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
@@ -97,9 +132,11 @@ export class SessionNavigatorHandler {
 /**
  * Read-only scrollable transcript overlay.
  *
- * Re-renders on every source update (live agents); the transcript text is Pi's
- * `serializeConversation` output from `renderTranscriptLines` — this class owns
- * only scroll state and chrome, no message formatting.
+ * Caches a `Container` of Pi's per-entry components and rebuilds it only when the
+ * source changes (live agents) — each paint reuses the cached tree, so markdown
+ * highlighting does not re-run per frame. This class owns scroll state, chrome,
+ * and the running-agent streaming indicator; the component mapping lives in
+ * `buildTranscriptComponents`.
  */
 export class TranscriptOverlay implements Component {
   private scrollOffset = 0;
@@ -111,16 +148,21 @@ export class TranscriptOverlay implements Component {
   private readonly theme: Theme;
   private readonly source: TranscriptSource;
   private readonly done: (result: undefined) => void;
-  private readonly wrapText: (text: string, width: number) => string[];
+  private readonly cwd: string;
+  private readonly markdownTheme: MarkdownTheme;
+  private content: Container;
 
-  constructor({ tui, theme, source, done, wrapText }: TranscriptOverlayOptions) {
+  constructor({ tui, theme, source, done, cwd, markdownTheme }: TranscriptOverlayOptions) {
     this.tui = tui;
     this.theme = theme;
     this.source = source;
     this.done = done;
-    this.wrapText = wrapText;
+    this.cwd = cwd;
+    this.markdownTheme = markdownTheme;
+    this.content = this.rebuild();
     this.unsubscribe = source.subscribe(() => {
       if (this.closed) return;
+      this.content = this.rebuild();
       this.tui.requestRender();
     });
   }
@@ -199,7 +241,7 @@ export class TranscriptOverlay implements Component {
 
   // fallow-ignore-next-line unused-class-member
   invalidate(): void {
-    /* no cached state to clear */
+    this.content.invalidate();
   }
 
   // fallow-ignore-next-line unused-class-member
@@ -224,14 +266,139 @@ export class TranscriptOverlay implements Component {
 
   private buildContentLines(innerW: number): string[] {
     if (innerW <= 0) return [];
-    const wrapped: string[] = [];
-    for (const line of renderTranscriptLines(this.source)) {
-      if (line === "") {
-        wrapped.push("");
-        continue;
+    const lines = this.content.render(innerW);
+    const streaming = this.source.streaming();
+    if (streaming) {
+      lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
+    }
+    return lines.map((l) => truncateToWidth(l, innerW));
+  }
+
+  private rebuild(): Container {
+    return buildTranscriptComponents(this.source.getMessages(), {
+      tui: this.tui,
+      cwd: this.cwd,
+      markdownTheme: this.markdownTheme,
+      getToolDefinition: (name) => this.source.getToolDefinition(name),
+    });
+  }
+}
+
+/** Dependencies the per-entry component tree needs from the SDK/TUI environment. */
+interface TranscriptRenderOptions {
+  tui: TUI;
+  cwd: string;
+  markdownTheme: MarkdownTheme;
+  getToolDefinition: (name: string) => ToolDefinition | undefined;
+}
+
+/**
+ * Build a `Container` of Pi's per-entry components from a message snapshot,
+ * mirroring Pi's own interactive-mode `renderSessionContext` mapping. Tool
+ * results are matched to their tool-call components by id, exactly as Pi does.
+ * `custom`-role messages are skipped — rendering them needs the child session's
+ * message-renderer registry, which the navigator does not hold.
+ */
+function buildTranscriptComponents(
+  messages: readonly SessionMessage[],
+  opts: TranscriptRenderOptions,
+): Container {
+  const container = new Container();
+  const pendingTools = new Map<string, ToolExecutionComponent>();
+  for (const message of messages) {
+    addMessageComponents(container, message, pendingTools, opts);
+  }
+  return container;
+}
+
+function addMessageComponents(
+  container: Container,
+  message: SessionMessage,
+  pendingTools: Map<string, ToolExecutionComponent>,
+  opts: TranscriptRenderOptions,
+): void {
+  switch (message.role) {
+    case "assistant": {
+      container.addChild(new AssistantMessageComponent(message, false, opts.markdownTheme));
+      for (const content of message.content) {
+        if (content.type !== "toolCall") continue;
+        const tool = new ToolExecutionComponent(
+          content.name,
+          content.id,
+          content.arguments,
+          { showImages: false },
+          opts.getToolDefinition(content.name),
+          opts.tui,
+          opts.cwd,
+        );
+        tool.setExpanded(true);
+        container.addChild(tool);
+        pendingTools.set(content.id, tool);
       }
-      wrapped.push(...this.wrapText(line, innerW));
+      break;
+    }
+    case "toolResult": {
+      pendingTools.get(message.toolCallId)?.updateResult(message);
+      pendingTools.delete(message.toolCallId);
+      break;
+    }
+    case "user": {
+      addUserComponents(container, message.content, opts.markdownTheme);
+      break;
+    }
+    case "bashExecution": {
+      const bash = new BashExecutionComponent(message.command, opts.tui, message.excludeFromContext);
+      if (message.output) bash.appendOutput(message.output);
+      bash.setComplete(message.exitCode, message.cancelled, undefined, message.fullOutputPath);
+      container.addChild(bash);
+      break;
+    }
+    case "compactionSummary": {
+      container.addChild(new Spacer(1));
+      const summary = new CompactionSummaryMessageComponent(message, opts.markdownTheme);
+      summary.setExpanded(true);
+      container.addChild(summary);
+      break;
     }
-    return wrapped.map((l) => truncateToWidth(l, innerW));
+    case "branchSummary": {
+      container.addChild(new Spacer(1));
+      const summary = new BranchSummaryMessageComponent(message, opts.markdownTheme);
+      summary.setExpanded(true);
+      container.addChild(summary);
+      break;
+    }
+  }
+}
+
+/** Render a user message (skill block + text) into the container, mirroring Pi. */
+function addUserComponents(
+  container: Container,
+  content: string | readonly { type: string; text?: string }[],
+  markdownTheme: MarkdownTheme,
+): void {
+  const text = userMessageText(content);
+  if (!text) return;
+  if (container.children.length > 0) 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("");
+}