@yaag/tui 0.1.0

package/src/run-tree-view.ts

@@ -0,0 +1,236 @@
+/**
+ * The Run view (spec §4): the interactive tree a blocking `yaag_run` opens in
+ * the Host Session, and the same component `/yaag` opens over a background
+ * Run, plus the Run's lifecycle over it.
+ *
+ * It layers the session gestures over the read-only drill-in: the stop prompt
+ * first while it is open, then the drill overlay or menu, then `q`/Ctrl-C, then
+ * the tree. Two rules are load-bearing:
+ *
+ * - `esc` never stops the Run. It reaches the session layer through no path:
+ *   the session table is literal `q`/`ctrl+c` only (`session-keys.ts`), and the
+ *   drill layers own `esc` before it. In the foreground surface `esc` never
+ *   closes the view either; in the background surface `esc` at tree level
+ *   closes a *settled* view, because there is nothing left to watch and no tool
+ *   call to return. In a live background view `esc` still only backs out of
+ *   overlays and focus, and `q` opens the same three-way prompt, where
+ *   `Detach (keep running)` means "close the view, the Run keeps running".
+ * - `ctrl+c` is best-effort. Pi binds `app.clear` to `ctrl+c` at app level, so a
+ *   Host Session may consume the byte before this component sees it; `q` is the
+ *   gesture to document to users.
+ *
+ * The view owns no clock and no I/O of its own: every capability, including the
+ * reap-ladder stop, arrives through `RunTreeViewHost`.
+ */
+import { DrillController, type DrillHost } from "./drill-controller.ts";
+import { routeDrillKey, routeMenuKey } from "./drill-keys.ts";
+import { type RunViewResult, resultText } from "./run-view-result.ts";
+import {
+  applyRunViewAction,
+  livePhase,
+  type RunPhase,
+  type RunViewEffect,
+} from "./run-view-state.ts";
+import { routeSessionKey } from "./session-keys.ts";
+import { renderStopPrompt, STOP_PROMPT_CHOICES } from "./stop-prompt.ts";
+import { buildTree } from "./tree-model.ts";
+import { TreeNavigator } from "./tree-navigator.ts";
+import { renderTree } from "./tree-render.ts";
+import { clamp } from "./tree-rows.ts";
+import type { TreeState } from "./tree-state.ts";
+
+/** Which surface opened the view; it decides only the settled-`esc` rule. */
+export type RunViewSurface = "foreground" | "background";
+
+const SETTLED_FOOTER_KEYS = " ↑↓ move  ←→ fold  ↵ actions  t transcript  ";
+
+// At tree level a settled background view closes on `esc`, so `esc back` would
+// contradict `esc close`: the surface picks exactly one of them (spec §4).
+function settledFooter(surface: RunViewSurface): string {
+  return `${SETTLED_FOOTER_KEYS}${surface === "background" ? "esc close  q done" : "esc back  q done"}`;
+}
+
+/** How the reader left the view. */
+export type RunViewExit = "dismissed" | "detached";
+
+/** Every capability the foreground view needs from its host. */
+export interface RunTreeViewHost extends Omit<DrillHost, "navigator" | "dropFocus"> {
+  /** Runs the reap ladder for this Run (ADR-0008). `esc` never reaches it. */
+  stop(): void;
+  /** Converts the Run to a background Run; the view then closes. */
+  detach(): void;
+  /** Resolves the `ctx.ui.custom()` promise with how the view ended. */
+  done(exit: RunViewExit): void;
+}
+
+/**
+ * What the foreground view needs to exist.
+ *
+ * The caller owns the `TreeState`; the view only reads it, so a redraw never
+ * changes the projection.
+ */
+export interface RunTreeViewOptions {
+  /** Ingested from Run start by the caller, so no early Ask is missed. */
+  readonly state: TreeState;
+  readonly host: RunTreeViewHost;
+  /** The Run id, e.g. `r1`; heads the tree. */
+  readonly label?: string;
+  /** Which surface opened the view; defaults to `"foreground"`. */
+  readonly surface?: RunViewSurface;
+  now?(): number;
+}
+
+/** The component `ctx.ui.custom()` renders, plus the handles the tool drives. */
+export interface RunTreeView {
+  render(width: number): string[];
+  handleInput(data: string): void;
+  invalidate(): void;
+  dispose(): void;
+  /** The Run settled: freeze the tree and show the Result region. */
+  settle(result: RunViewResult): void;
+  /** A pushed fd 3 update landed in the TreeState; redraw. */
+  touch(): void;
+  /**
+   * SIGINT (or the Run's AbortSignal) takes the same path as `q`: the first
+   * one opens the stop prompt, a second confirms Stop Run (spec §4). While the
+   * stop already runs, and on a settled view, it does nothing — a settled view
+   * closes on a keystroke only.
+   */
+  interrupt(): void;
+}
+
+/**
+ * Builds the foreground Run view over a `TreeState` the caller owns.
+ *
+ * `host.done` is called exactly once, on the reader's dismissal or detach; a
+ * host that closes the view for its own reason (an abort) calls `done` itself.
+ * Nothing here can prompt an Agent — the drill layer stays read-only, and the
+ * only write capability is the Run's own `stop` (spec §4).
+ */
+export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
+  const host = options.host;
+  const state = options.state;
+  const now = options.now ?? Date.now;
+  const surface: RunViewSurface = options.surface ?? "foreground";
+  const navigator = new TreeNavigator({
+    snapshot: () => buildTree(state, { now: now() }),
+    keybindings: host.keybindings,
+  });
+  // `esc` at tree level backs out of nothing in the foreground: it must not
+  // stop the Run and must not close the view (spec §4).
+  const drill = new DrillController({ ...host, navigator, dropFocus: () => {} });
+  let phase: RunPhase = livePhase();
+  let result: RunViewResult | undefined;
+  let exited = false;
+
+  const perform = (effect: RunViewEffect): void => {
+    switch (effect) {
+      case "stop":
+        host.stop();
+        return;
+      case "detach":
+        finish("detached");
+        return;
+      case "close":
+        finish("dismissed");
+        return;
+    }
+  };
+
+  const finish = (exit: RunViewExit): void => {
+    if (exited) return;
+    exited = true;
+    if (exit === "detached") host.detach();
+    host.done(exit);
+  };
+
+  const apply = (action: Parameters<typeof applyRunViewAction>[1]): void => {
+    const transition = applyRunViewAction(phase, action);
+    const changed = transition.phase !== phase;
+    phase = transition.phase;
+    if (transition.effect !== undefined) perform(transition.effect);
+    if (changed || transition.effect !== undefined) host.requestRender();
+  };
+
+  const promptInput = (data: string): boolean => {
+    if (phase.kind !== "confirm") return false;
+    const action = routeMenuKey(data, host.keybindings);
+    switch (action) {
+      case "menuUp":
+        apply({ kind: "move", delta: -1 });
+        return true;
+      case "menuDown":
+        apply({ kind: "move", delta: 1 });
+        return true;
+      case "cancel":
+        apply({ kind: "cancel" });
+        return true;
+      case "confirm": {
+        const choice = STOP_PROMPT_CHOICES[phase.cursor];
+        if (choice !== undefined) apply({ kind: "choose", choice: choice.action });
+        return true;
+      }
+      default:
+        return true;
+    }
+  };
+
+  return {
+    render(width: number): string[] {
+      const lines = [
+        ...renderTree(state, {
+          now: now(),
+          width,
+          ...(options.label === undefined ? {} : { label: options.label }),
+          ...(navigator.selectedPath === undefined ? {} : { selectedPath: navigator.selectedPath }),
+          fold: navigator.fold,
+          ...(result === undefined ? {} : { result: resultText(result) }),
+        }),
+      ];
+      if (phase.kind === "settled") lines[lines.length - 1] = clamp(settledFooter(surface), width);
+      const overlay = drill.overlayLines(width);
+      const framed =
+        overlay === undefined
+          ? lines
+          : [...lines.slice(0, Math.max(0, lines.length - overlay.length)), ...overlay];
+      return phase.kind === "confirm"
+        ? [...framed, ...renderStopPrompt({ cursor: phase.cursor, width })]
+        : framed;
+    },
+    handleInput(data: string): void {
+      if (promptInput(data)) return;
+      if (drill.layer.kind !== "tree") {
+        drill.handleInput(data);
+        return;
+      }
+      if (routeSessionKey(data, host.keybindings) === "quit") {
+        apply({ kind: "quit" });
+        return;
+      }
+      if (
+        surface === "background" &&
+        phase.kind === "settled" &&
+        routeDrillKey(data, host.keybindings) === "back"
+      ) {
+        finish("dismissed");
+        return;
+      }
+      drill.handleInput(data);
+    },
+    invalidate(): void {},
+    dispose(): void {},
+    settle(settled: RunViewResult): void {
+      result = settled;
+      // `apply` requests the redraw for the phase change; one settlement is one
+      // render request.
+      apply({ kind: "settle", outcome: settled.kind });
+    },
+    touch(): void {
+      host.requestRender();
+    },
+    interrupt(): void {
+      if (phase.kind === "live") apply({ kind: "quit" });
+      else if (phase.kind === "confirm") apply({ kind: "choose", choice: "stop" });
+    },
+  };
+}

