@gotgenes/pi-subagents 6.11.0 → 6.12.1

package/docs/retro/0133-inject-sdk-boundary-into-agent-runner.md

@@ -0,0 +1,45 @@
+---
+issue: 133
+issue_title: "Inject SDK boundary into `agent-runner`"
+---
+
+# Retro: #133 — Inject SDK boundary into agent-runner
+
+## Final Retrospective (2026-05-22T13:15:00Z)
+
+### Session summary
+
+Injected all SDK and IO dependencies into `runAgent()` via a `RunnerIO` interface and `createAgentRunner(io)` factory.
+Eliminated all 14 `vi.mock()` calls across `agent-runner.test.ts` (7) and `agent-runner-extension-tools.test.ts` (7).
+Released as `pi-subagents-v6.11.0`.
+
+### Observations
+
+#### What went well
+
+- The `createAgentRunner(io)` factory pattern was a clean design choice that kept the `AgentRunner` interface and `AgentManager` completely unchanged — zero downstream impact.
+- Folding plan steps 1 and 2 into a single commit was the right call given `tsconfig.json` includes `test/` — recognized the constraint before attempting a broken intermediate commit.
+
+#### What caused friction (agent side)
+
+1. `wrong-abstraction` — Annotated `createRunnerIO(): RunnerIO` in the test helper, which erased the `Mock<...>` type information from `vi.fn()` stubs.
+   TypeScript then rejected `.mockResolvedValue()` on `io.createSession` across 18 call sites.
+   Required removing the annotation plus a follow-up edit to remove the now-unused `type RunnerIO` import flagged by Biome.
+   Impact: two extra edit rounds and a type-check cycle before the fix landed.
+
+2. `missing-context` — Added `SettingsManager` to the SDK import block in `index.ts` without checking that the name was already imported from `./settings.js`.
+   Biome caught the redeclaration and the `noRedeclare` lint error required an alias fix (`SettingsManager as SdkSettingsManager`).
+   Impact: one extra edit round triggered by the autoformat failure.
+
+3. `premature-convergence` — Spent excessive reasoning time deliberating commit-boundary strategy (whether to combine steps 1+2, how to handle broken intermediate states, whether step 4 would have remaining work).
+   The answer was straightforward once the `tsconfig` `include` was checked, but the check came late in the deliberation.
+   Impact: added friction but no rework — the final decision was correct.
+
+#### What caused friction (user side)
+
+- None identified.
+  The plan and issue were well-specified, and the user's only intervention was "Please, continue" after a message boundary, which was appropriate.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added rule: do not annotate test factory return types with production interface types (erases `Mock<...>` methods).

package/docs/retro/0134-reduce-as-any-casts.md

