@yaag/tui 0.1.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@yaag/tui",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "!src/fixtures"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@earendil-works/pi-tui": "^0.84.0",
+    "@yaag/runtime": "0.0.0"
+  }
+}

package/src/accounting-text.ts

@@ -0,0 +1,19 @@
+/**
+ * Formats a cost the way the Run tree mockup writes it: `$0.43`, with
+ * `+incomplete` appended when the cost is a floor (ADR-0012). A null cost is
+ * reported as unknown rather than as zero.
+ */
+export function costText(value: number | null, incomplete = false): string {
+  if (value === null) return "cost unknown";
+  return `$${value.toFixed(2)}${incomplete ? " +incomplete" : ""}`;
+}
+
+/**
+ * Formats a token total the way the mockup writes it: `84K tok` above one
+ * thousand, the plain count below it. A null total is reported as unknown.
+ */
+export function tokensText(total: number | null): string {
+  if (total === null) return "tokens unknown";
+  if (total < 1_000) return `${total} tok`;
+  return `${Math.round(total / 1_000)}K tok`;
+}

package/src/activity-text.ts

@@ -0,0 +1,27 @@
+import type { AgentActivity } from "@yaag/runtime";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+
+/**
+ * Formats the current Agent Activity as the one-line gist the tree draws.
+ *
+ * Every activity state of the Run Summary has a form: `thinking`, `writing`,
+ * `<tool>: <args>`, `compacting`, and `retrying 2/3`. The result is sanitized
+ * to one line, so a hostile tool name or argument gist cannot forge a row.
+ */
+export function activityText(activity: AgentActivity): string {
+  switch (activity.type) {
+    case "thinking":
+      return "thinking";
+    case "writing":
+      return "writing";
+    case "compacting":
+      return "compacting";
+    case "retrying":
+      return `retrying ${activity.attempt}/${activity.max}`;
+    default: {
+      const args = sanitizeTerminalLine(activity.argsGist);
+      const name = sanitizeTerminalLine(activity.name);
+      return args === "" ? name : `${name}: ${args}`;
+    }
+  }
+}

package/src/ask-ledger.ts

@@ -0,0 +1,85 @@
+import type { LifecycleEvent } from "@yaag/runtime";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+
+/** Maximum Ask rows one Agent's renderer-only ledger retains (mirrors the node table cap). */
+export const AGENT_ASK_LEDGER_MAX = 64;
+
+type AskStartEvent = Extract<LifecycleEvent, { readonly type: "ask_start" }>;
+type AskEndEvent = Extract<LifecycleEvent, { readonly type: "ask_end" }>;
+
+/** One Ask as the tree draws it: identity, gist, timing, and settlement. */
+export interface AskRow {
+  readonly index: number;
+  readonly promptGist: string;
+  readonly startedAt: number | null;
+  readonly endedAt: number | null;
+  readonly ok: boolean | null;
+  readonly replayed: boolean;
+}
+
+/** One Agent's bounded Ask history, oldest settled Asks rolled into a counter. */
+export interface AskLedger {
+  readonly rows: readonly AskRow[];
+  readonly settledPruned: number;
+}
+
+/** The ledger of an Agent that has started no Ask. */
+export function emptyLedger(): AskLedger {
+  return { rows: [], settledPruned: 0 };
+}
+
+/**
+ * Records one Ask start. A repeated start for an index already present keeps
+ * the first-seen row, so a redraw cannot duplicate an Ask row.
+ */
+export function applyAskStart(ledger: AskLedger, event: AskStartEvent): AskLedger {
+  if (ledger.rows.some((row) => row.index === event.index)) return ledger;
+  const row: AskRow = {
+    index: event.index,
+    promptGist: sanitizeTerminalLine(event.promptGist),
+    startedAt: event.at,
+    endedAt: null,
+    ok: null,
+    replayed: event.replayed === true,
+  };
+  return prune({ rows: [...ledger.rows, row], settledPruned: ledger.settledPruned });
+}
+
+/**
+ * Records one Ask settlement. A settlement for an index the ledger never saw
+ * start still records a row, so a late observer keeps the Ask count honest.
+ */
+export function applyAskEnd(ledger: AskLedger, event: AskEndEvent): AskLedger {
+  const index = ledger.rows.findIndex((row) => row.index === event.index);
+  if (index === -1) {
+    const row: AskRow = {
+      index: event.index,
+      promptGist: "",
+      startedAt: null,
+      endedAt: event.at,
+      ok: event.ok,
+      replayed: false,
+    };
+    return prune({ rows: [...ledger.rows, row], settledPruned: ledger.settledPruned });
+  }
+  const rows = ledger.rows.map((row, position) =>
+    position === index ? { ...row, endedAt: event.at, ok: event.ok } : row,
+  );
+  return prune({ rows, settledPruned: ledger.settledPruned });
+}
+
+function prune(ledger: AskLedger): AskLedger {
+  if (ledger.rows.length <= AGENT_ASK_LEDGER_MAX) return ledger;
+  const excess = ledger.rows.length - AGENT_ASK_LEDGER_MAX;
+  const kept: AskRow[] = [];
+  let pruned = 0;
+  for (const row of ledger.rows) {
+    if (row.endedAt !== null && pruned < excess) {
+      pruned += 1;
+      continue;
+    }
+    kept.push(row);
+  }
+  if (pruned === 0) return ledger;
+  return { rows: kept, settledPruned: ledger.settledPruned + pruned };
+}