package/src/run-view-result.ts

@@ -0,0 +1,43 @@
+/**
+ * The Result region's text policy for a settled Run (spec §1 "End state"): the
+ * Run's value, or the error plus a bounded stderr tail.
+ *
+ * Pure, and the only place that policy lives, so the component and the CLI show
+ * the same end state.
+ */
+import { sanitizeTerminalText } from "./terminal-text.ts";
+
+/** How many trailing stderr lines a failed Run shows below its error. */
+export const STDERR_TAIL_LINES = 12;
+
+/** Shown for a Run that fulfilled with no printed value. */
+const NO_VALUE = "(no value)";
+
+/** How a Run ended, with everything the Result region needs to draw it. */
+export type RunViewResult =
+  | { readonly kind: "fulfilled"; readonly result: string }
+  | { readonly kind: "failed"; readonly error: string; readonly stderrTail?: string };
+
+/**
+ * Builds the `result` string for `renderTree`.
+ *
+ * Every part is sanitized, so a hostile Run value or stderr tail can neither
+ * emit an escape byte nor forge a region; the stderr tail is cut to its last
+ * `STDERR_TAIL_LINES` lines. Never throws.
+ */
+export function resultText(result: RunViewResult): string {
+  if (result.kind === "fulfilled") {
+    const value = sanitizeTerminalText(result.result).trimEnd();
+    return value === "" ? NO_VALUE : value;
+  }
+  const error = sanitizeTerminalText(result.error).trimEnd();
+  const tail = boundedTail(result.stderrTail);
+  return tail === "" ? error : `${error}\n${tail}`;
+}
+
+function boundedTail(stderrTail: string | undefined): string {
+  if (stderrTail === undefined) return "";
+  const text = sanitizeTerminalText(stderrTail).trimEnd();
+  if (text.trim() === "") return "";
+  return text.split("\n").slice(-STDERR_TAIL_LINES).join("\n");
+}

