@esso0428/pi-subagents 0.15.4 → 0.15.6

package/src/ui/fleet-list.ts

@@ -4,7 +4,7 @@
  * Shows `main` + each running/queued subagent as a navigable list. Pressing ↓ (or
  * ←) at an empty prompt activates the list; ↑/↓ move the selection (filled ● marker),
  * Enter opens the selected agent's live conversation overlay, Esc returns to the prompt.
- * A viewer stays open when its agent finishes; finished agents linger briefly in the list.
+ * A viewer stays open when its agent finishes so the final output remains readable.
  *
  * Mechanics (see plan): the list is a `belowEditor` widget (render-only), and ALL key
  * handling goes through `onTerminalInput` — which fires before the focused editor and
@@ -12,22 +12,22 @@
  */
 
 import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AgentManager } from "../agent-manager.js";
-import { hasAgentHistory, readAgentHistory } from "../agent-history.js";
+import { canOpenActiveAgent } from "../agent-history-list.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal } from "../usage.js";
 import { type AgentActivity, getDisplayName, type Theme } from "./agent-widget.js";
-import { ConversationViewer, createStaticConversationSource, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
+import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "./conversation-viewer.js";
 
 /** Widget key for the below-editor fleet list. */
 const FLEET_KEY = "fleet";
-/** Max agent rows shown at once; extras collapse into a "↓ N more" indicator. */
-const MAX_AGENT_ROWS = 5;
+/** Maximum total rows contributed by FleetView, including hint and indicators. */
+export const FLEET_MAX_RENDER_ROWS = 6;
+const FLEET_BASE_ROWS = 2; // hint + main
+const FLEET_BODY_ROWS = FLEET_MAX_RENDER_ROWS - FLEET_BASE_ROWS;
 /** Re-render cadence so elapsed/token stats tick while agents run. */
 const TICK_MS = 200;
-/** How long a finished agent lingers in the list before it drops out. */
-const FINISHED_LINGER_MS = 4000;
-
 /** Minimal UI surface the FleetView needs from `ctx.ui` (structural subset). */
 export type FleetUICtx = {
   setWidget(
@@ -62,6 +62,32 @@ export function formatFleetTokens(count: number): string {
   return `↓ ${compact} tokens`;
 }
 
+/**
+ * Calculate a bounded agent slice for the complete logical roster.
+ * `selectedRosterIndex` includes main at index 0; `end` is exclusive.
+ */
+export function calculateFleetAgentWindow(
+  agentCount: number,
+  selectedRosterIndex: number,
+): { start: number; end: number; hiddenAbove: number; hiddenBelow: number } {
+  const count = Math.max(0, Math.floor(agentCount));
+  if (count === 0) return { start: 0, end: 0, hiddenAbove: 0, hiddenBelow: 0 };
+
+  const selectedAgent = Math.min(
+    count - 1,
+    Math.max(0, Math.floor(selectedRosterIndex) - 1),
+  );
+  const reserveAbove = selectedAgent > 0 ? 1 : 0;
+  const reserveBelow = selectedAgent < count - 1 ? 1 : 0;
+  const visibleCount = Math.max(1, FLEET_BODY_ROWS - reserveAbove - reserveBelow);
+  const start = Math.min(
+    Math.max(0, selectedAgent - visibleCount + 1),
+    Math.max(0, count - visibleCount),
+  );
+  const end = Math.min(count, start + visibleCount);
+  return { start, end, hiddenAbove: start, hiddenBelow: count - end };
+}
+
 /**
  * Place `right` flush to `width`, truncating `left` first so the stats survive.
  * The final clamp guarantees the line never exceeds `width` (which would wrap and
@@ -80,6 +106,7 @@ export class FleetList {
   private tui: any | undefined;
   private inputUnsub: (() => void) | undefined;
   private widgetRegistered = false;
+  private lastRosterKey: string | undefined;
   private timer: ReturnType<typeof setInterval> | undefined;
 
   private enabled = true;
@@ -95,6 +122,8 @@ export class FleetList {
     private manager: AgentManager,
     private agentActivity: Map<string, AgentActivity>,
     private getCwd: () => string | undefined = () => undefined,
+    private pi?: ExtensionAPI,
+    private getCtx: () => ExtensionContext | undefined = () => undefined,
   ) {}
 
   // ---- Lifecycle ----
@@ -112,6 +141,7 @@ export class FleetList {
     this.inputUnsub?.();
     this.ui = ui;
     this.widgetRegistered = false;
+    this.lastRosterKey = undefined;
     this.tui = undefined;
     this.inputUnsub = ui.onTerminalInput(data => this.handleKey(data));
   }
@@ -123,7 +153,7 @@ export class FleetList {
 
   /**
    * Called when an agent finishes. The viewer (if open on it) stays open so the
-   * final output remains readable, and the row lingers in the list — just refresh.
+   * final output remains readable; refresh the active-only roster.
    */
   onAgentFinished(_id: string): void {
     this.update();
@@ -137,6 +167,7 @@ export class FleetList {
     this.viewingAgentId = undefined;
     if (this.ui && this.widgetRegistered) this.ui.setWidget(FLEET_KEY, undefined);
     this.widgetRegistered = false;
+    this.lastRosterKey = undefined;
     this.tui = undefined;
     this.active = false;
     // Null last so a `viewerClose()` microtask above can't re-register the widget.
@@ -146,7 +177,11 @@ export class FleetList {
   /** Re-register/refresh the below-editor widget; clears it when no agents remain. */
   update(): void {
     if (!this.ui) return;
-    const hasAgents = this.enabled && this.agentRecords().length > 0;
+    const records = this.agentRecords();
+    const hasAgents = this.enabled && records.length > 0;
+    const rosterKey = records.map(record => record.id).join("\0");
+    const rosterChanged = rosterKey !== this.lastRosterKey;
+    this.lastRosterKey = rosterKey;
 
     if (!hasAgents) {
       if (this.widgetRegistered) {
@@ -157,6 +192,7 @@ export class FleetList {
       if (this.timer) { clearInterval(this.timer); this.timer = undefined; }
       this.active = false;
       this.selectedIndex = 0;
+      this.lastRosterKey = undefined;
       return;
     }
 
@@ -173,35 +209,21 @@ export class FleetList {
       }, { placement: "belowEditor" });
       this.widgetRegistered = true;
     } else {
-      this.tui?.requestRender();
+      this.tui?.requestRender(rosterChanged);
     }
   }
 
   // ---- Roster ----
 
   /**
-   * Agents shown in the list, ordered earliest-launched first so the ones you
-   * started sooner sit at the top. Live rows are openable through their session;
-   * terminal rows are included only when their durable transcript exists. This
-   * prevents Enter from dead-ending on stale rehydrated metadata.
-   * Included: running/queued, plus the agent currently being viewed, plus
-   * recently-finished ones (they linger briefly before dropping out).
-   * Pending agents with no session yet are hidden until they start.
-   * (`listAgents()` is newest-first, so we re-sort.)
+   * Active agents shown in the list, ordered earliest-launched first so the
+   * ones you started sooner sit at the top. Pending agents with no session yet
+   * are hidden until they start. (`listAgents()` is newest-first, so we
+   * re-sort.)
    */
   private agentRecords(): AgentRecord[] {
-    const now = Date.now();
     return this.manager.listAgents()
-      .filter(a => {
-        const live = a.session && (
-          a.status === "running" || a.status === "queued"
-          || a.id === this.viewingAgentId
-          || (a.completedAt != null && now - a.completedAt < FINISHED_LINGER_MS)
-        );
-        const cwd = this.getCwd();
-        const history = cwd !== undefined && hasAgentHistory(cwd, a.transcriptPath);
-        return !!live || history;
-      })
+      .filter(record => canOpenActiveAgent(record))
       .sort((a, b) => a.startedAt - b.startedAt);
   }
 
@@ -296,18 +318,18 @@ export class FleetList {
     }
     const record = entry.record;
     if (!this.ui) return;
-    const session = record.session ?? (record.transcriptPath && this.getCwd()
-      ? (() => {
-          const messages = readAgentHistory(this.getCwd()!, record.transcriptPath!);
-          return messages ? createStaticConversationSource(messages) : undefined;
-        })()
-      : undefined);
-    if (!session) {
-      this.ui.notify(`Agent is ${record.status} — no history available.`, "info");
+    if (!canOpenActiveAgent(record) || !record.session) {
+      this.ui.notify(`Agent is ${record.status} — no live session available.`, "info");
+      return;
+    }
+    const session = record.session;
+    const ctx = this.getCtx();
+    const pi = this.pi;
+    if (!ctx || !pi) {
+      this.ui.notify("Agent conversation is unavailable — no active session.", "info");
       return;
     }
     const activity = this.agentActivity.get(record.id);
-    const isLive = record.session !== undefined;
     this.viewingAgentId = record.id;
 
     void this.ui.custom<undefined>(
@@ -320,11 +342,12 @@ export class FleetList {
           activity,
           theme,
           done,
-          isLive ? () => {
+          () => {
             if (this.manager.abort(record.id)) this.ui?.notify(`Stopped "${record.description}".`, "info");
-          } : undefined,
+          },
           keybindings,
-          isLive ? (message: string) => this.manager.steer(record.id, message) : undefined,
+          (message: string) => this.manager.steer(record.id, message),
+          { pi, ctx, readOnly: false },
         );
       },
       {
@@ -363,20 +386,18 @@ export class FleetList {
       : "esc to interrupt · ← for agents · ↓ to manage";
     const lines: string[] = [];
     lines.push(truncateToWidth("  " + theme.fg("dim", hint), width));
-    lines.push("");
     lines.push(truncateToWidth(`  ${this.bullet(0, sel, theme)} main`, width));
 
-    // Window the agent rows so the selected one stays visible.
-    const visible = Math.min(MAX_AGENT_ROWS, agents.length);
-    const selAgent = Math.max(0, sel - 1);
-    const start = selAgent < visible ? 0 : selAgent - visible + 1;
-    const hiddenBelow = agents.length - (start + visible);
-
-    if (start > 0) lines.push(rightAlign("", theme.fg("dim", `↑ ${start} more`), width));
-    for (let a = start; a < start + visible; a++) {
+    const window = calculateFleetAgentWindow(agents.length, sel);
+    if (window.hiddenAbove > 0) {
+      lines.push(rightAlign("", theme.fg("dim", `↑ ${window.hiddenAbove} more`), width));
+    }
+    for (let a = window.start; a < window.end; a++) {
       lines.push(this.renderAgentRow(a + 1, sel, agents[a].record, width, theme));
     }
-    if (hiddenBelow > 0) lines.push(rightAlign("", theme.fg("dim", `↓ ${hiddenBelow} more`), width));
+    if (window.hiddenBelow > 0) {
+      lines.push(rightAlign("", theme.fg("dim", `↓ ${window.hiddenBelow} more`), width));
+    }
 
     return lines;
   }

package/test/agent-history-list.test.ts

@@ -0,0 +1,121 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  buildAgentStatusMenuEntries,
+  canOpenActiveAgent,
+  canOpenAgentHistory,
+  formatAgentHistoryOption,
+  isTerminalAgentStatus,
+  splitAgentRecords,
+} from "../src/agent-history-list.js";
+
+type TestRecord = {
+  status: string;
+  session?: object;
+  transcriptPath?: string;
+  type?: string;
+  description?: string;
+  startedAt?: number;
+  completedAt?: number;
+};
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of tempDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function record(overrides: TestRecord): any {
+  return {
+    id: "agent-1",
+    type: "Explore",
+    description: "Inspect the repository",
+    status: "completed",
+    toolUses: 0,
+    startedAt: 1_000,
+    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
+    compactionCount: 0,
+    ...overrides,
+  };
+}
+
+describe("agent history list helpers", () => {
+  it("recognizes exactly the five terminal statuses", () => {
+    for (const status of ["completed", "steered", "stopped", "aborted", "error"]) {
+      expect(isTerminalAgentStatus(status)).toBe(true);
+    }
+    for (const status of ["running", "queued", "unknown", ""]) {
+      expect(isTerminalAgentStatus(status)).toBe(false);
+    }
+  });
+
+  it("separates active and terminal records without mutating input", () => {
+    const done = record({ status: "completed", session: {} });
+    const running = record({ status: "running", session: {} });
+    const stopped = record({ status: "stopped", session: {} });
+    const queued = record({ status: "queued", session: {} });
+    const input = [done, running, stopped, queued];
+    const before = [...input];
+
+    const result = splitAgentRecords(input, undefined);
+
+    expect(result.active).toEqual([running, queued]);
+    expect(result.history).toEqual([done, stopped]);
+    expect(input).toEqual(before);
+    expect(input).toEqual([done, running, stopped, queued]);
+  });
+
+  it("requires a session or existing transcript for history", () => {
+    expect(canOpenAgentHistory(record({ session: undefined }), undefined)).toBe(false);
+    expect(canOpenAgentHistory(record({ session: {} }), undefined)).toBe(true);
+    expect(canOpenAgentHistory(record({ status: "running", session: {} }), undefined)).toBe(false);
+    expect(canOpenActiveAgent(record({ status: "running", session: {} }))).toBe(true);
+    expect(canOpenActiveAgent(record({ status: "queued", session: undefined }))).toBe(false);
+    expect(canOpenActiveAgent(record({ status: "completed", session: {} }))).toBe(false);
+  });
+
+  it("opens history only for an existing project-local transcript", () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-subagents-history-list-"));
+    tempDirectories.push(cwd);
+    const transcriptPath = ".pi-subagents/agent-transcripts/agent.jsonl";
+    mkdirSync(join(cwd, ".pi-subagents", "agent-transcripts"), { recursive: true });
+    const historical = record({ session: undefined, transcriptPath });
+
+    expect(canOpenAgentHistory(historical, cwd)).toBe(false);
+    writeFileSync(join(cwd, transcriptPath), "{}\n");
+    expect(canOpenAgentHistory(historical, cwd)).toBe(true);
+    expect(canOpenAgentHistory(historical, undefined)).toBe(false);
+  });
+
+  it("builds separate menu entries with openable records only", () => {
+    const entries = buildAgentStatusMenuEntries([
+      record({ status: "running", session: {} }),
+      record({ status: "queued", session: undefined }),
+      record({ status: "completed", session: {} }),
+      record({ status: "error", session: {} }),
+      record({ status: "stopped", session: undefined }),
+    ], undefined);
+
+    expect(entries).toEqual(["Running agents (1)", "Agent history (2)"]);
+    expect(buildAgentStatusMenuEntries([record({ status: "queued", session: undefined })], undefined)).toEqual([]);
+  });
+
+  it("formats a bounded history option using the display name and duration", () => {
+    const option = formatAgentHistoryOption(record({
+      status: "completed",
+      type: "Explore",
+      description: "A very long description ".repeat(20),
+      startedAt: 1_000,
+      completedAt: 3_000,
+    }), 9_000);
+
+    expect(option).toContain("[completed]");
+    expect(option).toContain("Explore");
+    expect(option).toContain("2.0s");
+    expect(option.length).toBeLessThanOrEqual(140);
+  });
+});

package/test/agent-manager-history.test.ts

@@ -1,87 +1,88 @@
 import { afterEach, describe, expect, it } from "vitest";
 import { AgentManager } from "../src/agent-manager.js";
 
-type PersistedRecord = {
-  id: string;
-  type: string;
-  description: string;
-  status: string;
-  result?: unknown;
-  error?: unknown;
-  startedAt: number;
-  completedAt: number;
-  transcriptPath?: string;
-};
+const managers: AgentManager[] = [];
 
-function persisted(overrides: Partial<PersistedRecord> = {}): PersistedRecord {
+afterEach(() => {
+  for (const manager of managers.splice(0)) manager.dispose();
+});
+
+function makeManager(): AgentManager {
+  const manager = new AgentManager();
+  managers.push(manager);
+  return manager;
+}
+
+function record(overrides: Record<string, unknown> = {}) {
   return {
     id: "agent-1",
-    type: "general-purpose",
-    description: "history test",
+    type: "Explore",
+    description: "Inspect the repository",
     status: "completed",
-    result: "restored result",
-    startedAt: 100,
-    completedAt: 200,
+    result: "done",
+    toolUses: 2,
+    startedAt: 1_000,
+    completedAt: 2_000,
     ...overrides,
   };
 }
 
 describe("AgentManager.restoreCompleted", () => {
-  let manager: AgentManager | undefined;
+  it("restores all five terminal statuses without sessions", () => {
+    const manager = makeManager();
+    manager.restoreCompleted(["completed", "steered", "stopped", "aborted", "error"].map((status, i) =>
+      record({ id: `agent-${i}`, status }),
+    ));
 
-  afterEach(() => {
-    manager?.dispose();
-    manager = undefined;
+    expect(manager.listAgents()).toHaveLength(5);
+    for (const restored of manager.listAgents()) {
+      expect(["completed", "steered", "stopped", "aborted", "error"]).toContain(restored.status);
+      expect(restored.session).toBeUndefined();
+      expect(restored.abortController).toBeUndefined();
+      expect(restored.promise).toBeUndefined();
+      expect(restored.lifetimeUsage).toEqual({ input: 0, output: 0, cacheWrite: 0 });
+      expect(restored.compactionCount).toBe(0);
+    }
   });
 
-  it("restores terminal records without creating live runtime state", () => {
-    manager = new AgentManager();
-
+  it("ignores running, queued, and invalid records", () => {
+    const manager = makeManager();
     manager.restoreCompleted([
-      persisted(),
-      persisted({ id: "agent-error", status: "error", error: "failed", transcriptPath: ".pi-subagents/agent-transcripts/agent-error.jsonl" }),
-      persisted({ id: "agent-running", status: "running" }),
-      persisted({ id: "agent-queued", status: "queued" }),
-      persisted({ id: "agent-invalid", completedAt: Number.NaN }),
-      persisted({ id: "agent-unsafe", transcriptPath: ".pi-subagents/../private.jsonl" }),
+      record({ id: "running", status: "running" }),
+      record({ id: "queued", status: "queued" }),
+      { id: "invalid" },
     ]);
 
-    expect(manager.listAgents().map((record) => record.id).sort()).toEqual([
-      "agent-1",
-      "agent-error",
-    ]);
-    const restored = manager.getRecord("agent-1");
-    expect(restored).toMatchObject({
-      status: "completed",
-      result: "restored result",
-      toolUses: 0,
-      lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
-      compactionCount: 0,
-      isBackground: true,
-      transcriptPath: undefined,
-    });
-    expect(restored?.session).toBeUndefined();
-    expect(restored?.promise).toBeUndefined();
-    expect(restored?.abortController).toBeUndefined();
+    expect(manager.listAgents()).toEqual([]);
   });
 
-  it("uses the newest branch entry when an id appears more than once", () => {
-    manager = new AgentManager();
-
+  it("keeps the last valid duplicate input", () => {
+    const manager = makeManager();
     manager.restoreCompleted([
-      persisted({ result: "old", completedAt: 200 }),
-      persisted({ result: "new", completedAt: 300 }),
+      record({ result: "first", startedAt: 1_000, completedAt: 1_100 }),
+      record({ result: "last", startedAt: 2_000, completedAt: 2_100 }),
     ]);
 
-    expect(manager.getRecord("agent-1")?.result).toBe("new");
+    expect(manager.getRecord("agent-1")?.result).toBe("last");
+    expect(manager.getRecord("agent-1")?.startedAt).toBe(2_000);
   });
 
-  it("does not overwrite a record already held by the manager", () => {
-    manager = new AgentManager();
+  it("does not replace a live record and rejects unsafe persisted data", () => {
+    const manager = makeManager();
+    // Exercise the public map through a restored terminal, then make it live
+    // without starting an LLM session.
+    manager.restoreCompleted([record({ id: "live", result: "original" })]);
+    const liveRecord = manager.getRecord("live")!;
+    liveRecord.status = "running";
 
-    manager.restoreCompleted([persisted({ result: "first" })]);
-    manager.restoreCompleted([persisted({ result: "second" })]);
+    manager.restoreCompleted([
+      record({ id: "live", result: "replacement" }),
+      record({ id: "bad-time", startedAt: Number.NaN }),
+      record({ id: "bad-path", transcriptPath: "../../outside.jsonl" }),
+    ]);
 
-    expect(manager.getRecord("agent-1")?.result).toBe("first");
+    expect(manager.getRecord("live")?.result).toBe("original");
+    expect(manager.getRecord("bad-time")).toBeUndefined();
+    expect(manager.getRecord("bad-path")).toBeUndefined();
   });
 });

package/test/agent-menu-history-navigation.test.ts

@@ -0,0 +1,86 @@
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import extension from "../src/index.js";
+import { agentHistoryLocator } from "../src/agent-history.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  for (const directory of tempDirectories.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+describe("/agents history navigation", () => {
+  it("returns to the Agents menu after closing a history viewer", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-subagents-menu-test-"));
+    tempDirectories.push(cwd);
+    const transcript = ".pi-subagents/agent-transcripts/agent-1.jsonl";
+    mkdirSync(join(cwd, ".pi-subagents/agent-transcripts"), { recursive: true });
+    writeFileSync(join(cwd, transcript), JSON.stringify({ message: { role: "user", content: "hello" } }) + "\n");
+
+    const eventHandlers = new Map<string, Set<(...args: any[]) => any>>();
+    const events = {
+      on: (name: string, handler: (...args: any[]) => any) => {
+        const handlersForEvent = eventHandlers.get(name) ?? new Set<(...args: any[]) => any>();
+        handlersForEvent.add(handler);
+        eventHandlers.set(name, handlersForEvent);
+        return () => handlersForEvent.delete(handler);
+      },
+      emit: (name: string, ...args: any[]) => {
+        for (const handler of eventHandlers.get(name) ?? []) handler(...args);
+      },
+    };
+    const handlers = new Map<string, (...args: any[]) => any>();
+    let command: { handler: (_args: unknown, ctx: any) => Promise<void> } | undefined;
+    const pi: any = {
+      events,
+      registerMessageRenderer: () => {},
+      registerTool: () => {},
+      registerCommand: (_name: string, definition: typeof command) => { command = definition; },
+      on: (name: string, handler: (...args: any[]) => any) => { handlers.set(name, handler); },
+      appendEntry: () => {},
+      sendMessage: () => {},
+    };
+    extension(pi);
+
+    const titles: string[] = [];
+    let historySelections = 0;
+    const ui = {
+      notify: () => {},
+      setWidget: () => {},
+      setStatus: () => {},
+      onTerminalInput: () => () => {},
+      select: async (title: string, options: string[]) => {
+        titles.push(title);
+        if (title === "Agents" && titles.filter(item => item === "Agents").length === 1) {
+          return options.find(option => option.startsWith("Agent history ("));
+        }
+        if (title === "Agent history" && historySelections++ === 0) return options[0];
+        return undefined;
+      },
+      custom: async () => undefined,
+    };
+    const ctx = {
+      cwd,
+      ui,
+      sessionManager: {
+        getSessionId: () => undefined,
+        getBranch: () => [{
+          type: "custom",
+          customType: "subagents:record",
+          data: {
+            id: "agent-1", type: "Explore", description: "Inspect", status: "completed",
+            startedAt: 1, completedAt: 2, transcriptPath: agentHistoryLocator(cwd, join(cwd, transcript)),
+          },
+        }],
+      },
+    };
+
+    await handlers.get("session_start")?.({}, ctx);
+    await command?.handler({}, ctx);
+    await handlers.get("session_shutdown")?.();
+
+    expect(titles).toEqual(["Agents", "Agent history", "Agents"]);
+  });
+});

package/test/ui/conversation-blocks.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { formatConversationMessages } from "../../src/ui/conversation-blocks.js";
+
+describe("formatConversationMessages", () => {
+  it("keeps markdown source for user and assistant blocks", () => {
+    const blocks = formatConversationMessages([
+      { role: "user", content: "# Ask\n\nUse `x`." },
+      { role: "assistant", content: [
+        { type: "text", text: "## Answer\n\n```ts\nconst x: number = 1;\n```" },
+      ] },
+    ] as any);
+
+    expect(blocks.filter((b) => b.kind === "text").map((b) => b.markdown)).toEqual([
+      "# Ask\n\nUse `x`.",
+      "## Answer\n\n```ts\nconst x: number = 1;\n```",
+    ]);
+  });
+
+  it("separates assistant tool calls and bounds tool results", () => {
+    const blocks = formatConversationMessages([
+      { role: "assistant", content: [
+        { type: "toolCall", name: "read", arguments: { path: "src/index.ts" } },
+      ] },
+      { role: "toolResult", toolName: "read", isError: false, content: [
+        { type: "text", text: "a".repeat(100) },
+      ] },
+    ] as any, { maxToolResultChars: 40 });
+
+    expect(blocks.some((b) => b.toolLine?.includes("read"))).toBe(true);
+    const result = blocks.find((b) => b.role === "tool" && b.fullText.includes("read"));
+    expect(result?.fullText.length).toBeLessThanOrEqual(40);
+  });
+
+  it("normalizes CRLF and bounds text with a deterministic truncation marker", () => {
+    const blocks = formatConversationMessages([
+      { role: "user", content: "one\r\ntwo\rthree\nfour" },
+    ] as any, { maxEntryChars: 12 });
+
+    expect(blocks[0]?.markdown).toBe("\n… [truncate");
+    expect(blocks[0]?.id).toBe("message-0");
+    expect(blocks[0]?.fullText.length).toBeLessThanOrEqual(12);
+  });
+
+  it("formats bash, images, summaries, and deterministic tool ids", () => {
+    const blocks = formatConversationMessages([
+      { role: "assistant", content: [
+        { type: "text", text: "answer" },
+        { type: "toolCall", name: "read", arguments: { path: "a.ts" } },
+        { type: "toolCall", name: "write", arguments: { path: "b.ts" } },
+      ] },
+      { role: "bashExecution", command: "echo hi", output: "hi" },
+      { role: "custom", customType: "note", content: [{ type: "image" }] },
+      { role: "compactionSummary", summary: "Earlier context" },
+    ] as any);
+
+    expect(blocks.map((block) => block.id)).toEqual([
+      "message-0", "message-0-tool-0", "message-0-tool-1", "message-1", "message-2", "message-3",
+    ]);
+    expect(blocks[1]?.toolLine).toContain("· read → a.ts");
+    expect(blocks[3]?.fullText).toContain("$ echo hi\nhi");
+    expect(blocks[4]?.markdown).toBe("[image]");
+    expect(blocks[5]?.role).toBe("meta");
+  });
+
+  it("skips unsupported or empty messages without throwing", () => {
+    expect(formatConversationMessages([
+      { role: "unknown", content: { not: "text" } },
+      { role: "user", content: [{ type: "thinking", thinking: "hidden" }] },
+      { role: "custom", display: false, content: "hidden" },
+    ] as any)).toEqual([]);
+  });
+});