package/src/compact-render.ts

@@ -0,0 +1,75 @@
+import { costText } from "./accounting-text.ts";
+import { durationText } from "./duration-text.ts";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { GLYPHS, stateGlyph } from "./tree-glyphs.ts";
+import { buildTree } from "./tree-model.ts";
+import type { TreeNode } from "./tree-node.ts";
+import { clamp } from "./tree-rows.ts";
+import type { TreeState } from "./tree-state.ts";
+
+/** Everything the compact background view needs; `now` keeps it clock-free. */
+export interface CompactRenderOptions {
+  readonly now: number;
+  readonly width: number;
+  /** Header text before the Program name; defaults to `yaag`. */
+  readonly label?: string;
+}
+
+/**
+ * Renders the same state folded to Agent level: one Run header line, then one
+ * line per Agent with a one-line nested-work gist for each live Agent.
+ *
+ * Pure over the state, and it never draws an Ask row: the full view owns that
+ * depth. Every untrusted string passes `sanitizeTerminalLine` first.
+ */
+export function renderCompact(state: TreeState, options: CompactRenderOptions): readonly string[] {
+  return [compactHeaderLine(state, options), ...compactAgentLines(state, options)];
+}
+
+/** The one Run header line the compact view and the inline widget share. */
+export function compactHeaderLine(state: TreeState, options: CompactRenderOptions): 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"}`;
+  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,
+  );
+}
+
+/** One line per Agent, with a one-line nested-work gist for each live Agent. */
+export function compactAgentLines(
+  state: TreeState,
+  options: CompactRenderOptions,
+): readonly string[] {
+  return buildTree(state, { now: options.now }).map((agent) =>
+    compactAgentLine(agent, options.width),
+  );
+}
+
+/** The one Agent line of the compact view, drawn for one Agent node. */
+export function compactAgentLine(agent: TreeNode, width: number): string {
+  return clamp(agentLine(agent), width);
+}
+
+function agentLine(agent: TreeNode): string {
+  const head = ` ${stateGlyph(agent.state)} ${agent.label}   ${agent.facts[0] ?? ""}`;
+  const running = countRunningNested(agent.children);
+  if (agent.state !== "running" || running === 0) return head;
+  return `${head}   ${GLYPHS.collapsed} ${running} subagent${running === 1 ? "" : "s"} running`;
+}
+
+function countRunningNested(nodes: readonly TreeNode[]): number {
+  let count = 0;
+  for (const node of nodes) {
+    if (node.kind === "nested" && node.state === "running") count += 1;
+    count += countRunningNested(node.children);
+  }
+  return count;
+}

package/src/details-pane.ts