package/src/run-view-state.ts

@@ -0,0 +1,89 @@
+/**
+ * The foreground Run view's lifecycle reducer (spec §4): live → stop prompt →
+ * stopping → settled.
+ *
+ * Pure and I/O-free. `cancel` — the `esc` gesture — can only close the prompt:
+ * no action reachable from it produces `stop` or `close`, so `esc` can never
+ * stop a Run and can never dismiss the view.
+ */
+import { moveStopCursor, type StopChoice } from "./stop-prompt.ts";
+
+/** How the Run ended, as the view shows it. */
+export type RunViewOutcome = "fulfilled" | "failed";
+
+/** Which lifecycle phase the view is in. */
+export type RunPhase =
+  | { readonly kind: "live" }
+  | { readonly kind: "confirm"; readonly cursor: number }
+  | { readonly kind: "stopping" }
+  | { readonly kind: "settled"; readonly outcome: RunViewOutcome };
+
+/** One gesture or event the session layer applies to the phase. */
+export type RunViewAction =
+  | { readonly kind: "quit" }
+  | { readonly kind: "cancel" }
+  | { readonly kind: "move"; readonly delta: number }
+  | { readonly kind: "choose"; readonly choice: StopChoice }
+  | { readonly kind: "settle"; readonly outcome: RunViewOutcome };
+
+/** What the host must do after a transition. */
+export type RunViewEffect = "stop" | "detach" | "close";
+
+/** One transition: the next phase, plus the effect the host must perform. */
+export interface RunViewTransition {
+  readonly phase: RunPhase;
+  readonly effect?: RunViewEffect;
+}
+
+/** The live view, with no prompt open. */
+export function livePhase(): RunPhase {
+  return { kind: "live" };
+}
+
+/**
+ * Applies one action to the view phase.
+ *
+ * A `settle` always wins, from any phase, so an open prompt cannot ask to stop a
+ * Run that already ended. An action that belongs to another phase returns the
+ * phase unchanged and no effect.
+ */
+export function applyRunViewAction(phase: RunPhase, action: RunViewAction): RunViewTransition {
+  if (action.kind === "settle") return { phase: { kind: "settled", outcome: action.outcome } };
+  switch (phase.kind) {
+    case "live":
+      return action.kind === "quit" ? { phase: { kind: "confirm", cursor: 0 } } : { phase };
+    case "confirm":
+      return fromConfirm(phase, action);
+    case "stopping":
+      return { phase };
+    case "settled":
+      return action.kind === "quit" ? { phase, effect: "close" } : { phase };
+  }
+}
+
+function fromConfirm(
+  phase: { readonly kind: "confirm"; readonly cursor: number },
+  action: RunViewAction,
+): RunViewTransition {
+  switch (action.kind) {
+    case "move":
+      return { phase: { kind: "confirm", cursor: moveStopCursor(phase.cursor, action.delta) } };
+    case "cancel":
+      return { phase: livePhase() };
+    case "choose":
+      return fromChoice(action.choice);
+    default:
+      return { phase };
+  }
+}
+
+function fromChoice(choice: StopChoice): RunViewTransition {
+  switch (choice) {
+    case "stop":
+      return { phase: { kind: "stopping" }, effect: "stop" };
+    case "detach":
+      return { phase: livePhase(), effect: "detach" };
+    case "resume":
+      return { phase: livePhase() };
+  }
+}