@@ -0,0 +1,56 @@
+---
+issue: 134
+issue_title: "Reduce `as any` casts in test suite"
+---
+
+# Retro: #134 — Reduce as-any casts in test suite
+
+## Final Retrospective (2026-05-22T17:00:00Z)
+
+### Session summary
+
+Reduced `as any` casts from 93 to 15 across the pi-subagents package.
+Production changes added type guards (`getToolCallName`, `isBashExecution`), narrowed `SubagentRuntime.widget` to `WidgetLike`, typed `CreateSessionOptions.settingsManager` as `SettingsManager`, and fixed `ResourceLoaderOptions.appendSystemPromptOverride` to match the SDK.
+Test improvements introduced `toAgentSession()`, `STUB_CTX`, and `makeRegistry()` helpers to centralise unavoidable bridge casts.
+Also fixed 3 pre-existing lint issues.
+
+This session also included #133 (plan + implement + ship) which preceded the #134 work.
+
+### Observations
+
+#### What went well
+
+- The user's Kent Beck prompt ("make the change that makes the change easy") redirected the plan from test-only fixes to targeted production changes, yielding cleaner results — `WidgetLike`, type guards, and SDK-typed options eliminated casts that would have been impossible to remove from tests alone.
+- The user's TDA observation on the `MenuCtx` step caught a deep architectural issue (context threaded 4 layers just to relay to `buildParentSnapshot`).
+  Skipping step 4 was the right call — attempting it would have added a production cast or cascaded changes through 6+ files.
+
+#### What caused friction (agent side)
+
+1. `rabbit-hole` — Step 1 planning involved extensive analysis of whether `CreateSessionOptions` could use full SDK types.
+   Spent significant reasoning tracing `ModelRegistry` / `SessionManager` private fields, structural compatibility, `ParentSnapshot` constructibility, and `ResourceLoader` interface width before concluding that only `settingsManager` and the callback signature could be fixed.
+   The plan's claim "widen to SDK types" was optimistic about class-with-private-fields constraints.
+   Impact: added friction but no rework — the conclusion was correct, just slow to reach.
+
+2. `wrong-abstraction` — Step 4 (`MenuCtx`) attempted to mechanically narrow the handler parameter without questioning why `ctx` was threaded 4 layers deep.
+   Partially implemented the `MenuCtx` interface before the user's "What am I misunderstanding?"
+   prompt exposed the real issue: a TDA violation where intermediate functions carry `ExtensionContext` only to relay it.
+   Impact: partial implementation reverted via `git checkout src/ui/agent-menu.ts`; ~10 minutes of wasted edits.
+
+3. `instruction-violation` (user-caught) — Used `pnpm exec biome check --write --unsafe` instead of `pnpm run lint:fix` to fix pre-existing lint issues.
+   The `/tdd-plan` prompt explicitly says "run `pnpm run lint:fix`."
+   Impact: no functional difference (same result), but violated the established convention and used an unnecessary `--unsafe` flag.
+
+4. `instruction-violation` (user-caught) — Dismissed pre-existing lint issues as "not from our changes" without fixing them.
+   The user asked "Why do we have pre-existing lint issues?"
+   — the correct action was to fix them immediately rather than noting and ignoring them.
+   Impact: required an extra commit (`style: fix pre-existing lint issues`) that should have been folded into an earlier step.
+
+#### What caused friction (user side)
+
+- The user's interventions on the `MenuCtx` step and lint issues were both valuable redirections that improved the outcome.
+  No mechanical overhead identified — each intervention was strategic judgment that the agent couldn't have reached alone.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — added "Verify green baseline" section (check + lint + test before starting TDD); added "Fix all failures — including pre-existing ones" to the end-of-cycle lint step.
+2. `.pi/prompts/build-plan.md` — same baseline check and fix-all rule for non-TDD plans.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.11.0",
+  "version": "6.12.1",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-runner.ts

@@ -6,6 +6,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import {
   type AgentSession,
   type AgentSessionEvent,
+  type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
@@ -17,6 +18,23 @@ import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
+// ── Local message-shape types ───────────────────────────────────────────────
+// The Pi SDK does not export a narrow type for tool-call content variants.
+
+/** Tool-call content item — SDK exposes this variant at runtime but doesn’t export the narrow type. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+/** Extracts the display name from a tool-call content item. */
+function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName ?? "unknown";
+}
+
 /**
  * Filter the session's active tool names according to extension/denylist rules.
  *
@@ -82,7 +100,8 @@ export interface ResourceLoaderOptions {
   noThemes?: boolean;
   noContextFiles?: boolean;
   systemPromptOverride?: () => string;
-  appendSystemPromptOverride?: () => unknown[];
+  /** Override the append system prompt. Receives the current base value; return the replacement. */
+  appendSystemPromptOverride?: (base: string[]) => string[];
 }
 
 /** Options passed to RunnerIO.createSession. */
