@yaag/tui 0.1.0

package/src/tree-navigator.ts

@@ -0,0 +1,70 @@
+import { resolveSelection } from "./tree-cursor.ts";
+import type { FoldState } from "./tree-fold.ts";
+import { type NamedKeybindings, routeTreeKey } from "./tree-keys.ts";
+import { applyTreeAction, emptyView, type TreeView } from "./tree-navigation.ts";
+import type { TreeNode } from "./tree-node.ts";
+
+/** What the keyboard router needs from its host component. */
+export interface TreeNavigatorOptions {
+  /** The current node tree, re-read on every key: a live Run keeps growing. */
+  snapshot(): readonly TreeNode[];
+  /** pi's injected manager in the Host Session, `cliKeybindings()` in the CLI. */
+  readonly keybindings: NamedKeybindings;
+  /**
+   * Whether the tree holds input focus. Defaults to always focused, because pi
+   * and pi-tui dispatch input to the focused component only; a host that layers
+   * an overlay over the tree passes its own predicate (spec §2).
+   */
+  focused?(): boolean;
+}
+
+/**
+ * The tree's keyboard router: it owns the cursor and the user's folds and turns
+ * input bytes into cursor and fold moves.
+ *
+ * `handleInput` reports whether the tree consumed the byte. It consumes only
+ * the keys of `TREE_KEY_TABLE`, and nothing at all without input focus, so no
+ * other pi default binding is shadowed (spec §2).
+ */
+export class TreeNavigator {
+  readonly #options: TreeNavigatorOptions;
+  #view: TreeView = emptyView();
+
+  constructor(options: TreeNavigatorOptions) {
+    this.#options = options;
+  }
+
+  /**
+   * The visible node the cursor rests on, re-resolved against the live tree, so
+   * a branch that the default fold collapses on its own — its nested work has
+   * settled — carries the cursor up to the collapsed ancestor.
+   *
+   * The resolved path is written back into the navigator state, so the move to
+   * the ancestor is permanent: later live work that re-expands the branch does
+   * not restore the cursor to the node the fold hid (spec §2).
+   */
+  get selectedPath(): string | undefined {
+    const resolved = resolveSelection(
+      this.#options.snapshot(),
+      this.#view.fold,
+      this.#view.selectedPath,
+    );
+    if (resolved !== this.#view.selectedPath)
+      this.#view = { ...this.#view, selectedPath: resolved };
+    return resolved;
+  }
+
+  /** The user's explicit folds, for `renderTree`'s `fold` option. */
+  get fold(): FoldState {
+    return this.#view.fold;
+  }
+
+  /** Routes one input byte string; returns whether the tree consumed it. */
+  handleInput(data: string): boolean {
+    if (this.#options.focused?.() === false) return false;
+    const action = routeTreeKey(data, this.#options.keybindings);
+    if (action === undefined) return false;
+    this.#view = applyTreeAction(this.#options.snapshot(), this.#view, action);
+    return true;
+  }
+}

package/src/tree-nested.ts

@@ -0,0 +1,129 @@
+import { type NodeInfo, sanitizeNodeName } from "@yaag/runtime";
+import { costText, tokensText } from "./accounting-text.ts";
+import { durationText } from "./duration-text.ts";
+import { parseNodePath } from "./node-path-parse.ts";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import type { TreeNode, TreeNodeKind, TreeNodeState } from "./tree-node.ts";
+
+interface Draft {
+  readonly path: string;
+  readonly kind: TreeNodeKind;
+  label: string;
+  state: TreeNodeState;
+  facts: readonly string[];
+  activityGist: string | null;
+  startedAt: number | null;
+  readonly children: Map<string, Draft>;
+}
+
+/**
+ * Grafts one Agent's bounded node table onto its Asks, keyed by node path.
+ *
+ * Returns the Nested Node children of each Ask index. A path that does not
+ * parse, or whose first segment is not this Agent with an Ask index, is
+ * dropped: an unattributable `node_update` renders nothing rather than a
+ * forged row. Intermediate segments materialize even when only a deep leaf
+ * reported.
+ */
+export function graftNestedNodes(
+  agent: string,
+  nodes: readonly NodeInfo[],
+  now: number,
+): ReadonlyMap<number, readonly TreeNode[]> {
+  const roots = new Map<number, Map<string, Draft>>();
+  const expected = sanitizeNodeName(agent);
+  for (const node of nodes) {
+    const segments = parseNodePath(node.path);
+    const first = segments?.[0];
+    if (segments === undefined || segments === null || first === undefined) continue;
+    if (first.name !== expected || first.askIndex === undefined) continue;
+    const container = roots.get(first.askIndex) ?? new Map<string, Draft>();
+    roots.set(first.askIndex, container);
+    graft(container, `${first.name}:${first.askIndex}`, segments.slice(1), node, now);
+  }
+  const grafted = new Map<number, readonly TreeNode[]>();
+  for (const [index, container] of roots) grafted.set(index, freezeAll(container));
+  return grafted;
+}
+
+function graft(
+  container: Map<string, Draft>,
+  prefix: string,
+  segments: readonly { readonly name: string; readonly askIndex?: number }[],
+  node: NodeInfo,
+  now: number,
+): void {
+  let where = container;
+  let path = prefix;
+  for (const [position, segment] of segments.entries()) {
+    path = `${path}/${segment.name}`;
+    const nested = upsert(where, path, "nested", sanitizeTerminalLine(segment.name));
+    if (position === segments.length - 1) applyNode(nested, node, now);
+    if (segment.askIndex === undefined) {
+      where = nested.children;
+      continue;
+    }
+    path = `${path}:${segment.askIndex}`;
+    where = upsert(nested.children, path, "ask", askLabel(segment.askIndex)).children;
+  }
+}
+
+function upsert(
+  container: Map<string, Draft>,
+  path: string,
+  kind: TreeNodeKind,
+  label: string,
+): Draft {
+  const existing = container.get(path);
+  if (existing !== undefined) return existing;
+  const draft: Draft = {
+    path,
+    kind,
+    label,
+    state: "running",
+    facts: [],
+    activityGist: null,
+    startedAt: null,
+    children: new Map(),
+  };
+  container.set(path, draft);
+  return draft;
+}
+
+function applyNode(draft: Draft, node: NodeInfo, now: number): void {
+  draft.state = node.state === "failed" ? "failed" : node.state;
+  draft.activityGist = node.activityGist === null ? null : sanitizeTerminalLine(node.activityGist);
+  draft.startedAt = node.updatedAt;
+  draft.facts = nodeFacts(node, now);
+}
+
+function nodeFacts(node: NodeInfo, now: number): readonly string[] {
+  const facts: string[] = [];
+  if (node.state === "running")
+    facts.push(`running ${durationText(now - (node.updatedAt ?? now))}`);
+  else facts.push(node.state);
+  if (node.cost !== null) facts.push(costText(node.cost));
+  if (node.tokens !== null) facts.push(tokensText(node.tokens.total));
+  return facts;
+}
+
+function askLabel(index: number): string {
+  return `ask #${index + 1}`;
+}
+
+function freezeAll(container: Map<string, Draft>): readonly TreeNode[] {
+  return [...container.values()].map(freeze);
+}
+
+function freeze(draft: Draft): TreeNode {
+  return {
+    path: draft.path,
+    kind: draft.kind,
+    label: draft.label,
+    state: draft.state,
+    facts: draft.facts,
+    children: freezeAll(draft.children),
+    activityGist: draft.activityGist,
+    startedAt: draft.startedAt,
+  };
+}

package/src/tree-node.ts

@@ -0,0 +1,20 @@
+/** What one tree row represents. */
+export type TreeNodeKind = "agent" | "ask" | "nested" | "rollup";
+
+/** The drawn lifecycle state of one tree row. */
+export type TreeNodeState = "running" | "idle" | "exited" | "failed";
+
+/** One node of the Run tree, identified by its path (spec §1). */
+export interface TreeNode {
+  /** The node's identity: `name(:askIndex(/childName…))`. */
+  readonly path: string;
+  readonly kind: TreeNodeKind;
+  readonly label: string;
+  readonly state: TreeNodeState;
+  /** Right-hand facts, already formatted: dwell, cost, tokens. */
+  readonly facts: readonly string[];
+  readonly children: readonly TreeNode[];
+  /** The current tool-call gist, drawn as the `└`-line under a running node. */
+  readonly activityGist: string | null;
+  readonly startedAt: number | null;
+}

package/src/tree-render.ts

@@ -0,0 +1,91 @@
+import { costText } from "./accounting-text.ts";
+import { renderDetailsPane } from "./details-pane.ts";
+import { durationText } from "./duration-text.ts";
+import { agentOfPath } from "./node-path-parse.ts";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { emptyFold, type FoldState, type VisibleRow, visibleRows } from "./tree-fold.ts";
+import { buildTree } from "./tree-model.ts";
+import type { TreeNode } from "./tree-node.ts";
+import { clamp, renderRow } from "./tree-rows.ts";
+import type { TreeState } from "./tree-state.ts";
+
+/** Tree rows drawn before the renderer rolls the remainder into one line. */
+const MAX_TREE_ROWS = 64;
+
+const FOOTER = " ↑↓ move  ←→ fold  ↵ actions  t transcript  esc back";
+
+/** Everything the full view needs; `now` keeps the renderer clock-free. */
+export interface TreeRenderOptions {
+  readonly now: number;
+  readonly width: number;
+  /** Header text before the Program name; defaults to `yaag`. */
+  readonly label?: string;
+  readonly selectedPath?: string;
+  readonly fold?: FoldState;
+  /** The settled Run's Result, or the error plus bounded stderr tail. */
+  readonly result?: string;
+}
+
+/**
+ * Renders the four stacked regions — header, tree, details pane, key footer —
+ * as unstyled terminal lines, every line truncated to `width`.
+ *
+ * Pure over the state: two calls with the same state and options return equal
+ * arrays. Every untrusted string passes `sanitizeTerminalLine` first, so a
+ * hostile gist or path can neither add a line nor emit an escape byte.
+ */
+export function renderTree(state: TreeState, options: TreeRenderOptions): readonly string[] {
+  const tree = buildTree(state, { now: options.now });
+  const rows = visibleRows(tree, options.fold ?? emptyFold());
+  const rule = "─".repeat(Math.max(1, Math.floor(options.width)));
+  const selected = selectedNode(rows, options.selectedPath);
+  const lines = [headerLine(state, options), rule, ...treeLines(rows, options), rule];
+  const details = renderDetailsPane(selected, {
+    width: options.width,
+    outputTail: selected === undefined ? [] : state.outputTail(agentOfPath(selected.path)),
+  });
+  if (details.length > 0) lines.push(...details, rule);
+  const result = options.result ?? state.result;
+  if (result !== undefined) {
+    lines.push(clamp("Result:", options.width));
+    for (const line of result.split("\n"))
+      lines.push(clamp(`  ${sanitizeTerminalLine(line)}`, options.width));
+    lines.push(rule);
+  }
+  lines.push(clamp(FOOTER, options.width));
+  return lines;
+}
+
+function treeLines(rows: readonly VisibleRow[], options: TreeRenderOptions): readonly string[] {
+  const shown = rows.slice(0, MAX_TREE_ROWS);
+  const lines = shown.flatMap((row) =>
+    renderRow(row, { width: options.width, selectedPath: options.selectedPath }),
+  );
+  const hidden = rows.length - shown.length;
+  if (hidden > 0) lines.push(clamp(` and ${hidden} more running`, options.width));
+  return lines;
+}
+
+function headerLine(state: TreeState, options: TreeRenderOptions): string {
+  const summary = state.summary;
+  const elapsed =
+    summary.runState === "ended"
+      ? summary.durationMs
+      : options.now - (summary.startedAt ?? options.now);
+  const status = summary.runState === "ended" ? summary.outcome : "running";
+  const asks = `${summary.asksSettled} ask${summary.asksSettled === 1 ? "" : "s"} settled`;
+  const label = sanitizeTerminalLine(options.label ?? "yaag");
+  const program = sanitizeTerminalLine(summary.program === "" ? "Run" : summary.program);
+  return clamp(
+    `${label} ▸ ${program}   ${status} ${durationText(elapsed)}   ${costText(summary.cost, summary.incomplete)} · ${asks}`,
+    options.width,
+  );
+}
+
+function selectedNode(
+  rows: readonly VisibleRow[],
+  selectedPath: string | undefined,
+): TreeNode | undefined {
+  if (selectedPath === undefined) return undefined;
+  return rows.find((row) => row.node.path === selectedPath)?.node;
+}

package/src/tree-rows.ts

@@ -0,0 +1,64 @@
+import { visibleWidth } from "@earendil-works/pi-tui";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import type { VisibleRow } from "./tree-fold.ts";
+import { foldGlyph, GLYPHS, stateGlyph } from "./tree-glyphs.ts";
+
+/** Marks the selected row in the drawn tree, matched by node path. */
+export interface TreeRowOptions {
+  readonly width: number;
+  readonly selectedPath?: string;
+}
+
+/**
+ * Draws one visible row, plus the `└`-line that carries a running node's
+ * current tool-call gist when the row draws no children of its own.
+ *
+ * Every untrusted string is sanitized to one line first, so a hostile gist
+ * cannot forge an extra row, and the result is truncated to `width`.
+ */
+export function renderRow(row: VisibleRow, options: TreeRowOptions): readonly string[] {
+  const prefix = ancestryPrefix(row);
+  const selected = options.selectedPath === row.node.path;
+  const facts = row.node.facts.map(sanitizeTerminalLine).join(" · ");
+  const head = `${selected ? "❯" : " "}${prefix}${foldGlyph(row.hasChildren, row.expanded)} ${stateGlyph(row.node.state)} ${sanitizeTerminalLine(row.node.label)}`;
+  const lines = [clamp(facts === "" ? head : `${head}   ${facts}`, options.width)];
+  const gist = row.node.activityGist;
+  if (gist !== null && !row.expanded) {
+    lines.push(
+      clamp(
+        ` ${prefix}  ${GLYPHS.branch} ${GLYPHS.running} ${sanitizeTerminalLine(gist)}`,
+        options.width,
+      ),
+    );
+  }
+  return lines;
+}
+
+/**
+ * Truncates one already sanitized line to a terminal column count, measuring
+ * columns rather than code points so a CJK or emoji label cannot overflow.
+ *
+ * pi-tui's `truncateToWidth` is deliberately not used: it appends a colour
+ * reset sequence, and this package emits unstyled lines only.
+ */
+export function clamp(value: string, width: number): string {
+  const limit = Math.max(1, Math.floor(width));
+  if (visibleWidth(value) <= limit) return value;
+  let text = "";
+  let used = 0;
+  for (const character of value) {
+    const next = used + visibleWidth(character);
+    if (next > limit - 1) break;
+    text += character;
+    used = next;
+  }
+  return `${text}…`;
+}
+
+function ancestryPrefix(row: VisibleRow): string {
+  let prefix = "";
+  for (let depth = 0; depth < row.depth; depth += 1) {
+    prefix += row.lastAtDepth[depth] === true ? "   " : `${GLYPHS.trunk}  `;
+  }
+  return prefix;
+}

package/src/tree-state.ts

@@ -0,0 +1,199 @@
+import { applyEvent, initialSummary, type LifecycleEvent, type RunSummary } from "@yaag/runtime";
+import { type AskLedger, applyAskEnd, applyAskStart, emptyLedger } from "./ask-ledger.ts";
+import { sanitizeTerminalText } from "./terminal-text.ts";
+
+const MAX_TAIL_CHARS = 2_048;
+const TAIL_LINES = 2;
+
+interface OutputTail {
+  readonly index: number;
+  readonly text: string;
+}
+
+/** A details-channel occurrence: the canonical Summary plus its producing event. */
+export interface TreeUpdate {
+  readonly summary: RunSummary;
+  /** fd 3 stream occurrence identity — never an event value or timestamp. */
+  readonly sequence?: number;
+  readonly event?: LifecycleEvent;
+  readonly id?: string;
+  readonly result?: string;
+}
+
+/**
+ * The Run tree's folded state: the canonical Summary plus the bounded,
+ * renderer-only projection the tree draws (per-Agent Ask ledger and output
+ * tails). It reads no clock; every render takes `now` as an option.
+ */
+export class TreeState {
+  #summary: RunSummary;
+  readonly #order: string[];
+  readonly #ledgers = new Map<string, AskLedger>();
+  readonly #tails = new Map<string, OutputTail>();
+  #highestSequence: number | undefined;
+  #id: string | undefined;
+  #result: string | undefined;
+
+  constructor(summary: RunSummary = initialSummary()) {
+    this.#summary = summary;
+    this.#order = Object.keys(summary.agents);
+  }
+
+  /** Reconstructs a settled tree state without retaining event history. */
+  static fromSummary(summary: RunSummary): TreeState {
+    return new TreeState(summary);
+  }
+
+  /** Canonical Summary after every ingested Lifecycle Event. */
+  get summary(): RunSummary {
+    return this.#summary;
+  }
+
+  /** Agent names in their first-observed insertion order. */
+  get agentOrder(): readonly string[] {
+    return this.#order;
+  }
+
+  /** The Run's identity, when an ingested occurrence carried one. */
+  get runId(): string | undefined {
+    return this.#id;
+  }
+
+  /** The settled Run's Result text, when an ingested occurrence carried one. */
+  get result(): string | undefined {
+    return this.#result;
+  }
+
+  /** Folds one stamped Lifecycle Event, for the CLI path that owns the stream. */
+  apply(event: LifecycleEvent): void {
+    this.#rememberAgent(event);
+    this.#summary = applyEvent(this.#summary, event);
+    this.#project(event);
+  }
+
+  /**
+   * Ingests one details occurrence: replaces the canonical Summary and folds
+   * the renderer-only projection exactly once, keyed by the fd 3 occurrence
+   * `sequence`.
+   *
+   * An occurrence whose sequence is not greater than the highest already
+   * processed sequence changes nothing at all — not the Summary, not the id,
+   * not the Result — so a repeat or a stale replay cannot duplicate Ask facts
+   * (spec §5). An occurrence that carries no `sequence` is not stream-keyed,
+   * so it is always processed.
+   */
+  ingest(update: TreeUpdate): void {
+    const sequence = update.sequence;
+    if (
+      sequence !== undefined &&
+      this.#highestSequence !== undefined &&
+      sequence <= this.#highestSequence
+    )
+      return;
+    if (sequence !== undefined) this.#highestSequence = sequence;
+    this.#replaceSummary(update.summary);
+    if (update.id !== undefined) this.#id = update.id;
+    if (update.result !== undefined) this.#result = update.result;
+    const event = update.event;
+    if (event === undefined) return;
+    this.#rememberAgent(event);
+    this.#project(event);
+  }
+
+  /** One Agent's bounded Ask ledger; empty for an unknown Agent. */
+  ledger(agent: string): AskLedger {
+    return this.#ledgers.get(agent) ?? emptyLedger();
+  }
+
+  /**
+   * Number of Ask settlements observed for an Agent.
+   *
+   * The count merges two sources and keeps the larger one. The renderer
+   * ledger counts the settled rows it holds plus its pruned settlements. The
+   * Agent Summary (`askIndex` and state) gives a lower bound, because a
+   * partially reconstructed ledger can hold fewer rows than the Run already
+   * settled. A larger ledger count wins, so live observation is never clamped
+   * down to the Summary.
+   */
+  settledAsks(agent: string): number {
+    const ledger = this.ledger(agent);
+    const settled = ledger.rows.filter((row) => row.endedAt !== null).length + this.#pruned(agent);
+    return Math.max(settled, settledFromSummary(this.#summary.agents[agent]));
+  }
+
+  /** The bounded, sanitized two-line output tail for an Agent's live Ask. */
+  outputTail(agent: string): readonly string[] {
+    const tail = this.#tails.get(agent);
+    const current = this.#summary.agents[agent];
+    if (
+      tail === undefined ||
+      current?.state !== "asking" ||
+      current.askIndex !== tail.index ||
+      current.replayed
+    )
+      return [];
+    return tail.text.split("\n").slice(-TAIL_LINES);
+  }
+
+  /** Whether an Agent's currently active Ask is Cassette-backed. */
+  replayed(agent: string): boolean {
+    const current = this.#summary.agents[agent];
+    return current?.state === "asking" && current.replayed;
+  }
+
+  #pruned(agent: string): number {
+    return this.ledger(agent).settledPruned;
+  }
+
+  #replaceSummary(summary: RunSummary): void {
+    this.#summary = summary;
+    for (const name of Object.keys(summary.agents)) {
+      if (!this.#order.includes(name)) this.#order.push(name);
+    }
+  }
+
+  #project(event: LifecycleEvent): void {
+    switch (event.type) {
+      case "ask_start":
+        this.#ledgers.set(event.agent, applyAskStart(this.ledger(event.agent), event));
+        this.#tails.set(event.agent, { index: event.index, text: "" });
+        break;
+      case "ask_output":
+        this.#appendOutput(event);
+        break;
+      case "ask_end":
+        this.#ledgers.set(event.agent, applyAskEnd(this.ledger(event.agent), event));
+        break;
+    }
+  }
+
+  #rememberAgent(event: LifecycleEvent): void {
+    if ("agent" in event && !this.#order.includes(event.agent)) this.#order.push(event.agent);
+  }
+
+  #appendOutput(event: Extract<LifecycleEvent, { readonly type: "ask_output" }>): void {
+    const current = this.#summary.agents[event.agent];
+    const tail = this.#tails.get(event.agent);
+    if (
+      current?.state !== "asking" ||
+      current.askIndex !== event.index ||
+      current.replayed ||
+      (tail !== undefined && tail.index !== event.index)
+    )
+      return;
+    this.#tails.set(event.agent, {
+      index: event.index,
+      text: boundTail(`${tail?.text ?? ""}${sanitizeTerminalText(event.text)}`),
+    });
+  }
+}
+
+function settledFromSummary(agent: RunSummary["agents"][string] | undefined): number {
+  if (agent === undefined || agent.askIndex === null) return 0;
+  return agent.state === "asking" ? agent.askIndex : agent.askIndex + 1;
+}
+
+function boundTail(text: string): string {
+  const bounded = text.slice(-MAX_TAIL_CHARS);
+  return bounded.split("\n").slice(-TAIL_LINES).join("\n");
+}

