pi-workflow-engine 0.13.0 → 1.0.0

package/.pi/extensions/pi-workflow-engine/src/ui/kit.ts

@@ -0,0 +1,193 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { formatCount } from "../text.ts";
+import type { WorkflowUsageSnapshot } from "../usage.ts";
+
+/**
+ * The extension's shared visual language. Every screen draws status, severity, usage, hints and
+ * frames through these helpers so the live widget, result messages and overlays read as one product.
+ */
+
+export type ThemeColor = Parameters<Theme["fg"]>[0];
+
+export const GLYPH = {
+  done: "✓",
+  failed: "✗",
+  running: "●",
+  queued: "○",
+  warning: "⚠",
+  bullet: "•",
+  cursor: "›",
+  workflow: "◆",
+  arrow: "→",
+} as const;
+
+export const SEPARATOR = " · ";
+
+export function dot(theme: Theme): string {
+  return theme.fg("dim", SEPARATOR);
+}
+
+export function joinParts(parts: readonly (string | undefined | false)[], theme: Theme): string {
+  return parts.filter((part): part is string => typeof part === "string" && part.length > 0).join(dot(theme));
+}
+
+export type Severity = "high" | "medium" | "low";
+
+export function severityColor(severity: Severity): ThemeColor {
+  return severity === "high" ? "error" : severity === "medium" ? "warning" : "muted";
+}
+
+const SEVERITY_LABEL: Record<Severity, string> = { high: "HIGH", medium: "MED", low: "LOW" };
+
+/** Fixed-width (4 columns) severity badge so finding rows align. */
+export function severityBadge(severity: Severity, theme: Theme): string {
+  const label = SEVERITY_LABEL[severity].padEnd(4, " ");
+  return severity === "high" ? theme.fg("error", theme.bold(label)) : theme.fg(severityColor(severity), label);
+}
+
+export function severityRank(severity: Severity): number {
+  return severity === "high" ? 0 : severity === "medium" ? 1 : 2;
+}
+
+/** `━━━━━───` style bar; empty when there is nothing to measure. */
+export function progressBar(done: number, total: number, width: number, theme: Theme): string {
+  if (total <= 0 || width <= 0) return "";
+  const filled = Math.round((Math.min(done, total) / total) * width);
+  return theme.fg("accent", "━".repeat(filled)) + theme.fg("dim", "─".repeat(width - filled));
+}
+
+/** `↑34k ↓1.2k · $0.02`: input (fresh + cache) and output tokens, cost only when known. */
+export function compactUsage(usage: WorkflowUsageSnapshot | undefined, theme: Theme): string | undefined {
+  if (!usage || usage.totals.totalTokens <= 0) return undefined;
+  const { input, cacheRead, cacheWrite, output, cost } = usage.totals;
+  const parts = [`↑${formatCount(input + cacheRead + cacheWrite)}`, `↓${formatCount(output)}`].join(" ");
+  return cost.total > 0 ? joinParts([parts, formatCost(cost.total)], theme) : parts;
+}
+
+export function formatCost(dollars: number): string {
+  if (dollars <= 0) return "$0";
+  if (dollars < 0.01) return "<$0.01";
+  return `$${dollars < 10 ? dollars.toFixed(2) : dollars.toFixed(1)}`;
+}
+
+/** `5s ago`, `3m ago`, `2h ago`, `4d ago`. */
+export function relativeTime(fromMs: number, nowMs = Date.now()): string {
+  const seconds = Math.max(0, Math.round((nowMs - fromMs) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.round(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 48) return `${hours}h ago`;
+  return `${Math.round(hours / 24)}d ago`;
+}
+
+/** Keeps the file name and line: `src/very/deep/file.ts:12` → `…/deep/file.ts:12`. */
+export function truncatePath(path: string, width: number): string {
+  if (visibleWidth(path) <= width) return path;
+  if (width <= 1) return "…".slice(0, width);
+  const segments = path.split("/");
+  let tail = segments.pop() ?? path;
+  while (segments.length > 0 && visibleWidth(`…/${segments[segments.length - 1]}/${tail}`) <= width) {
+    tail = `${segments.pop()}/${tail}`;
+  }
+  const candidate = `…/${tail}`;
+  return visibleWidth(candidate) <= width ? candidate : `…${tail.slice(-(width - 1))}`;
+}
+
+/** Pads (or truncates) styled text to an exact visible width. */
+export function fit(text: string, width: number): string {
+  if (width <= 0) return "";
+  const truncated = truncateToWidth(text, width, "…");
+  return truncated + " ".repeat(Math.max(0, width - visibleWidth(truncated)));
+}
+
+export function padStartVisible(text: string, width: number): string {
+  return " ".repeat(Math.max(0, width - visibleWidth(text))) + text;
+}
+
+/** Left and right content on one line, the left side truncated first. */
+export function spread(left: string, right: string, width: number): string {
+  const rightWidth = visibleWidth(right);
+  if (rightWidth >= width) return truncateToWidth(right, width, "…");
+  const leftRoom = width - rightWidth - 1;
+  return fit(left, leftRoom) + " " + right;
+}
+
+/** Wraps `text` to `width`, prefixing the first line with `first` and the rest with matching spaces. */
+export function hangingWrap(text: string, width: number, first = "", rest = " ".repeat(visibleWidth(first))): string[] {
+  const available = Math.max(8, width - visibleWidth(first));
+  const lines = wrapTextWithAnsi(text, available);
+  if (lines.length === 0) return [first.trimEnd()];
+  return lines.map((line, index) => `${index === 0 ? first : rest}${line}`);
+}
+
+/** `↑↓ move · enter open · q close` in pi's hint style (dim key, muted description). */
+export function keyHints(pairs: readonly (readonly [key: string, description: string])[], theme: Theme): string {
+  return pairs.map(([key, description]) => `${theme.fg("dim", key)} ${theme.fg("muted", description)}`).join(dot(theme));
+}
+
+export interface Tab {
+  readonly label: string;
+  readonly count?: number;
+}
+
+/** A tab strip; the active tab is bold on the selection background. */
+export function tabBar(tabs: readonly Tab[], active: number, theme: Theme): string {
+  return tabs
+    .map((tab, index) => {
+      const count = tab.count === undefined ? "" : ` ${tab.count}`;
+      if (index === active) return theme.bg("selectedBg", theme.bold(` ${tab.label}${count} `));
+      return ` ${theme.fg("muted", tab.label)}${theme.fg("dim", count)} `;
+    })
+    .join(theme.fg("dim", "│"));
+}
+
+export interface FrameOptions {
+  readonly title: string;
+  readonly right?: string;
+  readonly footer?: string;
+  readonly borderColor?: ThemeColor;
+}
+
+/**
+ * A rounded overlay frame with the title set into the top border and hints into the bottom one:
+ * `╭─ title ─────── right ─╮` … `╰─ hints ──────────────╯`. Body lines are padded to the width.
+ */
+export function frame(body: readonly string[], width: number, theme: Theme, options: FrameOptions): string[] {
+  const outer = Math.max(8, width);
+  const inner = outer - 4;
+  const border = (text: string) => theme.fg(options.borderColor ?? "borderAccent", text);
+  return [
+    borderLine("╭", "╮", options.title, options.right, outer, border),
+    ...body.map((line) => `${border("│")} ${fit(line, inner)} ${border("│")}`),
+    borderLine("╰", "╯", options.footer, undefined, outer, border),
+  ];
+}
+
+function borderLine(
+  left: string,
+  right: string,
+  label: string | undefined,
+  rightLabel: string | undefined,
+  width: number,
+  border: (text: string) => string,
+): string {
+  const room = width - 2;
+  const leftPart = label ? `${border("─")} ${truncateToWidth(label, Math.max(0, room - 4), "…")} ` : "";
+  const rightPart = rightLabel ? ` ${truncateToWidth(rightLabel, Math.max(0, room - visibleWidth(leftPart) - 4), "…")} ${border("─")}` : "";
+  const fill = Math.max(0, room - visibleWidth(leftPart) - visibleWidth(rightPart));
+  return `${border(left)}${leftPart}${border("─".repeat(fill))}${rightPart}${border(right)}`;
+}
+
+/** Overlay height: content-sized between a floor and 80% of the terminal, never more than `max`. */
+export function overlayHeight(terminalRows: number, contentRows: number, options: { min?: number; max?: number } = {}): number {
+  const ceiling = Math.max(6, Math.min(options.max ?? 40, Math.floor(terminalRows * 0.8), terminalRows - 2));
+  return Math.max(Math.min(options.min ?? 10, ceiling), Math.min(ceiling, contentRows));
+}
+
+/** A one-line scroll hint shown only when content is clipped: `↑ 3 more` / `↓ 12 more`. */
+export function scrollHint(above: number, below: number, theme: Theme): string | undefined {
+  const parts = [above > 0 ? `↑ ${above} more` : undefined, below > 0 ? `↓ ${below} more` : undefined];
+  return parts.some(Boolean) ? theme.fg("dim", parts.filter(Boolean).join("  ")) : undefined;
+}

package/.pi/extensions/pi-workflow-engine/src/ui/research-result-renderer.ts

@@ -0,0 +1,177 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { getCapabilities, hyperlink, truncateToWidth } from "@earendil-works/pi-tui";
+import { Value } from "typebox/value";
+import { ResearchReportSchema, type ResearchReport, type ResearchReportEntry, type ResearchSource } from "../research-contract.ts";
+import { GLYPH, hangingWrap, joinParts } from "./kit.ts";
+import {
+  bullets,
+  footerLine,
+  headerLine,
+  indent,
+  innerWidth,
+  paragraph,
+  plural,
+  runDetailRows,
+  type ResultFrame,
+} from "./result-layout.ts";
+
+const COLLAPSED_ANSWER_LINES = 4;
+const COLLAPSED_CLAIMS = 3;
+const COLLAPSED_CLAIM_LINES = 2;
+
+export function isResearchReport(value: unknown): value is ResearchReport {
+  return Value.Check(ResearchReportSchema, value);
+}
+
+interface ClaimGroup {
+  readonly title: string;
+  readonly fact: string;
+  readonly tag: string;
+  readonly entries: readonly ResearchReportEntry[];
+}
+
+/** Numbers each distinct source once, in report order, so claims cite `[1][2]` and the list matches. */
+class SourceIndex {
+  readonly sources: ResearchSource[] = [];
+  private readonly numbers = new Map<string, number>();
+
+  constructor(sources: readonly ResearchSource[]) {
+    for (const source of sources) this.number(source);
+  }
+
+  number(source: ResearchSource): number {
+    const key = source.url.trim();
+    const existing = this.numbers.get(key);
+    if (existing !== undefined) return existing;
+    this.sources.push(source);
+    this.numbers.set(key, this.sources.length);
+    return this.sources.length;
+  }
+}
+
+/**
+ * The research report: the answer, numbered claims with `[n]` citations, the non-empty conflicting and
+ * uncertain groups, and the numbered source list. Collapsed keeps the answer and the top claims.
+ */
+export function renderResearchResult(frame: ResultFrame, report: ResearchReport): string[] {
+  const { expanded, theme } = frame;
+  const width = innerWidth(frame);
+  const groups: ClaimGroup[] = [
+    { title: "Supported claims", fact: "supported", tag: "", entries: report.supportedClaims },
+    { title: "Conflicting evidence", fact: "conflicting", tag: "conflicting", entries: report.conflictingEvidence },
+    { title: "Uncertain", fact: "uncertain", tag: "uncertain", entries: report.uncertainties },
+    { title: "Inferences", fact: "inferred", tag: "inference", entries: report.inferences },
+  ];
+  const sources = new SourceIndex(report.sources);
+  const markers = new Map<ResearchReportEntry, string>();
+  for (const group of groups) {
+    for (const entry of group.entries) markers.set(entry, citationMarkers(entry, sources, theme));
+  }
+
+  const claimCount = groups.reduce((sum, group) => sum + group.entries.length, 0);
+  const facts = [
+    claimCount === 0 ? theme.fg("warning", "no verified claims") : undefined,
+    ...groups.map((group) => (group.entries.length > 0 ? theme.fg(group.fact === "supported" ? "text" : "warning", `${group.entries.length} ${group.fact}`) : undefined)),
+  ];
+  const sourceFacts = sources.sources.length > 0 ? [theme.fg("muted", plural(sources.sources.length, "source"))] : [];
+  const glyph = claimCount > 0 ? theme.fg("success", GLYPH.done) : theme.fg("warning", GLYPH.warning);
+  const lines = [headerLine(glyph, frame, facts, sourceFacts)];
+  if (report.answer.trim()) {
+    lines.push(...indent(paragraph(report.answer, width, (line) => theme.fg("text", line), expanded ? undefined : COLLAPSED_ANSWER_LINES)));
+  }
+
+  if (expanded) {
+    for (const group of groups) {
+      if (group.entries.length === 0) continue;
+      lines.push("", ...indent([heading(group.title, group.entries.length, theme)]));
+      group.entries.forEach((entry, index) => lines.push(...indent(claimLines(entry, index, markers.get(entry) ?? "", width, theme, true))));
+    }
+    if (sources.sources.length > 0) {
+      lines.push("", ...indent([heading("Sources", sources.sources.length, theme)]));
+      sources.sources.forEach((source, index) => lines.push(...indent(sourceLines(source, index + 1, width, theme))));
+    }
+    for (const [title, items] of [["Limitations", report.limitations], ["Next steps", report.nextSteps]] as const) {
+      if (items.length === 0) continue;
+      lines.push("", ...indent([heading(title, undefined, theme)]));
+      lines.push(...indent(bullets(items).flatMap((item) => hangingWrap(theme.fg("muted", item), width, "", "  "))));
+    }
+    const rows = runDetailRows(frame);
+    if (rows.length > 0) lines.push("", ...rows);
+  } else {
+    const featured = featuredClaims(groups);
+    if (featured.length > 0) {
+      lines.push("");
+      featured.slice(0, COLLAPSED_CLAIMS).forEach(({ entry, tag }, index) => {
+        const marker = joinParts([markers.get(entry), tag ? theme.fg("warning", tag) : undefined], theme);
+        lines.push(...indent(claimLines(entry, index, marker, width, theme, false)));
+      });
+      const hidden = claimCount - Math.min(COLLAPSED_CLAIMS, featured.length);
+      if (hidden > 0) lines.push(...indent([theme.fg("dim", `+${plural(hidden, "more claim", "more claims")}`)]));
+    } else if (report.nextSteps[0]) {
+      lines.push(...indent(hangingWrap(theme.fg("muted", report.nextSteps[0]), width, theme.fg("dim", `${GLYPH.arrow} `))));
+    }
+  }
+
+  const footer = footerLine(frame, [], { more: true });
+  if (footer) lines.push(footer);
+  return lines;
+}
+
+/** Supported claims lead; without any, the other groups stand in, each tagged with its kind. */
+function featuredClaims(groups: readonly ClaimGroup[]): { readonly entry: ResearchReportEntry; readonly tag: string }[] {
+  const [supported, ...rest] = groups;
+  if (supported && supported.entries.length > 0) return supported.entries.map((entry) => ({ entry, tag: "" }));
+  return rest.flatMap((group) => group.entries.map((entry) => ({ entry, tag: group.tag })));
+}
+
+function citationMarkers(entry: ResearchReportEntry, sources: SourceIndex, theme: Theme): string {
+  const numbers = [...new Set(entry.citations.map((citation) => sources.number(citation)))].sort((a, b) => a - b);
+  return numbers.map((number) => theme.fg("accent", `[${number}]`)).join("");
+}
+
+function heading(title: string, count: number | undefined, theme: Theme): string {
+  return `${theme.bold(title)}${count === undefined ? "" : theme.fg("dim", ` ${count}`)}`;
+}
+
+/** `1. claim [1][2]` with a hanging indent; expanded adds the explanation beneath. */
+function claimLines(entry: ResearchReportEntry, index: number, marker: string, width: number, theme: Theme, expanded: boolean): string[] {
+  const number = `${index + 1}. `;
+  const rest = " ".repeat(number.length);
+  const claim = `${theme.fg("text", entry.claim)}${marker ? ` ${marker}` : ""}`;
+  const lines = hangingWrap(claim, width, theme.fg("dim", number), rest);
+  if (!expanded) return clampLines(lines, COLLAPSED_CLAIM_LINES, width);
+  return [...lines, ...hangingWrap(theme.fg("muted", entry.explanation), width, rest)];
+}
+
+function clampLines(lines: string[], max: number, width: number): string[] {
+  if (lines.length <= max) return lines;
+  const kept = lines.slice(0, max);
+  kept[max - 1] = `${truncateToWidth(kept[max - 1] ?? "", Math.max(1, width - 1), "")}…`;
+  return kept;
+}
+
+/** `[1] Title · docs.example.dev · 2026-09-14`; the title is a link where the terminal supports one, else the URL follows. */
+function sourceLines(source: ResearchSource, number: number, width: number, theme: Theme): string[] {
+  const linkable = getCapabilities().hyperlinks;
+  const title = theme.fg("accent", source.title.trim());
+  const head = theme.fg("dim", `[${number}] `);
+  const rest = " ".repeat(`[${number}] `.length);
+  const host = sourceHost(source.url);
+  const date = source.publishedAt?.trim();
+  const line = joinParts([
+    linkable ? hyperlink(title, source.url) : title,
+    host ? theme.fg("muted", host) : undefined,
+    date ? theme.fg("muted", date) : undefined,
+  ], theme);
+  const lines = hangingWrap(line, width, head, rest);
+  if (!linkable) lines.push(...hangingWrap(theme.fg("dim", source.url), width, rest));
+  return lines;
+}
+
+function sourceHost(url: string): string | undefined {
+  try {
+    return new URL(url).host.replace(/^www\./, "");
+  } catch {
+    return undefined;
+  }
+}

package/.pi/extensions/pi-workflow-engine/src/ui/result-layout.ts

@@ -0,0 +1,209 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
+import { isFiniteNumber, isRecord } from "../guards.ts";
+import { labelledLines } from "../review/review-format.ts";
+import { formatCount } from "../text.ts";
+import { isWorkflowUsageSnapshot } from "../usage.ts";
+import { formatCost, GLYPH, joinParts, keyHints, spread } from "./kit.ts";
+import { formatDuration } from "./workflow-format.ts";
+
+/**
+ * Layout shared by every workflow result screen: a status header with right-aligned run metadata,
+ * an indented body, labelled detail rows, and a hint footer. Everything is drawn for one width.
+ */
+
+/** What the result renderers read. Persisted message details are unvalidated, so `usage` stays `unknown`. */
+export interface WorkflowResultView {
+  readonly name: string;
+  readonly result: unknown;
+  readonly usage?: unknown;
+  readonly perf?: unknown;
+  readonly runId?: string;
+  readonly resumedFromRunId?: string;
+  readonly startedAt?: unknown;
+  readonly completedAt?: unknown;
+  /** Set on background deliveries, together with the run's final `status`. */
+  readonly background?: unknown;
+  readonly status?: unknown;
+}
+
+/** Keys the result footer advertises; a missing key hides its hint. */
+export interface WorkflowResultHints {
+  /** Opens the code-review findings viewer: the configured shortcut, or `/workflow:results` when unbound. */
+  readonly triage?: string;
+  /** Opens the live or most recent run's inspector: the configured shortcut, or `/workflow:inspector` when unbound. */
+  readonly inspect?: string;
+  /** pi's expand-tool-output key (`app.tools.expand`). */
+  readonly expand?: string;
+}
+
+export interface ResultFrame {
+  readonly view: WorkflowResultView;
+  readonly expanded: boolean;
+  readonly width: number;
+  readonly theme: Theme;
+  readonly hints: WorkflowResultHints;
+}
+
+export type HintPair = readonly [key: string, description: string];
+
+export const INDENT = "  ";
+
+/** Body width once the two-column indent is taken. */
+export function innerWidth(frame: ResultFrame): number {
+  return Math.max(10, frame.width - INDENT.length);
+}
+
+/** Renders lines for the width pi offers and caches them until the width or theme changes. */
+export class LinesComponent implements Component {
+  private cache: { readonly width: number; readonly lines: string[] } | undefined;
+
+  constructor(private readonly draw: (width: number) => string[]) {}
+
+  render(width: number): string[] {
+    if (this.cache?.width !== width) {
+      this.cache = { width, lines: this.draw(width).map((line) => truncateToWidth(line, width, "…")) };
+    }
+    return this.cache.lines;
+  }
+
+  invalidate(): void {
+    this.cache = undefined;
+  }
+}
+
+/**
+ * `✓ code-review  3 findings · 1 high              4s · ↑34k ↓1k · $0.02`. Run metadata is right-aligned.
+ * When the line is too narrow, cost and tokens go first, then the optional facts, then the duration,
+ * so the essential facts never wrap.
+ */
+export function headerLine(glyph: string, frame: ResultFrame, facts: readonly (string | undefined)[], optionalFacts: readonly string[] = []): string {
+  const { theme, width } = frame;
+  const leftFor = (parts: readonly (string | undefined)[]) => {
+    const joined = joinParts(parts, theme);
+    return `${glyph} ${theme.bold(frame.view.name)}${joined ? `  ${joined}` : ""}`;
+  };
+  const meta = runMeta(frame);
+  const variants: { readonly left: string; readonly meta: number }[] = [];
+  const full = leftFor([...facts, ...optionalFacts]);
+  for (let count = meta.length; count >= 1; count--) variants.push({ left: full, meta: count });
+  if (optionalFacts.length > 0) variants.push({ left: leftFor(facts), meta: Math.min(1, meta.length) });
+  for (const variant of variants) {
+    const right = joinParts(meta.slice(0, variant.meta), theme);
+    if (visibleWidth(variant.left) + 2 + visibleWidth(right) <= width) return spread(variant.left, right, width);
+  }
+  const left = visibleWidth(full) <= width || optionalFacts.length === 0 ? full : leftFor(facts);
+  return truncateToWidth(left, width, "…");
+}
+
+/** Duration, then tokens, then cost; zeros and unknowns are left out. */
+function runMeta({ view, theme }: ResultFrame): string[] {
+  const parts: string[] = [];
+  const duration = runDuration(view);
+  if (duration !== undefined) parts.push(theme.fg("muted", formatDuration(duration)));
+  if (isWorkflowUsageSnapshot(view.usage) && view.usage.totals.totalTokens > 0) {
+    const { input, cacheRead, cacheWrite, output, cost } = view.usage.totals;
+    parts.push(theme.fg("muted", `↑${formatCount(input + cacheRead + cacheWrite)} ↓${formatCount(output)}`));
+    if (cost.total > 0) parts.push(theme.fg("muted", formatCost(cost.total)));
+  }
+  return parts;
+}
+
+function runDuration(view: WorkflowResultView): number | undefined {
+  if (!isFiniteNumber(view.startedAt) || !isFiniteNumber(view.completedAt)) return undefined;
+  const ms = view.completedAt - view.startedAt;
+  return ms > 0 ? ms : undefined;
+}
+
+export function agentCount(view: WorkflowResultView): number {
+  return isWorkflowUsageSnapshot(view.usage) ? view.usage.agents.length : 0;
+}
+
+/** `3 findings`, `1 finding`. */
+export function plural(count: number, noun: string, pluralNoun = `${noun}s`): string {
+  return `${count} ${count === 1 ? noun : pluralNoun}`;
+}
+
+/** Wraps plain text to `width`, styling each line, and ends a clipped paragraph with `…`. */
+export function paragraph(text: string, width: number, style: (line: string) => string, maxLines = Number.POSITIVE_INFINITY): string[] {
+  const lines = wrapTextWithAnsi(text.trim(), Math.max(8, width));
+  if (lines.length > maxLines) {
+    lines.length = maxLines;
+    lines[maxLines - 1] = `${truncateToWidth(lines[maxLines - 1] ?? "", Math.max(1, width - 1), "")}…`;
+  }
+  return lines.map(style);
+}
+
+/** True when `paragraph` would clip the text at `maxLines`. */
+export function clips(text: string, width: number, maxLines: number): boolean {
+  return wrapTextWithAnsi(text.trim(), Math.max(8, width)).length > maxLines;
+}
+
+export function indent(lines: readonly string[]): string[] {
+  return lines.map((line) => (line ? `${INDENT}${line}` : line));
+}
+
+/** Labelled rows aligned with finding details: `Run       3cfb22c2-… · resumed from 1a2b3c4d`. */
+export function labelled(frame: ResultFrame, label: string, items: readonly string[], itemIndent = ""): string[] {
+  if (items.length === 0) return [];
+  return indent(labelledLines(label, items, innerWidth(frame), frame.theme, itemIndent));
+}
+
+export function bullets(items: readonly string[]): string[] {
+  return items.map((item) => `${GLYPH.bullet} ${item}`);
+}
+
+/** The full run identity (with the agent count unless the header has it) and perf samples, shown only when expanded. */
+export function runDetailRows(frame: ResultFrame, options: { readonly agents: boolean } = { agents: true }): string[] {
+  const { view, theme } = frame;
+  const agents = options.agents ? agentCount(view) : 0;
+  const run = view.runId
+    ? joinParts([
+      theme.fg("muted", view.runId),
+      view.resumedFromRunId ? theme.fg("muted", `resumed from ${shortRunId(view.resumedFromRunId)}`) : undefined,
+      view.background === true ? theme.fg("muted", "background") : undefined,
+      agents > 0 ? theme.fg("muted", plural(agents, "agent")) : undefined,
+    ], theme)
+    : undefined;
+  const perf = perfSamples(view.perf);
+  return [
+    ...(run ? labelled(frame, "Run", [run]) : []),
+    ...labelled(frame, "Perf", perf.length > 0 ? [theme.fg("muted", perf.join(" · "))] : []),
+  ];
+}
+
+function perfSamples(perf: unknown): string[] {
+  if (!isRecord(perf) || !Array.isArray(perf.aggregates)) return [];
+  return perf.aggregates
+    .flatMap((aggregate: unknown) => (isRecord(aggregate) && typeof aggregate.name === "string" && isFiniteNumber(aggregate.total)
+      ? [`${aggregate.name} ${Math.round(aggregate.total)}ms`]
+      : []))
+    .slice(0, 6);
+}
+
+export function shortRunId(runId: string): string {
+  return runId.slice(0, 8);
+}
+
+/**
+ * `ctrl+shift+r triage · ctrl+shift+m inspect · ctrl+o expand · run 3cfb22c2`. Collapsed results name the short run id;
+ * expanded ones show the full id in the Run row instead, so it is not repeated here.
+ */
+export function footerLine(frame: ResultFrame, pairs: readonly HintPair[], options: { readonly more: boolean }): string | undefined {
+  const { view, theme, hints, expanded } = frame;
+  const allPairs = [...pairs];
+  if (hints.inspect) allPairs.push([hints.inspect, "inspect"]);
+  if (hints.expand && (expanded || options.more)) allPairs.push([hints.expand, expanded ? "collapse" : "expand"]);
+  const keys = allPairs.length > 0 ? keyHints(allPairs, theme) : undefined;
+  const facts = expanded ? [] : [
+    view.runId ? theme.fg("dim", `run ${shortRunId(view.runId)}`) : undefined,
+    view.background === true ? theme.fg("dim", "background") : undefined,
+  ];
+  // The run facts give way before any key hint is cut.
+  for (let count = facts.length; count >= 0; count--) {
+    const line = joinParts([keys, ...facts.slice(0, count)], theme);
+    if (!line) return undefined;
+    if (count === 0 || visibleWidth(line) <= innerWidth(frame)) return `${INDENT}${line}`;
+  }
+  return undefined;
+}