@@ -90,7 +109,7 @@ export interface CreateSessionOptions {
   cwd: string;
   agentDir: string;
   sessionManager: SessionManagerLike;
-  settingsManager: unknown;
+  settingsManager: SettingsManager;
   modelRegistry: unknown;
   model?: unknown;
   tools: string[];
@@ -110,7 +129,7 @@ export interface RunnerIO {
   createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
   createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
-  createSettingsManager: (cwd: string, agentDir: string) => unknown;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
   createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
   assemblerIO: AssemblerIO;
 }
@@ -446,9 +465,7 @@ export function getAgentConversation(session: AgentSession): string {
       for (const c of msg.content) {
         if (c.type === "text" && c.text) textParts.push(c.text);
         else if (c.type === "toolCall")
-          toolCalls.push(
-            `  Tool: ${(c as any).name ?? (c as any).toolName ?? "unknown"}`,
-          );
+          toolCalls.push(`  Tool: ${getToolCallName(c)}`);
       }
       if (textParts.length > 0)
         parts.push(`[Assistant]: ${textParts.join("\n")}`);

package/src/index.ts

@@ -136,7 +136,7 @@ export default function (pi: ExtensionAPI) {
   const runnerIO: RunnerIO = {
     detectEnv,
     getAgentDir,
-    createResourceLoader: (opts) => new DefaultResourceLoader(opts as any),
+    createResourceLoader: (opts) => new DefaultResourceLoader(opts),
     deriveSessionDir: deriveSubagentSessionDir,
     createSessionManager: (cwd, dir) => SessionManager.create(cwd, dir),
     createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),

package/src/renderer.ts

@@ -1,6 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import type { NotificationDetails } from "./notification.js";
-import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
+import { formatMs, formatTokens, formatTurns } from "./ui/display.js";
 
 /** Narrow theme interface — only the methods the renderer actually calls. */
 interface RendererTheme {

package/src/runtime.ts

@@ -7,7 +7,19 @@
  */
 
 import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
-import type { AgentWidget, UICtx } from "./ui/agent-widget.js";
+import type { UICtx } from "./ui/agent-widget.js";
+
+/**
+ * Narrow widget interface consumed by SubagentRuntime delegation methods.
+ * AgentWidget satisfies this structurally; tests use plain stubs.
+ */
+export interface WidgetLike {
+  setUICtx(ctx: UICtx): void;
+  onTurnStart(): void;
+  markFinished(id: string): void;
+  update(): void;
+  ensureTimer(): void;
+}
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -37,7 +49,7 @@ export class SubagentRuntime {
    * Persistent widget reference. Null until constructed after AgentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.
    */
-  widget: AgentWidget | null = null;
+  widget: WidgetLike | null = null;
 
   // ── Session-context methods ──────────────────────────────────────────────
 

package/src/tools/agent-tool.ts

@@ -9,6 +9,7 @@ import { resolveInvocationModel } from "../model-resolver.js";
 
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import { type UICtx } from "../ui/agent-widget.js";
 import {
   type AgentDetails,
   buildInvocationTags,
@@ -17,11 +18,10 @@ import {
   getDisplayName,
   getPromptModeLabel,
   SPINNER,
-  type UICtx,
-} from "../ui/agent-widget.js";
+} from "../ui/display.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
-import { buildDetails, buildTypeListText, formatLifetimeTokens, getStatusNote, textResult } from "./helpers.js";
+import { buildDetails, buildTypeListText, textResult } from "./helpers.js";
 
 // ---- Deps interface ----
 

package/src/tools/background-spawner.ts

@@ -2,7 +2,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSpawnConfig } from "../agent-manager.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import type { AgentDetails } from "../ui/agent-widget.js";
+import type { AgentDetails } from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import { textResult } from "./helpers.js";

package/src/tools/foreground-runner.ts

@@ -8,7 +8,7 @@ import {
   describeActivity,
   formatMs,
   SPINNER,
-} from "../ui/agent-widget.js";
+} from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import {

package/src/tools/get-result-tool.ts

@@ -2,7 +2,7 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "../agent-types.js";
 import type { AgentRecord } from "../types.js";
-import { formatDuration, getDisplayName } from "../ui/agent-widget.js";
+import { formatDuration, getDisplayName } from "../ui/display.js";
 import { getSessionContextPercent } from "../usage.js";
 import { formatLifetimeTokens, textResult } from "./helpers.js";
 

package/src/tools/helpers.ts

@@ -1,6 +1,6 @@
 import type { AgentConfigLookup } from "../agent-types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import { type AgentDetails, formatTokens } from "../ui/agent-widget.js";
+import { type AgentDetails, formatTokens } from "../ui/display.js";
 import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
 
 /** Parenthetical status note for completed agent result text. */
@@ -48,7 +48,7 @@ export function buildDetails(
 
 /** Tool execute return value for a text response. */
 export function textResult(msg: string, details?: unknown) {
-  return { content: [{ type: "text" as const, text: msg }], details: details as any };
+  return { content: [{ type: "text" as const, text: msg }], details };
 }
 
 /** Format an agent's lifetime token total, or "" when zero. */

package/src/ui/agent-menu.ts

@@ -10,7 +10,7 @@ import {
 import type { ModelRegistry } from "../model-resolver.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
-import { formatDuration, getDisplayName } from "./agent-widget.js";
+import { formatDuration, getDisplayName } from "./display.js";
 
 // ---- Deps interface ----
 

package/src/ui/agent-widget.ts

@@ -7,40 +7,29 @@
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
-import { type AgentConfigLookup, AgentTypeRegistry } from "../agent-types.js";
-import type { AgentInvocation, SubagentType } from "../types.js";
+import { AgentTypeRegistry } from "../agent-types.js";
+import type { SubagentType } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
+import {
+  describeActivity,
+  ERROR_STATUSES,
+  formatMs,
+  formatSessionTokens,
+  formatTurns,
+  getDisplayName,
+  getPromptModeLabel,
+  SPINNER,
+  type Theme,
+} from "./display.js";
 
 // ---- Constants ----
 
 /** Maximum number of rendered lines before overflow collapse kicks in. */
 const MAX_WIDGET_LINES = 12;
 
-/** 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",
-};
-
 // ---- Types ----
 
-export type Theme = {
-  fg(color: string, text: string): string;
-  bold(text: string): string;
-};
-
 export type UICtx = {
   setStatus(key: string, text: string | undefined): void;
   setWidget(
@@ -50,147 +39,6 @@ export type UICtx = {
   ): void;
 };
 
-/** 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", "isolated"]). */
-  tags?: string[];
-  /** Current turn count. */
-  turnCount?: number;
-  /** Effective max turns (undefined = unlimited). */
-  maxTurns?: number;
-  agentId?: string;
-  error?: string;
-}
-
-// ---- Formatting helpers ----
-
-/** 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;
-  return `${tokenStr} (${annot.join(" · ")})`;
-}
-
-/** 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)`;
-}
-
-/** 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.isolated) tags.push("isolated");
-  if (invocation.isolation === "worktree") tags.push("worktree");
-  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…";
-}
-
 // ---- Widget manager ----
 
 export class AgentWidget {

package/src/ui/conversation-viewer.ts

@@ -12,7 +12,38 @@ import { extractText } from "../context.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
-import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./agent-widget.js";
+import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./display.js";
+
+// ── Local message-shape types ───────────────────────────────────────────────
+// The Pi SDK does not export narrow types for all message content variants.
+// These file-local types document the runtime shapes this module handles.
+
+/** Tool-call content item — SDK exposes this variant at runtime but doesn't export the narrow type. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+/** Extracts the tool name from a content item, falling back to 'unknown'. */
+function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName ?? "unknown";
+}
+
+/** Bash execution message — 'bashExecution' role is not in the SDK's AgentSession message role union. */
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output?: string;
+}
+
+function isBashExecution(msg: { role: string }): msg is BashExecutionMessage {
+  return msg.role === "bashExecution";
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
 
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
@@ -228,7 +259,7 @@ export class ConversationViewer implements Component {
         for (const c of msg.content) {
           if (c.type === "text" && c.text) textParts.push(c.text);
           else if (c.type === "toolCall") {
-            toolCalls.push((c as any).name ?? (c as any).toolName ?? "unknown");
+            toolCalls.push(getToolCallName(c));
           }
         }
         if (needsSeparator) lines.push(th.fg("dim", "───"));
@@ -250,14 +281,13 @@ export class ConversationViewer implements Component {
         for (const line of wrapTextWithAnsi(truncated.trim(), width)) {
           lines.push(th.fg("dim", line));
         }
-      } else if ((msg as any).role === "bashExecution") {
-        const bash = msg as any;
+      } else if (isBashExecution(msg)) {
         if (needsSeparator) lines.push(th.fg("dim", "───"));
-        lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
-        if (bash.output?.trim()) {
-          const out = bash.output.length > 500
-            ? bash.output.slice(0, 500) + "... (truncated)"
-            : bash.output;
+        lines.push(truncateToWidth(th.fg("muted", `  $ ${msg.command}`), width));
+        if (msg.output?.trim()) {
+          const out = msg.output.length > 500
+            ? msg.output.slice(0, 500) + "... (truncated)"
+            : msg.output;
           for (const line of wrapTextWithAnsi(out.trim(), width)) {
             lines.push(th.fg("dim", line));
           }