@yaag/tui 0.1.4 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/tui",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +19,6 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.1.4"
+    "@yaag/runtime": "0.2.1"
   }
 }

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   emptyDrill,
 } from "./drill-state.ts";
 export { durationText } from "./duration-text.ts";
+export { type InlineRenderOptions, renderInlineRun } from "./inline-render.ts";
 export { type KeyBinding, type NamedKeybindings, routeKey } from "./key-router.ts";
 export {
   moveMenuCursor,
@@ -51,8 +52,6 @@ export {
   type RunTreeView,
   type RunTreeViewHost,
   type RunTreeViewOptions,
-  type RunViewExit,
-  type RunViewSurface,
 } from "./run-tree-view.ts";
 export { type RunViewResult, resultText, STDERR_TAIL_LINES } from "./run-view-result.ts";
 export {
@@ -119,8 +118,3 @@ export { TreeNavigator, type TreeNavigatorOptions } from "./tree-navigator.ts";
 export type { TreeNode, TreeNodeKind, TreeNodeState } from "./tree-node.ts";
 export { renderTree, type TreeRenderOptions } from "./tree-render.ts";
 export { TreeState, type TreeUpdate } from "./tree-state.ts";
-export {
-  renderRunsWidget,
-  type WidgetRenderOptions,
-  type WidgetRun,
-} from "./widget-render.ts";

package/src/inline-render.ts

@@ -0,0 +1,88 @@
+/**
+ * The inline frame a blocking `yaag_run` draws while it waits (architecture §9).
+ *
+ * A pi `string[]` widget receives no input, so this frame is read-only by
+ * construction: it is the compact Run projection — one header line, then one
+ * line per Agent — capped to a line budget the Host Session can afford.
+ *
+ * Over the cap the frame keeps the Agents a reader is watching while the tool
+ * call blocks — the running ones first, then the latest to change state — and
+ * rolls the rest into one `… +N more` line.
+ */
+import { compactAgentLine, compactHeaderLine } from "./compact-render.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";
+
+/** Default line budget; pi truncates a widget past 10 lines. */
+const DEFAULT_MAX_LINES = 10;
+
+/** Render-time inputs; `now` keeps the renderer clock-free. */
+export interface InlineRenderOptions {
+  readonly now: number;
+  readonly width: number;
+  /** Header text before the Program name; defaults to `yaag`. */
+  readonly label?: string;
+  /** Hard line budget for the whole frame; defaults to 10. */
+  readonly maxLines?: number;
+}
+
+/**
+ * Renders one Run into a frame that never exceeds `maxLines`.
+ *
+ * Pure over the given state, and every line is already width-clamped and
+ * sanitized. A budget of one draws the header alone; a budget under one is
+ * raised to one, so the frame always names the Run.
+ */
+export function renderInlineRun(state: TreeState, options: InlineRenderOptions): readonly string[] {
+  const budget = Math.max(1, options.maxLines ?? DEFAULT_MAX_LINES);
+  const compact = {
+    now: options.now,
+    width: options.width,
+    ...(options.label === undefined ? {} : { label: options.label }),
+  };
+  const header = compactHeaderLine(state, compact);
+  const agents = buildTree(state, { now: options.now });
+  if (budget === 1) return [header];
+  if (agents.length + 1 <= budget)
+    return [header, ...agents.map((agent) => compactAgentLine(agent, options.width))];
+  const kept = keepWatched(agents, budget - 2);
+  const hidden = agents.length - kept.length;
+  return [
+    header,
+    ...kept.map((agent) => compactAgentLine(agent, options.width)),
+    clamp(` … +${hidden} more`, options.width),
+  ];
+}
+
+/**
+ * Picks the `count` Agents worth watching, drawn in tree order.
+ *
+ * A running Agent always outranks one that is idle, exited, or failed. Within
+ * one rank the later state change wins, and an Agent that never changed state
+ * sorts last. Ties keep the first-observed order, so the choice is
+ * deterministic for a given state.
+ */
+function keepWatched(agents: readonly TreeNode[], count: number): readonly TreeNode[] {
+  if (count <= 0) return [];
+  const ranked = agents
+    .map((agent, index) => ({ agent, index }))
+    .sort(
+      (left, right) =>
+        rank(right.agent) - rank(left.agent) ||
+        changedAt(right.agent) - changedAt(left.agent) ||
+        left.index - right.index,
+    )
+    .slice(0, count)
+    .sort((left, right) => left.index - right.index);
+  return ranked.map((entry) => entry.agent);
+}
+
+function rank(agent: TreeNode): number {
+  return agent.state === "running" ? 1 : 0;
+}
+
+function changedAt(agent: TreeNode): number {
+  return agent.startedAt ?? Number.NEGATIVE_INFINITY;
+}

package/src/run-tree-view.ts

@@ -1,23 +1,19 @@
 /**
- * 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.
+ * The Run view (ADR-0008): the interactive tree `/yaag` opens over any Run of
+ * this session, 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
+ * first while it is open, then the drill overlay or menu, then `ctrl+q`, 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.
+ * - `esc` never stops the Run, and always leaves one layer. The session table
+ *   is literal `ctrl+q`/`ctrl+c` only (`session-keys.ts`), so `esc` reaches no
+ *   stop path. An open overlay, menu, or stop prompt consumes `esc` first —
+ *   one layer per press — and at tree level `esc` closes the view, live or
+ *   settled. A live Run keeps executing after that.
+ * - `ctrl+c` is a best-effort alias. Pi binds `app.clear` to `ctrl+c` at app
+ *   level, so a Host Session may consume the byte before this component sees
+ *   it; `ctrl+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`.
@@ -39,32 +35,21 @@ 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";
+// At tree level `esc` closes the view, live or settled, so the view replaces
+// the renderer's own footer on every phase; `tree-render.ts` writes `esc back`,
+// which is true only for the read-only frames that consume no key (ADR-0008).
+const VIEW_FOOTER = " ↑↓ move  ←→ fold  ↵ actions  t transcript  esc close";
 
-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. */
+/** Every capability the Run 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;
+  /** Resolves the `ctx.ui.custom()` promise; the view then closes. */
+  done(): void;
 }
 
 /**
- * What the foreground view needs to exist.
+ * What the view needs to exist.
  *
  * The caller owns the `TreeState`; the view only reads it, so a redraw never
  * changes the projection.
@@ -75,8 +60,6 @@ export interface RunTreeViewOptions {
   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;
 }
 
@@ -91,8 +74,8 @@ export interface RunTreeView {
   /** 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
+   * SIGINT takes the same path as `ctrl+q`: the first one opens the stop
+   * prompt, a second confirms Stop Run (ADR-0008). While the
    * stop already runs, and on a settled view, it does nothing — a settled view
    * closes on a keystroke only.
    */
@@ -100,24 +83,23 @@ export interface RunTreeView {
 }
 
 /**
- * Builds the foreground Run view over a `TreeState` the caller owns.
+ * Builds the 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.
+ * `host.done` is called exactly once, when the reader closes the view; 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).
+ * only write capability is the Run's own `stop` (ADR-0008).
  */
 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).