package/src/widget-render.ts

@@ -0,0 +1,88 @@
+/**
+ * The combined inline widget for every live background Run (spec §1).
+ *
+ * One frame holds every Run: a header line each, expanded to the compact
+ * per-Agent lines while a Run has an Agent waiting on an Ask. Expansion is a
+ * pure policy over the state, because a pi `string[]` widget receives no input
+ * and there is no gesture to expand an entry with.
+ */
+import { compactAgentLines, compactHeaderLine } from "./compact-render.ts";
+import { clamp } from "./tree-rows.ts";
+import type { TreeState } from "./tree-state.ts";
+
+/** Default line budget; pi truncates a widget past 10 lines. */
+const DEFAULT_MAX_LINES = 10;
+
+/** One Run in the widget: its Run id and the renderer projection it drives. */
+export interface WidgetRun {
+  readonly id: string;
+  readonly state: TreeState;
+}
+
+/** Render-time inputs; `now` keeps the renderer clock-free. */
+export interface WidgetRenderOptions {
+  readonly now: number;
+  readonly width: number;
+  /** Hard line budget for the whole frame; defaults to 10. */
+  readonly maxLines?: number;
+}
+
+interface Entry {
+  readonly header: string;
+  readonly agents: readonly string[];
+}
+
+/**
+ * Renders every Run into one frame that never exceeds `maxLines`.
+ *
+ * Degrades deterministically: expanded entries collapse from the tail, then
+ * trailing headers roll up into one `and N more Runs` line. Pure over the
+ * given states, and every line is already width-clamped and sanitized.
+ */
+export function renderRunsWidget(
+  runs: readonly WidgetRun[],
+  options: WidgetRenderOptions,
+): readonly string[] {
+  const budget = Math.max(1, options.maxLines ?? DEFAULT_MAX_LINES);
+  if (runs.length === 0) return [];
+  const entries = runs.map((run) => entryOf(run, options));
+  let expanded = entries.map((entry) => entry.agents.length > 0);
+  for (let index = entries.length - 1; index >= 0 && lineCount(entries, expanded) > budget; --index)
+    expanded = expanded.map((value, at) => (at === index ? false : value));
+  if (lineCount(entries, expanded) <= budget) return frame(entries, expanded);
+  const kept = Math.max(0, budget - 1);
+  const rest = entries.length - kept;
+  return [
+    ...entries.slice(0, kept).map((entry) => entry.header),
+    clamp(` and ${rest} more Run${rest === 1 ? "" : "s"}`, options.width),
+  ];
+}
+
+function entryOf(run: WidgetRun, options: WidgetRenderOptions): Entry {
+  const compact = { now: options.now, width: options.width, label: run.id };
+  return {
+    header: compactHeaderLine(run.state, compact),
+    agents: expandable(run.state) ? compactAgentLines(run.state, compact) : [],
+  };
+}
+
+/** A Run is expanded while at least one of its Agents waits on an Ask. */
+function expandable(state: TreeState): boolean {
+  return Object.values(state.summary.agents).some((agent) => agent.state === "asking");
+}
+
+function lineCount(entries: readonly Entry[], expanded: readonly boolean[]): number {
+  return entries.reduce(
+    (total, entry, index) => total + 1 + (expanded[index] === true ? entry.agents.length : 0),
+    0,
+  );
+}
+
+function frame(entries: readonly Entry[], expanded: readonly boolean[]): readonly string[] {
+  const lines: string[] = [];
+  entries.forEach((entry, index) => {
+    lines.push(entry.header);
+    if (expanded[index] === true) lines.push(...entry.agents);
+  });
+  return lines;
+}