package/src/session-keys.ts

@@ -0,0 +1,31 @@
+/**
+ * The session layer's key table (spec §2): the one gesture that can end a
+ * foreground Run view.
+ *
+ * Literal keys only, with no `named` binding. `esc` must never stop a Run, and
+ * pi binds `tui.select.cancel` to `escape, ctrl+c`; a named entry here would
+ * let that binding — or any user remap of it — reach the quit path. The literal
+ * table makes that structurally impossible.
+ */
+import { type KeyBinding, type NamedKeybindings, routeKey } from "./key-router.ts";
+
+/** The one gesture the session layer consumes. */
+export type SessionAction = "quit";
+
+/** `q` and Ctrl-C, and nothing else. */
+export const SESSION_KEY_TABLE: readonly KeyBinding<SessionAction>[] = [
+  { action: "quit", keys: ["q", "ctrl+c"] },
+];
+
+/**
+ * Resolves one input byte string to the session `quit` gesture.
+ *
+ * Returns undefined for every other byte, `escape` included, so no gesture
+ * routed here can stop a Run by accident (spec §4).
+ */
+export function routeSessionKey(
+  data: string,
+  keybindings: NamedKeybindings,
+): SessionAction | undefined {
+  return routeKey(data, keybindings, SESSION_KEY_TABLE);
+}

package/src/session-transcript.ts