@@ -0,0 +1,33 @@
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { stateGlyph } from "./tree-glyphs.ts";
+import type { TreeNode } from "./tree-node.ts";
+import { clamp } from "./tree-rows.ts";
+
+/** The bounded last-output lines the pane draws under the selected node. */
+export interface DetailsPaneOptions {
+  readonly width: number;
+  readonly outputTail: readonly string[];
+}
+
+/**
+ * Draws the details region for the selected node: its path as the header, its
+ * activity gist and facts, and the bounded output tail of the Agent that owns
+ * it. Returns no lines when nothing is selected.
+ */
+export function renderDetailsPane(
+  node: TreeNode | undefined,
+  options: DetailsPaneOptions,
+): readonly string[] {
+  if (node === undefined) return [];
+  const lines = [
+    clamp(`${stateGlyph(node.state)} ${sanitizeTerminalLine(node.path)}`, options.width),
+  ];
+  if (node.activityGist !== null)
+    lines.push(clamp(`  ${sanitizeTerminalLine(node.activityGist)}`, options.width));
+  if (node.facts.length > 0)
+    lines.push(clamp(`  ${node.facts.map(sanitizeTerminalLine).join(" · ")}`, options.width));
+  const last = options.outputTail.at(-1);
+  if (last !== undefined && last !== "")
+    lines.push(clamp(`  last: “${sanitizeTerminalLine(last)}”`, options.width));
+  return lines;
+}

package/src/drill-controller.ts

