@zhushanwen/pi-subagent-workflow 0.1.0

package/src/interface/views/detail-content.ts

@@ -0,0 +1,298 @@
+/**
+ * L2 详情内容构建 + 滚动按键处理（纯函数）。
+ *
+ * 从 WorkflowsView.ts 抽出，目的：
+ *   1. 把 WorkflowsView.ts 控制在 1000 行以内（行数检查 hook）
+ *   2. buildDetailContent / detailContentLength / processDetailKey 为导出纯函数，
+ *      无 Pi runtime 依赖，可直接单测（对齐 subagents list-view 的 processKey 模式）
+ *
+ * 单一数据源：renderLevel2 渲染与 detailContentLength 算行数都走 buildDetailContent，
+ * 避免两者发散（对齐 subagents buildDetailContent / detailContentLength）。
+ */
+
+import { Key, matchesKey } from "@mariozechner/pi-tui";
+
+import { getAllToolCalls, projectLiveProgress } from "../../execution/execution-record.ts";
+import type { AgentEventLogEntry } from "../../execution/types.ts";
+import type { ExecutionTraceNode } from "../../orchestration/models/types.ts";
+import type { WorkflowRun } from "../../orchestration/models/workflow-run.ts";
+import {
+  BOX_BORDER_CHARS,
+  BUDGET_TOKENS_DIVISOR,
+  ELLIPSIS,
+  formatActivityLine,
+  formatElapsed,
+  formatElapsedSeconds,
+  formatEventLine,
+  formatTokenStat,
+  MAX_TOOL_CALLS_DISPLAY,
+  OUTPUT_TRUNCATE_BYTES,
+  PAGE_SCROLL_DEFAULT,
+  PROMPT_FOLD_LINES,
+  statusDotStr,
+  type ThemeLike,
+} from "./format.ts";
+
+// ── 共享常量（BOX_BORDER_CHARS / BUDGET_TOKENS_DIVISOR / MAX_TOOL_CALLS_DISPLAY
+//    已上移到 format.ts，供 WorkflowsView + detail-content 共用，避免重复定义）──
+
+/** 探测宽度：足够大避免截断折行影响行数统计（对齐 subagents DETAIL_LEN_PROBE_WIDTH）。 */
+const DETAIL_LEN_PROBE_WIDTH = 9999;
+
+/** status → 语义色标签（L2 detail 头用）。 */
+export function statusLabel(status: string, theme: ThemeLike): string {
+  switch (status) {
+    case "completed": return theme.fg("success", status);
+    case "running": return theme.fg("warning", status);
+    case "failed": return theme.fg("error", status);
+    default: return theme.fg("muted", status);
+  }
+}
+
+// ── L2 详情内容构建（单一数据源）──────────────────────────────────
+
+/**
+ * 构建 L2 右侧详情的完整内容行。
+ *
+ * 纯函数：无 Pi runtime、无副作用，可单测。入参 promptExpanded 用结构化类型，
+ * 不依赖完整 ViewState（便于测试构造）。
+ */
+export function buildDetailContent(
+  node: ExecutionTraceNode,
+  state: { promptExpanded: boolean },
+  run: WorkflowRun,
+  theme: ThemeLike,
+  mainWidth: number,
+  now: number,
+): string[] {
+  const rightLines: string[] = [];
+  const elapsed = formatElapsed(
+    node.startedAt,
+    node.completedAt ? new Date(node.completedAt).getTime() : now,
+  );
+  rightLines.push(theme.fg("muted", "Detail"));
+  rightLines.push("─".repeat(mainWidth));
+  rightLines.push(`${statusDotStr(node.status, theme)} ${statusLabel(node.status, theme)} · ${node.model}`);
+  // Live 路径优先：运行中用 node.live 的实时 usage/toolCalls/elapsed；否则用终态 result。
+  if (node.live) {
+    const live = projectLiveProgress(node.live);
+    const tokK = live.totalTokens > 0 ? `${Math.round(live.totalTokens / BUDGET_TOKENS_DIVISOR)}k tok` : "0 tok";
+    const tcCount = getAllToolCalls(node.live).length;
+    rightLines.push(theme.fg("dim", `${tokK} · ${tcCount} tool calls · ${formatElapsedSeconds(live.elapsedSeconds)}`));
+  } else {
+    rightLines.push(theme.fg("dim", formatTokenStat(node.result?.usage, node.result?.toolCalls, elapsed)));
+  }
+  rightLines.push("");
+  renderWorkerLogSection(rightLines, run, mainWidth, theme);
+  renderPromptSection(rightLines, node, state, theme);
+  renderActivitySection(rightLines, node, mainWidth, theme);
+  renderOutcomeSection(rightLines, node, mainWidth, theme);
+  return rightLines;
+}
+
+/** L2 详情内容总行数（供 processDetailKey 算 max，不重复生成内容）。 */
+export function detailContentLength(
+  node: ExecutionTraceNode,
+  state: { promptExpanded: boolean },
+  run: WorkflowRun,
+  theme: ThemeLike,
+): number {
+  return buildDetailContent(node, state, run, theme, DETAIL_LEN_PROBE_WIDTH, Date.now()).length;
+}
+
+// ── L2 详情滚动按键（纯函数，对齐 subagents processKey）─────────
+
+/** 详情翻屏上下文：视口高 + 内容总行数 + 是否 running（驱动 followTail）。 */
+export interface DetailScrollContext {
+  /** 右侧 detail 可见行数（render 的 viewH，单一数据源）。 */
+  viewportHeight: number;
+  /** buildDetailContent 总行数。 */
+  contentLines: number;
+  /** node.status === "running"（决定 followTail 语义）。 */
+  isRunning: boolean;
+}
+
+/** 滚动按键处理结果（纯数据，调用方回写 state）。 */
+export interface DetailKeyResult {
+  /** 新的滚动 offset（已 clamp 到 [0, max]）。 */
+  scrollOffset: number;
+  /** 是否继续"钉底部"（running 态自动跟随最新输出）。 */
+  followTail: boolean;
+  /** 是否命中滚动键（false → 调用方回退到 up/down/enter 等现有逻辑）。 */
+  handled: boolean;
+}
+
+/**
+ * 处理 L2 详情滚动按键（PgUp/PgDn/Home/End）。
+ *
+ *   - PgUp  → offset -= viewportHeight，followTail=false（用户主动上滚，停止跟随）
+ *   - PgDn  → offset += viewportHeight；到底则 followTail=true
+ *   - Home  → offset=0，followTail=false
+ *   - End   → offset=max，followTail=true
+ *   - 其他  → handled=false（交回 handleInput 现有逻辑）
+ *
+ * max = max(0, contentLines - viewportHeight)。纯函数：入参 data + state + ctx，
+ * 无副作用、无 Pi 依赖，可直接单测（对齐 subagents processKey）。
+ */
+export function processDetailKey(
+  data: string,
+  state: { scrollOffset: number; followTail: boolean },
+  ctx: DetailScrollContext,
+): DetailKeyResult {
+  const viewH = Math.max(1, ctx.viewportHeight);
+  const max = Math.max(0, ctx.contentLines - viewH);
+  const off = state.scrollOffset;
+
+  if (matchesKey(data, Key.pageUp)) {
+    const step = ctx.viewportHeight > 0 ? ctx.viewportHeight : PAGE_SCROLL_DEFAULT;
+    return { scrollOffset: Math.max(0, off - step), followTail: false, handled: true };
+  }
+  if (matchesKey(data, Key.pageDown)) {
+    const step = ctx.viewportHeight > 0 ? ctx.viewportHeight : PAGE_SCROLL_DEFAULT;
+    const next = Math.min(max, off + step);
+    // 到底恢复跟随（用户 PgDn 翻到底 = 想看最新）
+    return { scrollOffset: next, followTail: next >= max, handled: true };
+  }
+  if (matchesKey(data, Key.home)) {
+    return { scrollOffset: 0, followTail: false, handled: true };
+  }
+  if (matchesKey(data, Key.end)) {
+    return { scrollOffset: max, followTail: true, handled: true };
+  }
+  return { scrollOffset: off, followTail: state.followTail, handled: false };
+}
+
+// ── L2 详情区段渲染（buildDetailContent 调用）─────────────────────
+
+function renderWorkerLogSection(
+  rightLines: string[],
+  run: WorkflowRun,
+  mainWidth: number,
+  theme: ThemeLike,
+): void {
+  const logs = run.state.errorLogs;
+  if (!logs || logs.length === 0) return;
+  const total = logs.length;
+  const WORKER_LOG_SHOW = 20;
+  const showCount = Math.min(total, WORKER_LOG_SHOW);
+  const label = total > showCount
+    ? `Worker diagnostics · last ${showCount} of ${total}`
+    : `Worker diagnostics · ${total} entr${total !== 1 ? "ies" : "y"}`;
+  rightLines.push(theme.fg("warning", label));
+  const start = total - showCount;
+  for (let i = start; i < total; i++) {
+    const entry = logs[i];
+    const levelToken = entry.level === "error" ? "error" : entry.level === "warn" ? "warning" : "muted";
+    const prefix = `[${entry.level}]`;
+    const line = `  ${prefix} ${entry.message}`.slice(0, mainWidth - BOX_BORDER_CHARS);
+    rightLines.push(theme.fg(levelToken, line));
+  }
+  rightLines.push("");
+}
+
+function renderPromptSection(
+  rightLines: string[],
+  node: ExecutionTraceNode,
+  state: { promptExpanded: boolean },
+  theme: ThemeLike,
+): void {
+  const taskLines = node.task.split("\n");
+  const lineCount = taskLines.length;
+  rightLines.push(theme.fg("muted", `Prompt · ${lineCount} lines · ⏎ ${state.promptExpanded ? "collapse" : "expand"}`));
+  if (state.promptExpanded || lineCount <= PROMPT_FOLD_LINES) {
+    rightLines.push(...taskLines.map((l) => `  ${l}`));
+  } else {
+    rightLines.push(...taskLines.slice(0, PROMPT_FOLD_LINES).map((l) => `  ${l}`));
+    rightLines.push(theme.fg("dim", `  ${ELLIPSIS} ${lineCount - PROMPT_FOLD_LINES} more lines`));
+  }
+  rightLines.push("");
+}
+
+function renderActivitySection(
+  rightLines: string[],
+  node: ExecutionTraceNode,
+  mainWidth: number,
+  theme: ThemeLike,
+): void {
+  // Live 路径：agent 运行中，从 node.live 派生实时 eventLog + currentActivity。
+  // 与 subagents TUI 一致：当前活动行 + 最近 N 条离散事件（tool/turn_end/error）。
+  if (node.live) {
+    const live = projectLiveProgress(node.live);
+    const eventLog = live.eventLog.filter((e) => e.type !== "turn_end");
+    const totalCount = getAllToolCalls(node.live).length;
+    const label = `Activity · ${totalCount} tool call${totalCount !== 1 ? "s" : ""} · ${live.turns} turn${live.turns !== 1 ? "s" : ""}`;
+    rightLines.push(theme.fg("muted", label));
+    // 当前活动行（running tool / thinking / text）
+    if (live.currentActivity) {
+      rightLines.push(theme.fg("accent", `  ⎿ ${live.currentActivity.type}: ${live.currentActivity.label}`.slice(0, mainWidth - BOX_BORDER_CHARS)));
+    }
+    // 最近 N 条事件
+    const showCount = Math.min(MAX_TOOL_CALLS_DISPLAY, eventLog.length);
+    const start = eventLog.length - showCount;
+    for (let i = start; i < eventLog.length; i++) {
+      const entry = eventLog[i] as AgentEventLogEntry;
+      rightLines.push(theme.fg("dim", `  ${formatEventLine(entry, theme)}`.slice(0, mainWidth - BOX_BORDER_CHARS)));
+    }
+    if (totalCount === 0 && !live.currentActivity) {
+      rightLines.push(theme.fg("dim", "  (starting...)"));
+    }
+    rightLines.push("");
+    return;
+  }
+
+  // 终态路径：从 node.result.toolCalls 读（原有逻辑）
+  const toolCalls = node.result?.toolCalls ?? [];
+  const totalCount = toolCalls.length;
+  if (totalCount > 0) {
+    const showCount = Math.min(MAX_TOOL_CALLS_DISPLAY, totalCount);
+    const isTruncated = totalCount > MAX_TOOL_CALLS_DISPLAY;
+    const label = isTruncated
+      ? `Activity · last ${showCount} of ${totalCount} tool calls`
+      : `Activity · ${totalCount} tool call${totalCount !== 1 ? "s" : ""}`;
+    rightLines.push(theme.fg("muted", label));
+    const start = totalCount - showCount;
+    for (let i = start; i < totalCount; i++) {
+      rightLines.push(`  ${formatActivityLine(toolCalls[i], mainWidth - BOX_BORDER_CHARS)}`);
+    }
+  } else {
+    rightLines.push(theme.fg("muted", "Activity"));
+    rightLines.push(theme.fg("dim", `  ${node.status === "running" ? "(no tool calls yet)" : "(no activity recorded)"}`));
+  }
+  rightLines.push("");
+}
+
+function renderOutcomeSection(
+  rightLines: string[],
+  node: ExecutionTraceNode,
+  mainWidth: number,
+  theme: ThemeLike,
+): void {
+  rightLines.push(theme.fg("muted", "Outcome"));
+  if (node.status === "running" && node.live) {
+    // 运行中：显示实时指标（elapsed/tokens/turns）替代空荡的 "Still running..."
+    const live = projectLiveProgress(node.live);
+    const tokK = live.totalTokens > 0 ? `${Math.round(live.totalTokens / 1000)}k tok` : "0 tok";
+    rightLines.push(theme.fg("dim", `  Running · ${formatElapsedSeconds(live.elapsedSeconds)} · ${tokK} · ${live.turns} turn${live.turns !== 1 ? "s" : ""}`));
+    if (live.lastError) {
+      rightLines.push(theme.fg("warning", `  ⚠ ${live.lastError.slice(0, mainWidth - BOX_BORDER_CHARS)}`));
+    }
+  } else if (node.status === "running") {
+    rightLines.push(theme.fg("dim", "  Still running..."));
+  } else if (node.result?.error) {
+    rightLines.push(theme.fg("error", `  ${node.result.error.slice(0, mainWidth - BOX_BORDER_CHARS)}`));
+  } else if (node.result?.content) {
+    const raw = node.result.content;
+    const OUTCOME_TAIL_LINES = 5;
+    if (Buffer.byteLength(raw, "utf8") > OUTPUT_TRUNCATE_BYTES) {
+      const truncated = Buffer.from(raw, "utf8").slice(0, OUTPUT_TRUNCATE_BYTES).toString("utf8");
+      const allLines = truncated.split("\n");
+      const tail = allLines.slice(-OUTCOME_TAIL_LINES);
+      rightLines.push(...tail.map((l) => `  ${l.slice(0, mainWidth - BOX_BORDER_CHARS)}`));
+      rightLines.push(theme.fg("dim", "  (truncated)"));
+    } else {
+      const allLines = raw.split("\n");
+      const tail = allLines.slice(-OUTCOME_TAIL_LINES);
+      rightLines.push(...tail.map((l) => `  ${l.slice(0, mainWidth - BOX_BORDER_CHARS)}`));
+    }
+  }
+}