@@ -0,0 +1,164 @@
+/**
+ * A defensive reader for one Agent's pi session file (JSONL on disk).
+ *
+ * A Peek renders this to show an Agent's transcript; it is never a wire
+ * protocol, so an unknown entry type or a malformed line is skipped rather than
+ * thrown — the same ethos as `event-reader.ts`. The reader owns only decoding;
+ * truncation and layout belong to the renderer.
+ */
+
+/** One rendered turn of an Agent's conversation, normalised across pi versions. */
+export type TranscriptItem =
+  | { readonly kind: "user"; readonly text: string }
+  | { readonly kind: "assistant"; readonly text: string }
+  | { readonly kind: "thinking"; readonly text: string }
+  | { readonly kind: "tool-call"; readonly name: string; readonly args: string }
+  | {
+      readonly kind: "tool-result";
+      readonly name: string;
+      readonly text: string;
+      readonly isError: boolean;
+    };
+
+/**
+ * Decodes a pi session file body into ordered transcript items.
+ *
+ * Never throws: a non-JSON line, an entry that is not a `message`, or a part
+ * with an unknown shape is dropped. An empty or wholly-unreadable body yields an
+ * empty array, which the renderer presents as a "no transcript available" stub.
+ */
+export function parseTranscript(content: string): readonly TranscriptItem[] {
+  const items: TranscriptItem[] = [];
+  for (const line of content.split("\n")) {
+    const message = messageOf(line);
+    if (message !== null) collectMessage(message, items);
+  }
+  return items;
+}
+
+/**
+ * Extracts an Agent's system prompt from its session file, when one is present.
+ *
+ * pi does not persist the system prompt in every session version, so this
+ * returns null whenever no recorded prompt is found rather than inventing one.
+ */
+export function extractSystemPrompt(content: string): string | null {
+  for (const line of content.split("\n")) {
+    const record = parseLine(line);
+    if (record === null) continue;
+    const direct = stringField(record, "systemPrompt");
+    if (direct !== null) return direct;
+    const message = recordField(record, "message");
+    if (message === null) continue;
+    const prompt = stringField(message, "systemPrompt");
+    if (prompt !== null) return prompt;
+    if (message.role === "system") {
+      const text = joinText(arrayField(message, "content"));
+      if (text !== "") return text;
+    }
+  }
+  return null;
+}
+
+function messageOf(line: string): Record<string, unknown> | null {
+  const record = parseLine(line);
+  if (record === null || record.type !== "message") return null;
+  return recordField(record, "message");
+}
+
+function collectMessage(message: Record<string, unknown>, items: TranscriptItem[]): void {
+  const parts = arrayField(message, "content");
+  switch (message.role) {
+    case "user":
+      pushText(items, "user", joinText(parts));
+      return;
+    case "assistant":
+      collectAssistant(parts, items);
+      return;
+    case "toolResult":
+      items.push({
+        kind: "tool-result",
+        name: stringField(message, "toolName") ?? "tool",
+        text: joinText(parts),
+        isError: message.isError === true,
+      });
+      return;
+    default:
+      return;
+  }
+}
+
+function collectAssistant(parts: readonly unknown[], items: TranscriptItem[]): void {
+  for (const part of parts) {
+    if (!isRecord(part)) continue;
+    if (part.type === "thinking") pushText(items, "thinking", asString(part.thinking));
+    else if (part.type === "text") pushText(items, "assistant", asString(part.text));
+    else if (part.type === "toolCall") {
+      items.push({
+        kind: "tool-call",
+        name: asString(part.name) || "tool",
+        args: stringifyArgs(part.arguments),
+      });
+    }
+  }
+}
+
+function pushText(
+  items: TranscriptItem[],
+  kind: "user" | "assistant" | "thinking",
+  text: string,
+): void {
+  if (text !== "") items.push({ kind, text });
+}
+
+function joinText(parts: readonly unknown[]): string {
+  return parts
+    .filter(isRecord)
+    .filter((part) => part.type === "text")
+    .map((part) => asString(part.text))
+    .join("")
+    .trim();
+}
+
+function stringifyArgs(args: unknown): string {
+  if (args === undefined) return "";
+  try {
+    return JSON.stringify(args);
+  } catch {
+    return String(args);
+  }
+}
+
+function parseLine(line: string): Record<string, unknown> | null {
+  if (line.trim() === "") return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  return isRecord(value) ? value : null;
+}
+
+function recordField(record: Record<string, unknown>, key: string): Record<string, unknown> | null {
+  const value = record[key];
+  return isRecord(value) ? value : null;
+}
+
+function arrayField(record: Record<string, unknown>, key: string): readonly unknown[] {
+  const value = record[key];
+  return Array.isArray(value) ? value : [];
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" && value !== "" ? value : null;
+}
+
+function asString(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/snapshot-render.ts

@@ -0,0 +1,51 @@
+import { compactAgentLine, compactHeaderLine } from "./compact-render.ts";
+import { renderNodeTable } from "./node-table.ts";
+import { sanitizeTerminalLine } from "./terminal-text.ts";
+import { buildTree } from "./tree-model.ts";
+import { clamp } from "./tree-rows.ts";
+import type { TreeState } from "./tree-state.ts";
+
+/** Everything the model-facing snapshot needs; `now` keeps it clock-free. */
+export interface SnapshotRenderOptions {
+  readonly now: number;
+  readonly width: number;
+  /** Header text before the Program name; usually the Run id. */
+  readonly label?: string;
+  /** The settled Run's result value, printed under a `Result:` line. */
+  readonly result?: string;
+}
+
+/**
+ * Renders the model-facing snapshot frame: one Run header line, then one line
+ * per Agent with that Agent's Nested Node table, then the Result block when
+ * the Run settled with a value.
+ *
+ * It draws no key footer and reads no input, so every line is content a model
+ * can parse. Pure over the state; every untrusted string is sanitized and
+ * clamped to `width`.
+ */
+export function renderSnapshot(
+  state: TreeState,
+  options: SnapshotRenderOptions,
+): readonly string[] {
+  const header = { now: options.now, width: options.width, ...labelOf(options) };
+  const lines: string[] = [compactHeaderLine(state, header)];
+  const agents = buildTree(state, { now: options.now });
+  const names = state.agentOrder.filter((name) => state.summary.agents[name] !== undefined);
+  agents.forEach((agent, index) => {
+    lines.push(compactAgentLine(agent, options.width));
+    const info = state.summary.agents[names[index] ?? ""];
+    if (info !== undefined) lines.push(...renderNodeTable(info, options.width));
+  });
+  if (options.result === undefined) return lines;
+  return [
+    ...lines,
+    "",
+    clamp("Result:", options.width),
+    ...options.result.split("\n").map((line) => clamp(sanitizeTerminalLine(line), options.width)),
+  ];
+}
+
+function labelOf(options: SnapshotRenderOptions): { readonly label?: string } {
+  return options.label === undefined ? {} : { label: options.label };
+}

package/src/stop-prompt.ts

@@ -0,0 +1,58 @@
+/**
+ * The foreground Run view's stop prompt (spec §4): the three-way choice `q` and
+ * Ctrl-C raise over a live Run.
+ *
+ * The spec's key table names no key for Detach, and the component consumes only
+ * the keys of that table, so Detach lives here as a prompt choice rather than as
+ * a new binding.
+ */
+import { renderFramedBox } from "./overlay-frame.ts";
+
+/** What the reader may do with a live Run. */
+export type StopChoice = "stop" | "detach" | "resume";
+
+/** One prompt row: the choice and the label the reader sees. */
+export interface StopChoiceRow {
+  readonly action: StopChoice;
+  readonly label: string;
+}
+
+/** The three choices, in prompt order. */
+export const STOP_PROMPT_CHOICES: readonly StopChoiceRow[] = [
+  { action: "stop", label: "Stop Run" },
+  { action: "detach", label: "Detach (keep running)" },
+  { action: "resume", label: "Keep watching" },
+];
+
+const FOOTER = " ↑↓ choose  ↵ confirm  esc back";
+
+/** One stop-prompt render request. */
+export interface StopPromptOptions {
+  readonly cursor: number;
+  readonly width: number;
+}
+
+/** Moves the prompt cursor by `delta`, wrapping at both ends of the list. */
+export function moveStopCursor(cursor: number, delta: number): number {
+  const count = STOP_PROMPT_CHOICES.length;
+  return (((cursor + delta) % count) + count) % count;
+}
+
+/**
+ * Draws the framed stop prompt.
+ *
+ * Every returned line is exactly `width` visible columns; a cursor outside the
+ * choice list highlights no row, and a width that is not finite degrades through
+ * `renderFramedBox` rather than throwing.
+ */
+export function renderStopPrompt(options: StopPromptOptions): readonly string[] {
+  const rows = STOP_PROMPT_CHOICES.map(
+    (row, index) => `${index === options.cursor ? "❯" : " "} ${row.label}`,
+  );
+  return renderFramedBox({
+    title: "Stop Run?",
+    lines: rows,
+    footer: FOOTER,
+    width: options.width,
+  });
+}