+  // The drill layers own `esc` while one of them is open; the tree level below
+  // them turns the same press into a close (ADR-0008).
   const drill = new DrillController({ ...host, navigator, dropFocus: () => {} });
   let phase: RunPhase = livePhase();
   let result: RunViewResult | undefined;
@@ -128,20 +110,16 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
       case "stop":
         host.stop();
         return;
-      case "detach":
-        finish("detached");
-        return;
       case "close":
-        finish("dismissed");
+        finish();
         return;
     }
   };
 
-  const finish = (exit: RunViewExit): void => {
+  const finish = (): void => {
     if (exited) return;
     exited = true;
-    if (exit === "detached") host.detach();
-    host.done(exit);
+    host.done();
   };
 
   const apply = (action: Parameters<typeof applyRunViewAction>[1]): void => {
@@ -187,7 +165,7 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
           ...(result === undefined ? {} : { result: resultText(result) }),
         }),
       ];
-      if (phase.kind === "settled") lines[lines.length - 1] = clamp(settledFooter(surface), width);
+      lines[lines.length - 1] = clamp(VIEW_FOOTER, width);
       const overlay = drill.overlayLines(width);
       const framed =
         overlay === undefined
@@ -207,12 +185,10 @@ export function createRunTreeView(options: RunTreeViewOptions): RunTreeView {
         apply({ kind: "quit" });
         return;
       }