@@ -0,0 +1,234 @@
+/**
+ * The drill-in controller: it layers the actions menu and the read-only
+ * transcript overlay over the Run tree (spec §1).
+ *
+ * Read-only by construction: `DrillHost` exposes copy, editor, notify, and
+ * session reads and nothing else, so no code path here can prompt an Agent or
+ * stop a Run (ADR — a Peek observes, it never sends). It holds no clock either;
+ * a host that tails a live session file calls `refreshTranscript` on its own
+ * cadence.
+ */
+import type { AgentInfo } from "@yaag/runtime";
+import { routeDrillKey, routeMenuKey, routeOverlayKey } from "./drill-keys.ts";
+import {
+  type AnyDrillAction,
+  applyDrillAction,
+  type DrillEffect,
+  type DrillState,
+  emptyDrill,
+} from "./drill-state.ts";
+import type { NamedKeybindings } from "./key-router.ts";
+import { renderActionsMenu } from "./node-actions.ts";
+import { agentOfPath } from "./node-path-parse.ts";
+import { extractSystemPrompt } from "./session-transcript.ts";
+import { nodeTranscriptLines } from "./transcript-content.ts";
+import { renderTranscriptOverlay } from "./transcript-overlay.ts";
+import { NO_TRANSCRIPT_STUB } from "./transcript-render.ts";
+import type { TreeNavigator } from "./tree-navigator.ts";
+
+/** Shown when a session file records no system prompt (spec §5). */
+const NO_SYSTEM_PROMPT = "(no system prompt recorded in this session file)";
+
+/** Every capability the drill-in needs from its host — all of them read-only. */
+export interface DrillHost {
+  /** The tree's keyboard router; the drill layers sit above it. */
+  readonly navigator: TreeNavigator;
+  /** The keybinding matcher the drill key tables route through. */
+  readonly keybindings: NamedKeybindings;
+  /** The owning Agent's observer projection, absent for an unknown Agent. */
+  agentInfo(agent: string): AgentInfo | undefined;
+  /** Reads an Agent's session file body, or null when it is missing. */
+  readSession(agent: string): Promise<string | null>;
+  /** An Agent's session file path, or null when the spawn reported none. */
+  sessionPath(agent: string): string | null;
+  copyPath(text: string): Promise<void>;
+  openEditor(title: string, body: string): Promise<void>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  requestRender(): void;
+  /** Content rows the overlay may draw. */
+  rows(): number;
+  /** Releases input focus when `esc` closes the last layer. */
+  dropFocus?(): void;
+}
+
+/**
+ * Routes input through the overlay, then the menu, then the tree, and performs
+ * each layer's read-only effects through the host.
+ *
+ * `handleInput` reports whether a layer consumed the byte; an unbound key is
+ * consumed by no layer. The tree's cursor and folds are never written, so
+ * closing every layer restores the tree exactly as the reader left it.
+ */
+export class DrillController {
+  readonly #host: DrillHost;
+  #state: DrillState = emptyDrill();
+  /** Content of the currently open node, keyed by its path, or undefined. */
+  #content: { readonly path: string; readonly lines: readonly string[] } | undefined;
+  /** Bumped by every open, refresh, and close, to void in-flight reads. */
+  #generation = 0;
+
+  constructor(host: DrillHost) {
+    this.#host = host;
+  }
+
+  /** Which layer holds input focus. */
+  get layer(): DrillState {
+    return this.#state;
+  }
+
+  /** The framed overlay lines, or undefined while the tree holds focus. */
+  overlayLines(width: number): readonly string[] | undefined {
+    const state = this.#state;
+    switch (state.kind) {
+      case "tree":
+        return undefined;
+      case "menu":
+        return renderActionsMenu({ nodePath: state.path, cursor: state.cursor, width });
+      case "transcript":
+        return renderTranscriptOverlay({
+          nodePath: state.path,
+          content: this.#linesFor(state.path),
+          scroll: state.scroll,
+          rows: this.#host.rows(),
+          width,
+        });
+    }
+  }
+
+  /** Routes one input byte string; returns whether a layer consumed it. */
+  handleInput(data: string): boolean {
+    const action = this.#route(data);
+    if (action === undefined) return this.#state.kind === "tree" && this.#tree(data);
+    const before = this.#state;
+    const { state, effect } = applyDrillAction(before, action, {
+      selectedPath: this.#host.navigator.selectedPath,
+      total: before.kind === "transcript" ? this.#linesFor(before.path).length : 0,
+      rows: this.#host.rows(),
+    });
+    this.#state = state;
+    if (state.kind !== "transcript" || state.path !== openPath(before)) this.#invalidate();
+    if (effect !== undefined) void this.#perform(effect);
+    if (state !== before || effect !== undefined) this.#host.requestRender();
+    return true;
+  }
+
+  /**
+   * Re-reads the open node's transcript, for a host that tails a live session
+   * file. Does nothing while no overlay is open, and never throws.
+   */
+  async refreshTranscript(): Promise<void> {
+    const state = this.#state;
+    if (state.kind !== "transcript") return;
+    await this.#loadTranscript(state.path, this.#nextGeneration());
+  }
+
+  #route(data: string): AnyDrillAction | undefined {
+    const keybindings = this.#host.keybindings;
+    switch (this.#state.kind) {
+      case "transcript":
+        return routeOverlayKey(data, keybindings);
+      case "menu":
+        return routeMenuKey(data, keybindings);
+      case "tree":
+        return routeDrillKey(data, keybindings);
+    }
+  }
+
+  #tree(data: string): boolean {
+    return this.#host.navigator.handleInput(data);
+  }
+
+  async #perform(effect: DrillEffect): Promise<void> {
+    switch (effect.kind) {
+      case "loadTranscript":
+        await this.#loadTranscript(effect.path, this.#nextGeneration());
+        return;
+      case "copySessionPath":
+        await this.#copySessionPath(effect.path);
+        return;
+      case "openSystemPrompt":
+        await this.#openSystemPrompt(effect.path);
+        return;
+      case "dropFocus":
+        this.#host.dropFocus?.();
+        return;
+    }
+  }
+
+  /**
+   * Reads one node's transcript and commits it only while that node is still
+   * the open overlay and no newer read has started, so a slow read for A can
+   * never land under B and a closed overlay drops its pending read.
+   */
+  async #loadTranscript(nodePath: string, generation: number): Promise<void> {
+    const agent = agentOfPath(nodePath);
+    const info = this.#host.agentInfo(agent);
+    const session = await this.#readSession(agent);
+    if (generation !== this.#generation) return;
+    const state = this.#state;
+    if (state.kind !== "transcript" || state.path !== nodePath) return;
+    this.#content = {
+      path: nodePath,
+      lines:
+        info === undefined
+          ? [NO_TRANSCRIPT_STUB]
+          : nodeTranscriptLines({ nodePath, agent: info, session }),
+    };
+    this.#host.requestRender();
+  }
+
+  /** Loaded lines for `nodePath`, or none while its own read is in flight. */
+  #linesFor(nodePath: string): readonly string[] {
+    const content = this.#content;
+    return content !== undefined && content.path === nodePath ? content.lines : [];
+  }
+
+  /** Drops retained content and voids every in-flight read. */
+  #invalidate(): void {
+    this.#content = undefined;
+    this.#generation += 1;
+  }
+
+  #nextGeneration(): number {
+    this.#generation += 1;
+    return this.#generation;
+  }
+
+  async #copySessionPath(nodePath: string): Promise<void> {
+    const path = this.#host.sessionPath(agentOfPath(nodePath));
+    if (path === null) {
+      this.#host.notify(`${nodePath} has no session file to copy.`, "warning");
+      return;
+    }
+    try {
+      await this.#host.copyPath(path);
+      this.#host.notify(`Copied session file path for ${nodePath}.`, "info");
+    } catch (error) {
+      this.#host.notify(`Could not copy path: ${message(error)}`, "error");
+    }
+  }
+
+  async #openSystemPrompt(nodePath: string): Promise<void> {
+    const session = await this.#readSession(agentOfPath(nodePath));
+    const prompt = session === null ? null : extractSystemPrompt(session);
+    await this.#host.openEditor(`System prompt — ${nodePath}`, prompt ?? NO_SYSTEM_PROMPT);
+  }
+
+  /** A session file that cannot be read degrades to the labelled stub. */
+  async #readSession(agent: string): Promise<string | null> {
+    try {
+      return await this.#host.readSession(agent);
+    } catch {
+      return null;
+    }
+  }
+}
+
+/** The node path of an open transcript overlay, or undefined for other layers. */
+function openPath(state: DrillState): string | undefined {
+  return state.kind === "transcript" ? state.path : undefined;
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/drill-keys.ts

@@ -0,0 +1,74 @@
+/**
+ * The three key tables of the drill-in (spec §2): the tree's drill gestures, the
+ * actions menu, and the transcript overlay.
+ *
+ * Every table routes through `routeKey`, so a user's named-binding override
+ * always beats a vim literal. `back`/`close` resolve `tui.select.cancel` before
+ * the bare `escape` literal, and both sit after the arrow entries, so an
+ * ESC-prefixed arrow sequence scrolls rather than closing the layer.
+ */
+import { type KeyBinding, type NamedKeybindings, routeKey } from "./key-router.ts";
+
+/** A drill gesture the tree layer consumes. */
+export type DrillAction = "openMenu" | "openTranscript" | "back";
+
+/** A gesture the actions menu consumes. */
+export type MenuAction = "menuUp" | "menuDown" | "confirm" | "cancel";
+
+/** A gesture the transcript overlay consumes. */
+export type OverlayAction =
+  | "scrollUp"
+  | "scrollDown"
+  | "pageUp"
+  | "pageDown"
+  | "copyPath"
+  | "close";
+
+/**
+ * The tree's drill keys. `openMenu` uses the literal `enter`, because the spec
+ * names no pi binding for it and the tree layer is consulted last.
+ */
+export const DRILL_KEY_TABLE: readonly KeyBinding<DrillAction>[] = [
+  { action: "openMenu", keys: ["enter", "return"] },
+  { action: "openTranscript", keys: ["t"] },
+  { action: "back", named: "tui.select.cancel", keys: ["escape"] },
+];
+
+/** The actions menu's keys. */
+export const MENU_KEY_TABLE: readonly KeyBinding<MenuAction>[] = [
+  { action: "menuUp", named: "tui.select.up", vim: ["k"] },
+  { action: "menuDown", named: "tui.select.down", vim: ["j"] },
+  { action: "confirm", named: "tui.select.confirm", keys: ["enter", "return"] },
+  { action: "cancel", named: "tui.select.cancel", keys: ["escape"] },
+];
+
+/** The transcript overlay's keys. */
+export const OVERLAY_KEY_TABLE: readonly KeyBinding<OverlayAction>[] = [
+  { action: "scrollUp", named: "tui.select.up", vim: ["k"] },
+  { action: "scrollDown", named: "tui.select.down", vim: ["j"] },
+  { action: "pageUp", named: "tui.select.pageUp" },
+  { action: "pageDown", named: "tui.select.pageDown" },
+  { action: "copyPath", keys: ["c"] },
+  { action: "close", named: "tui.select.cancel", keys: ["escape"] },
+];
+
+/** Resolves one input byte string to a tree drill action, or undefined. */
+export function routeDrillKey(
+  data: string,
+  keybindings: NamedKeybindings,
+): DrillAction | undefined {
+  return routeKey(data, keybindings, DRILL_KEY_TABLE);
+}
+
+/** Resolves one input byte string to an actions-menu action, or undefined. */
+export function routeMenuKey(data: string, keybindings: NamedKeybindings): MenuAction | undefined {
+  return routeKey(data, keybindings, MENU_KEY_TABLE);
+}
+
+/** Resolves one input byte string to a transcript-overlay action, or undefined. */
+export function routeOverlayKey(
+  data: string,
+  keybindings: NamedKeybindings,
+): OverlayAction | undefined {
+  return routeKey(data, keybindings, OVERLAY_KEY_TABLE);
+}