@jameslovespancakes/pi-plus 1.0.11 → 1.0.13

package/src/domains/workflows/runtime/ui/workflow-inspector.ts

@@ -0,0 +1,435 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  Box,
+  Input,
+  Markdown,
+  matchesKey,
+  Text,
+  type Focusable,
+  type MarkdownTheme,
+  type TUI,
+  type TuiMouseEvent,
+  type TuiMouseEventResult,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import type { AgentChatMessage, AgentRowSnapshot, WorkflowProgressSnapshot } from "../progress-types.ts";
+import type { WorkflowProgressSource } from "../types.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
+import { formatDuration, statusIcon, truncateDisplay } from "./workflow-format.ts";
+import {
+  centerWorkflowViewerViewport,
+  fitWorkflowViewerRow,
+  fitWorkflowViewerRows,
+  workflowViewerHeight,
+} from "./workflow-viewer-layout.ts";
+
+export interface WorkflowInspectorOutcome {
+  readonly label: string;
+  readonly text: string;
+}
+
+type WorkflowInspectorLiveSource = Pick<WorkflowProgressSource, "conversation" | "followUp">;
+
+interface BoardAgent {
+  readonly agent: AgentRowSnapshot;
+  readonly phase: string;
+}
+
+interface BoardRow {
+  readonly text: string;
+  readonly agentIndex?: number;
+}
+
+/** Modal board for inspecting workflow agents and sending targeted follow-ups. */
+export class WorkflowInspector implements Focusable {
+  private selected = 0;
+  private detailAgentId: number | undefined;
+  private detailScroll = 0;
+  private clickRows = new Map<number, number>();
+  private inputRow: number | undefined;
+  private followUpError: string | undefined;
+  private sending = false;
+  private _focused = false;
+  private readonly input: Input;
+  private readonly snapshotProvider: () => WorkflowProgressSnapshot;
+  private readonly tui: Pick<TUI, "requestRender" | "terminal">;
+  private readonly theme: Theme;
+  private readonly close: () => void;
+  private readonly outcome?: WorkflowInspectorOutcome;
+  private readonly live?: WorkflowInspectorLiveSource;
+
+  constructor(
+    snapshotProvider: () => WorkflowProgressSnapshot,
+    tui: Pick<TUI, "requestRender" | "terminal">,
+    theme: Theme,
+    close: () => void,
+    outcome?: WorkflowInspectorOutcome,
+    live?: WorkflowInspectorLiveSource,
+  ) {
+    this.snapshotProvider = snapshotProvider;
+    this.tui = tui;
+    this.theme = theme;
+    this.close = close;
+    this.outcome = outcome;
+    this.live = live;
+    this.input = new Input({
+      prompt: this.theme.fg("accent", "› "),
+      placeholder: "Send a follow-up to this agent…",
+      placeholderStyle: (text) => this.theme.fg("dim", text),
+    });
+    this.input.onSubmit = (value) => void this.submitFollowUp(value);
+  }
+
+  get focused(): boolean {
+    return this._focused;
+  }
+
+  set focused(value: boolean) {
+    this._focused = value;
+    this.input.focused = value && this.detailAgentId !== undefined;
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, "escape") || (data === "q" && this.detailAgentId === undefined)) {
+      this.close();
+      return;
+    }
+
+    if (this.detailAgentId !== undefined) {
+      if (matchesKey(data, "pageUp")) this.scrollChat(6);
+      else if (matchesKey(data, "pageDown")) this.scrollChat(-6);
+      else if (matchesKey(data, "backspace") && this.input.getValue().length === 0) this.closeDetails();
+      else if (this.canMessageSelectedAgent()) this.input.handleInput(data);
+      this.tui.requestRender();
+      return;
+    }
+
+    const count = this.agents().length;
+    if (matchesKey(data, "up") || data === "k") this.select(this.selected - 1, count);
+    else if (matchesKey(data, "down") || data === "j") this.select(this.selected + 1, count);
+    else if (matchesKey(data, "pageUp")) this.select(this.selected - 8, count);
+    else if (matchesKey(data, "pageDown")) this.select(this.selected + 8, count);
+    else if (matchesKey(data, "home") || data === "g") this.select(0, count);
+    else if (matchesKey(data, "end") || data === "G") this.select(count - 1, count);
+    else if (matchesKey(data, "return") || matchesKey(data, "enter") || data === " ") this.openDetails(count);
+  }
+
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined {
+    if (this.detailAgentId !== undefined) {
+      if (event.type === "wheel") {
+        this.scrollChat(event.wheelDelta && event.wheelDelta < 0 ? 3 : -3);
+        return { handled: true, focus: true, render: true };
+      }
+      if (event.type === "click" && event.button === "left" && event.y === this.inputRow && this.canMessageSelectedAgent()) {
+        const result = this.input.handleMouse({ ...event, y: 0 });
+        return { handled: true, focus: true, render: true, ...result };
+      }
+      return undefined;
+    }
+
+    const count = this.agents().length;
+    if (event.type === "wheel") {
+      this.select(this.selected + (event.wheelDelta && event.wheelDelta < 0 ? -3 : 3), count);
+      return { handled: true, focus: true, render: true };
+    }
+    if (event.type !== "click" || event.button !== "left") return undefined;
+    const index = this.clickRows.get(event.y);
+    if (index === undefined) return undefined;
+    this.selected = index;
+    this.openDetails(count);
+    return { handled: true, focus: true, render: true };
+  }
+
+  render(width: number): string[] {
+    const outerWidth = Math.max(4, width);
+    const innerWidth = Math.max(1, outerWidth - 4);
+    const snapshot = this.snapshotProvider();
+    const agents = this.agents(snapshot);
+    this.selected = Math.min(Math.max(0, agents.length - 1), this.selected);
+
+    const selected = this.detailAgentId === undefined
+      ? undefined
+      : agents.find((entry) => entry.agent.id === this.detailAgentId);
+    if (this.detailAgentId !== undefined && !selected) this.closeDetails();
+
+    const totalHeight = workflowViewerHeight(this.tui.terminal.rows);
+    const innerHeight = Math.max(1, totalHeight - 2);
+    const interior = selected
+      ? this.chatInterior(selected, innerWidth, innerHeight)
+      : this.boardInterior(snapshot, agents, innerWidth, innerHeight);
+
+    return [
+      this.theme.fg("border", `╭${"─".repeat(Math.max(0, outerWidth - 2))}╮`),
+      ...interior.map((line) => this.frame(line, innerWidth)),
+      this.theme.fg("border", `╰${"─".repeat(Math.max(0, outerWidth - 2))}╯`),
+    ].map((line) => truncateDisplay(line, outerWidth));
+  }
+
+  invalidate(): void {
+    this.input.invalidate();
+  }
+
+  private boardInterior(
+    snapshot: WorkflowProgressSnapshot,
+    agents: readonly BoardAgent[],
+    width: number,
+    height: number,
+  ): string[] {
+    this.inputRow = undefined;
+    this.clickRows.clear();
+    const bodyHeight = Math.max(0, height - 6);
+    const rows = this.boardRows(snapshot, agents, width);
+    const selectedRow = Math.max(0, rows.findIndex((row) => row.agentIndex === this.selected));
+    const viewport = centerWorkflowViewerViewport(rows, bodyHeight, selectedRow);
+    const body = fitWorkflowViewerRows(viewport.visible.map((row) => row.text), bodyHeight);
+
+    viewport.visible.forEach((row, index) => {
+      if (row.agentIndex !== undefined) this.clickRows.set(5 + index, row.agentIndex);
+    });
+
+    return fitWorkflowViewerRows([
+      ` ${this.theme.fg("accent", this.theme.bold("Workflow"))} ${this.theme.fg("dim", snapshot.title)}`,
+      ` ${this.summary(snapshot, agents)}`,
+      this.theme.fg("dim", "─".repeat(width)),
+      ` ${this.columns(width)}`,
+      ...body,
+      this.theme.fg("dim", "─".repeat(width)),
+      ` ${this.theme.fg("dim", `↑↓ select · click/enter inspect · ${viewport.percentage}% · esc close`)}`,
+    ], height);
+  }
+
+  private chatInterior(
+    entry: BoardAgent,
+    width: number,
+    height: number,
+  ): string[] {
+    this.clickRows.clear();
+    const { agent } = entry;
+    const bodyHeight = Math.max(0, height - 6);
+    const rows = this.chatRows(agent, width);
+    const maxStart = Math.max(0, rows.length - bodyHeight);
+    const start = Math.max(0, maxStart - this.detailScroll);
+    const body = fitWorkflowViewerRows(rows.slice(start, start + bodyHeight), bodyHeight);
+    const elapsed = agent.startedAt === undefined ? "queued" : formatDuration((agent.doneAt ?? Date.now()) - agent.startedAt);
+    const details = [
+      shortModel(agent.model ?? "host default"),
+      entry.phase,
+      elapsed,
+      `${agent.toolUses} tool${agent.toolUses === 1 ? "" : "s"}`,
+    ].join(this.theme.fg("dim", " · "));
+    const canMessage = agent.status === "running" && this.live !== undefined;
+    this.input.focused = this._focused && canMessage;
+    this.inputRow = canMessage ? height - 1 : undefined;
+    const inputLine = canMessage
+      ? this.input.render(Math.max(1, width - 1))[0] ?? ""
+      : this.theme.fg("dim", agent.status === "queued" ? "Agent has not started yet." : "Agent has finished.");
+    const help = this.followUpError
+      ? this.theme.fg("error", truncateDisplay(this.followUpError, Math.max(1, width - 1)))
+      : this.theme.fg("dim", "enter send · page up/down scroll · backspace agents · esc close");
+
+    return fitWorkflowViewerRows([
+      ` ${statusIcon(agent.status, this.theme)} ${this.theme.fg("accent", this.theme.bold(agent.label))}`,
+      ` ${details}`,
+      this.theme.fg("dim", "─".repeat(width)),
+      ...body,
+      this.theme.fg("dim", "─".repeat(width)),
+      ` ${inputLine}`,
+      ` ${help}`,
+    ], height);
+  }
+
+  private agents(snapshot = this.snapshotProvider()): BoardAgent[] {
+    return snapshot.phases.flatMap((phase) => phase.agents.map((agent) => ({ phase: phase.title, agent })));
+  }
+
+  private select(index: number, count: number): void {
+    if (count === 0) return;
+    this.selected = Math.min(count - 1, Math.max(0, index));
+    this.tui.requestRender();
+  }
+
+  private openDetails(count: number): void {
+    if (count === 0) return;
+    const entry = this.agents()[this.selected];
+    if (!entry) return;
+    this.detailAgentId = entry.agent.id;
+    this.detailScroll = 0;
+    this.followUpError = undefined;
+    this.input.focused = this._focused;
+    this.tui.requestRender();
+  }
+
+  private closeDetails(): void {
+    this.detailAgentId = undefined;
+    this.detailScroll = 0;
+    this.followUpError = undefined;
+    this.input.setValue("");
+    this.input.focused = false;
+    this.tui.requestRender();
+  }
+
+  private scrollChat(delta: number): void {
+    this.detailScroll = Math.max(0, this.detailScroll + delta);
+    this.tui.requestRender();
+  }
+
+  private canMessageSelectedAgent(): boolean {
+    if (this.detailAgentId === undefined || !this.live || this.sending) return false;
+    return this.agents().some((entry) => entry.agent.id === this.detailAgentId && entry.agent.status === "running");
+  }
+
+  private async submitFollowUp(value: string): Promise<void> {
+    const message = value.trim();
+    const agentId = this.detailAgentId;
+    if (!message || agentId === undefined || !this.live || this.sending) return;
+    this.sending = true;
+    this.followUpError = undefined;
+    this.input.setValue("");
+    this.tui.requestRender();
+    try {
+      await this.live.followUp(agentId, message);
+      this.detailScroll = 0;
+    } catch (error) {
+      this.followUpError = unknownErrorMessage(error);
+      this.input.setValue(message);
+    } finally {
+      this.sending = false;
+      this.tui.requestRender();
+    }
+  }
+
+  private boardRows(snapshot: WorkflowProgressSnapshot, agents: readonly BoardAgent[], width: number): BoardRow[] {
+    if (agents.length === 0) {
+      return [{ text: ` ${this.theme.fg("dim", "No agents yet. Tasks appear here when the workflow starts.")}` }];
+    }
+
+    const rows: BoardRow[] = agents.map((entry, index) => ({
+      text: this.agentRow(entry, index, width),
+      agentIndex: index,
+    }));
+    const latestLog = snapshot.logs.at(-1);
+    if (latestLog) rows.push({ text: ` ${this.theme.fg("dim", `Latest · ${latestLog}`)}` });
+    if (this.outcome) {
+      rows.push({ text: ` ${this.theme.fg("accent", this.outcome.label)}` });
+      rows.push(...wrapTextWithAnsi(this.outcome.text, Math.max(1, width - 2)).slice(0, 12).map((text) => ({ text: ` ${text}` })));
+    }
+    return rows;
+  }
+
+  private chatRows(agent: AgentRowSnapshot, width: number): string[] {
+    const messages = this.live?.conversation(agent.id) ?? [];
+    if (messages.length === 0) return [` ${this.theme.fg("dim", "Waiting for agent activity…")}`];
+    return messages.flatMap((message) => this.chatMessageRows(message, width));
+  }
+
+  private chatMessageRows(message: AgentChatMessage, width: number): string[] {
+    if (message.role === "task" || message.role === "user") {
+      const box = new Box(1, 1, (text) => this.theme.bg("userMessageBg", text));
+      box.addChild(new Markdown(
+        message.text,
+        0,
+        0,
+        this.markdownTheme(),
+        { color: (text) => this.theme.fg("userMessageText", text) },
+        { preserveOrderedListMarkers: true, preserveBackslashEscapes: true },
+      ));
+      return box.render(width);
+    }
+
+    if (message.role === "assistant") {
+      return ["", ...new Markdown(message.text, 1, 0, this.markdownTheme()).render(width)];
+    }
+
+    if (message.role === "tool") {
+      const box = new Box(1, 0, (text) => this.theme.bg("toolPendingBg", text));
+      box.addChild(new Text(this.theme.fg("toolTitle", this.theme.bold(message.text)), 0, 0));
+      return box.render(width);
+    }
+
+    return [
+      "",
+      ...new Text(this.theme.fg("error", message.text), 1, 0).render(width),
+    ];
+  }
+
+  private markdownTheme(): MarkdownTheme {
+    return {
+      heading: (text) => this.theme.fg("mdHeading", text),
+      link: (text) => this.theme.fg("mdLink", text),
+      linkUrl: (text) => this.theme.fg("mdLinkUrl", text),
+      code: (text) => this.theme.fg("mdCode", text),
+      codeBlock: (text) => this.theme.fg("mdCodeBlock", text),
+      codeBlockBorder: (text) => this.theme.fg("mdCodeBlockBorder", text),
+      quote: (text) => this.theme.fg("mdQuote", text),
+      quoteBorder: (text) => this.theme.fg("mdQuoteBorder", text),
+      hr: (text) => this.theme.fg("mdHr", text),
+      listBullet: (text) => this.theme.fg("mdListBullet", text),
+      bold: (text) => this.theme.bold(text),
+      italic: (text) => this.theme.italic(text),
+      strikethrough: (text) => this.theme.strikethrough(text),
+      underline: (text) => this.theme.underline(text),
+    };
+  }
+
+  private agentRow(entry: BoardAgent, index: number, width: number): string {
+    const { agent } = entry;
+    const selected = index === this.selected;
+    const marker = selected ? this.theme.fg("accent", "▸") : " ";
+    const taskWidth = Math.max(12, Math.floor(width * 0.36));
+    const modelWidth = Math.max(12, Math.floor(width * 0.28));
+    const activityWidth = Math.max(8, width - taskWidth - modelWidth - 7);
+    const task = this.cell(agent.label, taskWidth, agent.status === "failed" ? "error" : "text");
+    const model = this.cell(shortModel(agent.model ?? "host default"), modelWidth, "muted");
+    const activity = this.cell(agentActivity(agent), activityWidth, agent.status === "failed" ? "error" : "dim");
+    const row = `${marker} ${statusIcon(agent.status, this.theme)} ${task} ${model} ${activity}`;
+    return selected ? this.theme.bg("selectedBg", fitWorkflowViewerRow(row, width)) : fitWorkflowViewerRow(row, width);
+  }
+
+  private columns(width: number): string {
+    const taskWidth = Math.max(12, Math.floor(width * 0.36));
+    const modelWidth = Math.max(12, Math.floor(width * 0.28));
+    return this.theme.fg("dim", `  ${"Task".padEnd(taskWidth + 2)}${"Model".padEnd(modelWidth + 1)}Activity`);
+  }
+
+  private summary(snapshot: WorkflowProgressSnapshot, agents: readonly BoardAgent[]): string {
+    const counts = { queued: 0, running: 0, done: 0, failed: 0 };
+    for (const { agent } of agents) counts[agent.status]++;
+    const parts = [
+      this.theme.fg("accent", snapshot.currentPhase),
+      `${counts.running} running`,
+      `${counts.queued} queued`,
+      this.theme.fg("success", `${counts.done} done`),
+      ...(counts.failed > 0 ? [this.theme.fg("error", `${counts.failed} failed`)] : []),
+      formatDuration((snapshot.doneAt ?? Date.now()) - snapshot.startedAt),
+      formatWorkflowUsageLine(snapshot.usage) ?? "",
+    ].filter(Boolean);
+    return parts.join(this.theme.fg("dim", " · "));
+  }
+
+  private cell(text: string, width: number, color: Parameters<Theme["fg"]>[0]): string {
+    const value = truncateDisplay(text, width);
+    return this.theme.fg(color, value + " ".repeat(Math.max(0, width - visibleWidth(value))));
+  }
+
+  private frame(content: string, width: number): string {
+    const fitted = fitWorkflowViewerRow(content, width);
+    const padding = " ".repeat(Math.max(0, width - visibleWidth(fitted)));
+    return `${this.theme.fg("border", "│")} ${fitted}${padding} ${this.theme.fg("border", "│")}`;
+  }
+}
+
+function shortModel(model: string): string {
+  return model.replace(/^openai-codex\//, "codex/").replace(/^anthropic\//, "");
+}
+
+function agentActivity(agent: AgentRowSnapshot): string {
+  if (agent.status === "queued") return "queued";
+  if (agent.status === "failed") return agent.error ?? "failed";
+  const parts: string[] = [];
+  if (agent.lastTool) parts.push(agent.lastTool);
+  if (agent.toolUses > 0) parts.push(`${agent.toolUses} tool${agent.toolUses === 1 ? "" : "s"}`);
+  if (agent.startedAt !== undefined) parts.push(formatDuration((agent.doneAt ?? Date.now()) - agent.startedAt));
+  return parts.join(" · ") || agent.status;
+}

package/src/domains/workflows/runtime/ui/workflow-result-renderer.ts

@@ -0,0 +1,171 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Box, type Component, Text } from "@earendil-works/pi-tui";
+import { isAdvisoryReport, type AdvisoryReportWithStats } from "../advisory-schema.ts";
+import { renderIssueDetails, renderIssuesTable } from "../review/review-format.ts";
+import { toReviewIssues } from "../review/review-issues.ts";
+import { formatCount } from "./workflow-format.ts";
+import { formatWorkflowUsageLine } from "../usage.ts";
+import type { WorkflowPerfDetails, WorkflowResultEnvelope } from "../workflow-execution.ts";
+import { unknownErrorMessage } from "../unknown-error.ts";
+
+export function isWorkflowResult(value: unknown): value is WorkflowResultEnvelope {
+  if (!isRecord(value)) return false;
+  return typeof value.name === "string" && "result" in value && typeof value.completedAt === "number";
+}
+
+export interface WorkflowRunDisplayMetadata {
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+}
+
+export interface WorkflowDetailLineInput {
+  readonly usage?: unknown;
+  readonly perf?: WorkflowPerfDetails;
+  readonly metadata?: WorkflowRunDisplayMetadata;
+}
+
+export function renderWorkflowResult(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): Component {
+  const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(renderWorkflowResultText(name, result, expanded, theme, usage, metadata, perf), 0, 0));
+  return box;
+}
+
+export function renderWorkflowResultText(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
+  if (isAdvisoryReport(result)) {
+    return renderAdvisoryResult(name, result, expanded, theme, usage, metadata, perf);
+  }
+  return renderGenericWorkflowResult(name, result, expanded, theme, usage, metadata, perf);
+}
+
+function renderAdvisoryResult(
+  name: string,
+  result: AdvisoryReportWithStats,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
+  const incomplete = result.status === "incomplete";
+  const icon = incomplete ? theme.fg("warning", "⚠") : theme.fg("success", "✓");
+  const title = theme.fg("accent", theme.bold(`Workflow: ${name}`));
+  const lines = [`${icon} ${title}`, theme.fg("muted", result.summary)];
+  if (result.coverage?.length) lines.push(theme.fg("dim", result.coverage.map((stage) => `${stage.stage}: ${stage.completed}/${stage.expected} complete, ${stage.failed} failed`).join(" · ")));
+  if (expanded) for (const gap of result.gaps ?? []) lines.push(theme.fg("warning", gap));
+  const stats = statsLine(result.stats, theme);
+  if (stats) lines.push(stats);
+  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
+
+  if (result.findings.length === 0) {
+    lines.push(incomplete ? theme.fg("warning", "No verified findings; coverage is incomplete.") : theme.fg("success", "No findings."));
+    if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
+    return lines.join("\n");
+  }
+
+  const issues = toReviewIssues(name, result);
+  lines.push(theme.fg("dim", "Findings:"));
+  lines.push(renderIssuesTable(issues, theme, { maxRows: expanded ? issues.length : 12 }));
+  if (expanded) {
+    for (const issue of issues) {
+      lines.push(renderIssueDetails(issue, theme));
+    }
+  }
+  if (expanded && result.nextSteps.length > 0) renderNextSteps(result.nextSteps, lines, theme);
+  return lines.join("\n");
+}
+
+function renderNextSteps(nextSteps: string[], lines: string[], theme: Theme): void {
+  lines.push(theme.fg("dim", "Next steps:"));
+  for (const step of nextSteps) {
+    lines.push(`  - ${theme.fg("muted", step)}`);
+  }
+}
+
+function renderGenericWorkflowResult(
+  name: string,
+  result: unknown,
+  expanded: boolean,
+  theme: Theme,
+  usage?: unknown,
+  metadata?: WorkflowRunDisplayMetadata,
+  perf?: WorkflowPerfDetails,
+): string {
+  const lines = [`${theme.fg("success", "✓")} ${theme.fg("accent", theme.bold(`Workflow: ${name}`))}`];
+  const summary = extractSummary(result);
+  if (summary) lines.push(theme.fg("muted", summary));
+  pushWorkflowDetailLines(lines, theme, { usage, metadata, perf });
+  if (expanded) lines.push(theme.fg("dim", safeJson(result)));
+  else if (!summary) lines.push(theme.fg("dim", "Result available in expanded view."));
+  return lines.join("\n");
+}
+
+function pushWorkflowDetailLines(lines: string[], theme: Theme, input: WorkflowDetailLineInput): void {
+  for (const line of formatWorkflowDetailLines(input)) {
+    lines.push(theme.fg("dim", line));
+  }
+}
+
+export function formatWorkflowDetailLines(input: WorkflowDetailLineInput): string[] {
+  return [
+    formatWorkflowRunLine(input.metadata),
+    formatWorkflowUsageLine(input.usage),
+    formatWorkflowPerfLine(input.perf),
+  ].filter((line): line is string => line !== undefined);
+}
+
+export function formatWorkflowRunLine(metadata: WorkflowRunDisplayMetadata | undefined): string | undefined {
+  if (!metadata?.runId) return undefined;
+  return metadata.resumedFromRunId ? `Run: ${metadata.runId} (resumed from ${metadata.resumedFromRunId})` : `Run: ${metadata.runId}`;
+}
+
+export function formatWorkflowPerfLine(perf: WorkflowPerfDetails | undefined): string | undefined {
+  if (!perf) return undefined;
+  const parts = perf.aggregates.slice(0, 4).map((aggregate) => `${aggregate.name} ${Math.round(aggregate.total)}ms`);
+  return parts.length > 0 ? `Perf: ${parts.join(" · ")}` : "Perf: no samples";
+}
+
+function statsLine(stats: Record<string, string | number> | undefined, theme: Theme): string | undefined {
+  if (!stats) return undefined;
+  const ordered = ["files", "candidates", "dropped", "verified", "kept"];
+  const parts = ordered.flatMap((key) => {
+    const value = stats[key];
+    if (value === undefined) return [];
+    return [`${key} ${typeof value === "number" ? formatCount(value) : value}`];
+  });
+  if (parts.length === 0) return undefined;
+  return theme.fg("dim", parts.join(" · "));
+}
+
+function extractSummary(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (isRecord(value) && typeof value.summary === "string") return value.summary;
+  return undefined;
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch (error) {
+    return unknownErrorMessage(error);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}

package/src/domains/workflows/runtime/ui/workflow-viewer-layout.ts

@@ -0,0 +1,51 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+
+const VIEWPORT_HEIGHT_RATIO = 0.7;
+const VIEWPORT_MARGIN_ROWS = 4;
+
+export const WORKFLOW_VIEWER_OVERLAY_OPTIONS = {
+  overlay: true,
+  overlayOptions: {
+    anchor: "center",
+    width: "70%",
+    minWidth: 48,
+    maxHeight: "70%",
+    margin: 2,
+  },
+} as const;
+
+export function workflowViewerHeight(terminalRows: number): number {
+  const rows = Math.max(1, terminalRows);
+  const availableRows = Math.max(1, rows - VIEWPORT_MARGIN_ROWS);
+  const proportionalRows = Math.floor(rows * VIEWPORT_HEIGHT_RATIO);
+  return Math.min(availableRows, Math.max(3, proportionalRows));
+}
+
+export function fitWorkflowViewerRow(text: string, width: number): string {
+  return truncateToWidth(text, Math.max(0, width), "...", true);
+}
+
+export function fitWorkflowViewerRows(lines: readonly string[], height: number): string[] {
+  const visible = lines.slice(0, Math.max(0, height));
+  return [...visible, ...Array.from({ length: Math.max(0, height - visible.length) }, () => "")];
+}
+
+interface WorkflowViewerViewport<T> {
+  readonly visible: readonly T[];
+  readonly percentage: number;
+}
+
+export function centerWorkflowViewerViewport<T>(
+  rows: readonly T[],
+  height: number,
+  selectedIndex: number,
+): WorkflowViewerViewport<T> {
+  const visibleHeight = Math.max(0, Math.floor(height));
+  const clampedSelection = Math.min(Math.max(0, rows.length - 1), Math.max(0, selectedIndex));
+  const maxStart = Math.max(0, rows.length - visibleHeight);
+  const start = Math.min(maxStart, Math.max(0, clampedSelection - Math.floor(visibleHeight / 2)));
+  const visible = rows.slice(start, start + visibleHeight);
+  const end = Math.min(rows.length, start + visible.length);
+  const percentage = rows.length <= visibleHeight ? 100 : Math.round((end / rows.length) * 100);
+  return { visible, percentage };
+}