-      if (
-        surface === "background" &&
-        phase.kind === "settled" &&
-        routeDrillKey(data, host.keybindings) === "back"
-      ) {
-        finish("dismissed");
+      // At tree level nothing is left to back out of, so `esc` closes the view;
+      // a live Run keeps executing without it (ADR-0008).
+      if (routeDrillKey(data, host.keybindings) === "back") {
+        finish();
         return;
       }
       drill.handleInput(data);

package/src/run-view-state.ts

@@ -1,10 +1,11 @@
 /**
- * The foreground Run view's lifecycle reducer (spec §4): live → stop prompt →
+ * The Run view's lifecycle reducer (ADR-0008): 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.
+ * Pure and I/O-free. `cancel` — the `esc` gesture inside the prompt — can only
+ * close the prompt: no action reachable from it produces `stop`, so `esc` can
+ * never stop a Run. Closing the view is the view's own tree-level `esc`, which
+ * never reaches this reducer.
  */
 import { moveStopCursor, type StopChoice } from "./stop-prompt.ts";
 
@@ -27,7 +28,7 @@ export type RunViewAction =
   | { readonly kind: "settle"; readonly outcome: RunViewOutcome };
 
 /** What the host must do after a transition. */
-export type RunViewEffect = "stop" | "detach" | "close";
+export type RunViewEffect = "stop" | "close";
 
 /** One transition: the next phase, plus the effect the host must perform. */
 export interface RunViewTransition {
@@ -81,8 +82,6 @@ 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

@@ -1,27 +1,32 @@
 /**
- * The session layer's key table (spec §2): the one gesture that can end a
- * foreground Run view.
+ * The session layer's key table (ADR-0008): the one gesture that can stop a Run
+ * from the 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.
+ *
+ * `ctrl+q` is the documented gesture. `ctrl+c` stays as a best-effort alias:
+ * pi binds `app.clear` to `ctrl+c` at app level, so a Host Session may consume
+ * the byte before this component sees it. Plain `q` is bound to nothing, so a
+ * reader who types `q` in the tree changes nothing (ADR-0008).
  */
 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. */
+/** Ctrl-Q and its best-effort Ctrl-C alias, and nothing else. */
 export const SESSION_KEY_TABLE: readonly KeyBinding<SessionAction>[] = [
-  { action: "quit", keys: ["q", "ctrl+c"] },
+  { action: "quit", keys: ["ctrl+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).
+ * routed here can stop a Run by accident (ADR-0008).
  */
 export function routeSessionKey(
   data: string,

package/src/snapshot-render.ts

@@ -1,3 +1,4 @@
+import type { RunSummary } from "@yaag/runtime";
 import { compactAgentLine, compactHeaderLine } from "./compact-render.ts";
 import { renderNodeTable } from "./node-table.ts";
 import { sanitizeTerminalLine } from "./terminal-text.ts";
@@ -16,9 +17,10 @@ export interface SnapshotRenderOptions {
 }
 
 /**
- * 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.
+ * Renders the model-facing snapshot frame: one Run header line, one warning
+ * line when the Run lost its Checkpoint, 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
@@ -30,6 +32,8 @@ export function renderSnapshot(
 ): readonly string[] {
   const header = { now: options.now, width: options.width, ...labelOf(options) };
   const lines: string[] = [compactHeaderLine(state, header)];
+  const warning = checkpointLostLine(state.summary, options.width);
+  if (warning !== undefined) lines.push(warning);
   const agents = buildTree(state, { now: options.now });
   const names = state.agentOrder.filter((name) => state.summary.agents[name] !== undefined);
   agents.forEach((agent, index) => {
@@ -46,6 +50,15 @@ export function renderSnapshot(
   ];
 }
 
+/**
+ * One warning line for a Run that asked for a Checkpoint and lost it. The Run's
+ * own error is reported elsewhere; this line reports only the missing artifact.
+ */
+function checkpointLostLine(summary: RunSummary, width: number): string | undefined {
+  if (summary.runState !== "ended" || summary.checkpointLost === undefined) return undefined;
+  return clamp(sanitizeTerminalLine(`! checkpoint lost: ${summary.checkpointLost}`), width);
+}
+
 function labelOf(options: SnapshotRenderOptions): { readonly label?: string } {
   return options.label === undefined ? {} : { label: options.label };
 }

package/src/stop-prompt.ts

@@ -1,15 +1,15 @@
 /**
- * The foreground Run view's stop prompt (spec §4): the three-way choice `q` and
- * Ctrl-C raise over a live Run.
+ * The Run view's stop prompt (ADR-0008): the two-way choice `ctrl+q` raises 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.
+ * Stopping a Run is the only write capability the view has, so it asks first.
+ * Leaving a Run running needs no prompt choice: `esc` closes the view and the
+ * Run keeps executing.
  */
 import { renderFramedBox } from "./overlay-frame.ts";
 
 /** What the reader may do with a live Run. */
-export type StopChoice = "stop" | "detach" | "resume";
+export type StopChoice = "stop" | "resume";
 
 /** One prompt row: the choice and the label the reader sees. */
 export interface StopChoiceRow {
@@ -17,11 +17,10 @@ export interface StopChoiceRow {
   readonly label: string;
 }
 
-/** The three choices, in prompt order. */
+/** The two 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" },
+  { action: "resume", label: "Cancel" },
 ];
 
 const FOOTER = " ↑↓ choose  ↵ confirm  esc back";

package/src/widget-render.ts

@@ -1,88 +0,0 @@
-/**
- * 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;
-}