package/src/interface/views/format.ts

@@ -0,0 +1,320 @@
+/**
+ * Workflow View — Pure formatting functions (FR-4)
+ *
+ * Stateless functions extracted from WorkflowsView for testability.
+ * All functions are pure: no Pi runtime, no side effects.
+ */
+
+import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+
+import type { AgentEventLogEntry } from "../../execution/types.ts";
+import type { ExecutionTraceNode, ToolCallEntry } from "../../orchestration/models/types.ts";
+import type { DoneReason, RunStatus } from "../../orchestration/models/types.ts";
+
+// ── Constants ─────────────────────────────────────────────────
+
+export const SIDEBAR_WIDTH = 24;
+export const PROMPT_FOLD_LINES = 3;
+export const OUTPUT_TRUNCATE_BYTES = 100_000;
+export const ELLIPSIS = "\u2026"; // U+2026
+
+// L2 详情滚动常量（对齐 subagents list-view.ts）。
+/** terminal.rows 读不到时的翻页兜底步长（防 NaN）。 */
+export const PAGE_SCROLL_DEFAULT = 10;
+/** tui.terminal.rows 兜底行数（duck-type 失败时，对齐 subagents TERM_ROWS_FALLBACK）。 */
+export const TERM_ROWS_FALLBACK = 24;
+
+// 跨 view 共享的布局常量（WorkflowsView + detail-content 都用）。
+/** box 左右边框字符宽度（│ x 2），用于内容行截断预算。 */
+export const BOX_BORDER_CHARS = 2;
+/** token 数 → k 单位的除数。 */
+export const BUDGET_TOKENS_DIVISOR = 1000;
+/** Activity 区最多显示的 tool call 条数。 */
+export const MAX_TOOL_CALLS_DISPLAY = 3;
+
+// 时间换算（模块私有常量）。
+const MS_PER_SEC = 1000;
+const SECS_PER_MIN = 60;
+
+/**
+ * 可显示的状态文本集合。
+ *
+ * 包含 RunStatus（"running"|"paused"|"done" 不直接显示，转 reason）+ DoneReason
+ * （completed/failed/aborted/budget_limited/time_limited）+ ExecutionTraceNode.status
+ * （含 "pending"——trace 节点的初始态）。
+ *
+ * 收窄自 string → 显式联合，编译器会在新增 status 时强制 switch 补齐分支。
+ */
+type StatusText =
+  | RunStatus
+  | DoneReason
+  | "pending";
+
+// ── Theme interface (avoids importing Pi runtime) ─────────────
+
+export interface ThemeLike {
+  fg(token: string, text: string): string;
+  bold(text: string): string;
+}
+
+// ── Status helpers ────────────────────────────────────────────
+
+/** status → 语义颜色 token（用于给任意文本染色，不含符号）。 */
+function statusColorToken(
+  status: StatusText,
+): "success" | "warning" | "error" | "muted" {
+  switch (status) {
+    case "completed": return "success";
+    case "running": return "warning";
+    case "failed": case "aborted": return "error";
+    default: return "muted";
+  }
+}
+
+export function statusDotStr(
+  status: StatusText,
+  theme: ThemeLike,
+): string {
+  return theme.fg(statusColorToken(status), "●");
+}
+
+/** Format a status badge with color for the header area. */
+export function formatStatusBadge(
+  status: StatusText,
+  theme: ThemeLike,
+): string {
+  switch (status) {
+    case "running": return theme.fg("warning", "\u25CF running");
+    case "paused": return theme.fg("warning", "\u23F8 PAUSED");
+    case "completed": return theme.fg("success", "\u2713 completed");
+    case "failed": return theme.fg("error", "\u2717 failed");
+    case "aborted": return theme.fg("error", "\u2717 aborted");
+    case "budget_limited": return theme.fg("error", "\u26A0 budget");
+    case "time_limited": return theme.fg("error", "\u26A0 timeout");
+    default: return theme.fg("muted", status);
+  }
+}
+
+// ── Pure formatting functions ─────────────────────────────────
+
+/** Group trace nodes by phase. Nodes without phase go to "(no phase)". */
+function groupByPhase(nodes: ExecutionTraceNode[]): Map<string, ExecutionTraceNode[]> {
+  const map = new Map<string, ExecutionTraceNode[]>();
+  for (const node of nodes) {
+    const phase = node.phase || "(default)";
+    let arr = map.get(phase);
+    if (!arr) {
+      arr = [];
+      map.set(phase, arr);
+    }
+    arr.push(node);
+  }
+ // Sort within each phase by stepIndex ascending (FR-3.2)
+  for (const arr of map.values()) {
+    arr.sort((a, b) => a.stepIndex - b.stepIndex);
+  }
+  return map;
+}
+
+/** Format elapsed time string from startedAt. */
+export function formatElapsed(startedAt?: string, now: number = Date.now()): string {
+  if (!startedAt) return "-";
+  const ms = now - new Date(startedAt).getTime();
+  if (ms < MS_PER_SEC) return "0s";
+  const secs = Math.floor(ms / MS_PER_SEC);
+  if (secs < SECS_PER_MIN) return `${secs}s`;
+  const mins = Math.floor(secs / SECS_PER_MIN);
+  const remSecs = secs % SECS_PER_MIN;
+  return `${mins}m${remSecs}s`;
+}
+
+/**
+ * Format elapsed time from integer seconds（live 路径用）。
+ * 与 formatElapsed 输出格式一致，但输入是 computeElapsedSeconds 的秒数（非时间戳）。
+ */
+export function formatElapsedSeconds(seconds: number): string {
+  if (seconds < 1) return "0s";
+  if (seconds < SECS_PER_MIN) return `${seconds}s`;
+  const mins = Math.floor(seconds / SECS_PER_MIN);
+  const remSecs = seconds % SECS_PER_MIN;
+  return `${mins}m${remSecs}s`;
+}
+
+/**
+ * Format a live eventLog entry（live 路径 Activity 区用）。
+ *
+ *   tool_start → "→ {label}"
+ *   tool_end   → "← {label}"（done）/ "✗ {label}"（failed）
+ *   turn_end   → "∘ {label}"（turn 摘要）
+ *   error      → "✗ {label}"
+ *
+ * 对齐 subagents formatEventLine 的视觉风格，但用 workflow 的 ThemeLike（无 spinner）。
+ */
+export function formatEventLine(entry: AgentEventLogEntry, theme: ThemeLike): string {
+  switch (entry.type) {
+    case "tool_start":
+      return `→ ${entry.label}`;
+    case "tool_end":
+      return entry.status === "failed"
+        ? theme.fg("error", `✗ ${entry.label}`)
+        : `✓ ${entry.label}`;
+    case "turn_end":
+      return theme.fg("dim", `∘ ${entry.label}`);
+    case "error":
+      return theme.fg("error", `✗ ${entry.label}`);
+    default:
+      return entry.label;
+  }
+}
+
+/** Format token + tool call statistics. */
+export function formatTokenStat(
+  usage?: { input: number; output: number },
+  toolCalls?: ToolCallEntry[],
+  elapsed?: string,
+): string {
+  const tokens = usage ? usage.input + usage.output : 0;
+  const tools = toolCalls?.length ?? 0;
+  const base = `${tokens} tok · ${tools} tool calls`;
+  return elapsed ? `${base} · ${elapsed}` : base;
+}
+
+/**
+ * renderResult 的文本兜底：从 result.content[0] 提取纯文本。
+ * 多处 tool 的 renderResult 曾各自内联此逻辑，提取后统一调用。
+ */
+export function renderTextFallback(
+  result: { content?: Array<{ type: string; text?: string }> },
+): string {
+  const first = result.content?.[0];
+  return first?.type === "text" ? (first.text ?? "") : "";
+}
+
+/** Format a single activity line: ToolName(argsPreview). */
+export function formatActivityLine(entry: ToolCallEntry, maxWidth: number): string {
+ // 语义阈值与开销：低于此宽度只显名称；括号占 2 字符 (name)。
+  const MIN_ACTIVITY_WIDTH = 10;
+  const PARENS_OVERHEAD = 2;
+  if (maxWidth < MIN_ACTIVITY_WIDTH) return entry.name;
+  const argsBudget = maxWidth - entry.name.length - PARENS_OVERHEAD;
+  if (argsBudget <= 0) return truncateToWidth(entry.name, maxWidth);
+  const truncated = entry.input.length > argsBudget
+    ? entry.input.slice(0, argsBudget - 1) + ELLIPSIS
+    : entry.input;
+  return `${entry.name}(${truncated})`;
+}
+
+// ── ANSI helpers ──────────────────────────────────────────────
+
+/** Measure visible width of a string (strips ANSI escapes, handles CJK/emoji).
+ *  Delegates to pi-tui's visibleWidth for accurate width calculation.
+ */
+export function visibleLen(s: string): number {
+  return visibleWidth(s);
+}
+
+/** Pad an ANSI-escaped string to a target *visible* width.
+ *  只 pad 不截断：超宽时原样返回（调用方负责先截断）。
+ *  对齐 subagents 的 padToVisible 语义。
+ */
+export function padVisible(s: string, width: number): string {
+  const vl = visibleLen(s);
+  if (vl >= width) return s;
+  return s + " ".repeat(width - vl);
+}
+
+/**
+ * 分段着色版填充：title 和 fill 都已着色（含 ANSI），拼接时各自 ANSI 延续。
+ * 解决 ANSI 嵌套失色：若用 fg("c1", fill(title, "─", n))，
+ * title 内的 \x1b[0m 会重置外层 c1，导致 title 之后的 ─ 失去 c1。
+ * 改成 title + fill.repeat(后)，fill 整段保持自己的 ANSI，不依赖外层包裹。
+ *
+ * 对齐 subagents format.ts segFillColored（同源移植）。
+ */
+export function segFillColored(
+  titleStyled: string | undefined,
+  fillStyled: string,
+  width: number,
+): string {
+  if (width <= 0) return "";
+  const fillW = visibleLen(fillStyled);
+  if (!titleStyled || fillW === 0) {
+    return fillStyled.repeat(width);
+  }
+  const tw = visibleLen(titleStyled);
+  if (tw >= width) return truncateToWidth(titleStyled, width);
+  const fillCount = width - tw;
+  return titleStyled + fillStyled.repeat(fillCount);
+}
+
+// ── Phase group (filters empty phases) ────────────────────────
+
+export interface PhaseGroup {
+  name: string;
+  nodes: ExecutionTraceNode[];
+  doneCount: number;
+}
+
+/** The fallback phase name when node has no explicit phase. */
+const NO_PHASE = "(default)";
+
+/** Build phase groups. Nodes without a phase are placed in an unnamed group. */
+export function buildPhaseGroups(nodes: ExecutionTraceNode[]): PhaseGroup[] {
+  const map = groupByPhase(nodes);
+  const result: PhaseGroup[] = [];
+  for (const [name, phaseNodes] of map) {
+    if (phaseNodes.length > 0) {
+      result.push({
+        name: name === NO_PHASE ? "" : name,
+        nodes: phaseNodes,
+        doneCount: phaseNodes.filter((n) => n.status === "completed").length,
+      });
+    }
+  }
+  return result;
+}
+
+// ── Sidebar phase line formatter ─────────────────────────────
+
+export function formatPhaseLine(
+  pg: PhaseGroup,
+  idx: number,
+  isSelected: boolean,
+  theme: ThemeLike,
+  maxWidth: number,
+): string {
+  const pointer = isSelected ? "❯ " : "  ";
+  const dot = statusDotStr(pg.doneCount === pg.nodes.length ? "completed" : "running", theme);
+  const name = pg.name || "(unnamed)";
+  const label = `${idx + 1} ${name} ${pg.doneCount}/${pg.nodes.length}`;
+ // pointer(2) + dot(1) + space(1)
+  const PHASE_PREFIX_WIDTH = 4;
+  const budget = maxWidth - PHASE_PREFIX_WIDTH;
+  const truncated = visibleLen(label) > budget
+    ? truncateToWidth(label, budget - 1) + ELLIPSIS
+    : label;
+  return `${pointer}${dot} ${truncated}`;
+}
+
+// ── Agent one-liner for overview right panel ──────────────────
+
+const TOKEN_K = 1000;
+
+export function formatAgentOneLiner(node: ExecutionTraceNode, theme: ThemeLike): string {
+  const dot = statusDotStr(node.status, theme);
+  const elapsed = formatElapsed(
+    node.startedAt,
+    node.completedAt ? new Date(node.completedAt).getTime() : Date.now(),
+  );
+  const tok = node.result?.usage;
+  const tokStr = tok
+    ? `${Math.round((tok.input + tok.output) / TOKEN_K)}k tok`
+    : "";
+  const tcCount = node.result?.toolCalls?.length ?? 0;
+  const parts = [dot, node.agent, node.model];
+  if (tokStr) parts.push(`${tokStr} · ${tcCount} tools`);
+  parts.push(elapsed);
+  return parts.join("    ");
+}
+
+