@yaag/tui 0.9.0 → 0.11.0

package/package.json

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

package/src/tree/index.ts

@@ -3,6 +3,7 @@
  * Files inside this directory import each other directly.
  */
 export { AGENT_ASK_LEDGER_MAX, type AskLedger, type AskRow } from "./ask-ledger.ts";
+export { type FlatAgent, flattenAgents } from "./tree-agents.ts";
 export { moveSelection, nodeAt, nodeChain, parentOf, resolveSelection } from "./tree-cursor.ts";
 export {
   emptyFold,

package/src/tree/tree-agent-facts.ts

@@ -0,0 +1,66 @@
+import type { AgentInfo } from "@yaag/runtime";
+import {
+  costText,
+  durationText,
+  modelText,
+  sanitizeTerminalLine,
+  tokensText,
+} from "../text/index.ts";
+import type { AgentTimers } from "./agent-timers.ts";
+
+/** Everything one Agent row's facts are built from; `now` is already resolved. */
+export interface AgentFactsOptions {
+  readonly agent: AgentInfo;
+  readonly settled: number;
+  readonly timers: AgentTimers;
+  /** The Agent's Parent Link resolved to a row in this tree (`lineageOf`). */
+  readonly parentShown: boolean;
+}
+
+/**
+ * The Agent row's facts. The headline fact keeps the Agent's state and both
+ * timers in one string, because the compact and inline frames render only the
+ * first fact. Fork and compaction facts stay short so the row still fits a
+ * narrow pane.
+ */
+export function agentFacts(options: AgentFactsOptions): readonly string[] {
+  const { agent, settled, timers } = options;
+  const clocks = `active ${durationText(timers.activeMs)} · idle ${durationText(timers.idleMs)}`;
+  const facts: string[] = [];
+  if (agent.state === "asking") facts.push(`ask #${agent.askIndex + 1} · ${clocks}`);
+  else if (agent.state === "exited")
+    facts.push(`exited · ${settled} ask${settled === 1 ? "" : "s"} · ${clocks}`);
+  else facts.push(clocks);
+  facts.push(
+    `${costText(agent.cost, agent.incomplete)} · ${tokensText(agent.tokens?.total ?? null)}`,
+  );
+  if (agent.model !== null) facts.push(modelText(agent.model));
+  const last = agent.modelFallbacks.at(-1);
+  if (last !== undefined) {
+    facts.push(sanitizeTerminalLine(`fallback · ${last.failedModel} → ${last.resolvedModel}`));
+  }
+  const fork = forkFact(agent, options.parentShown);
+  if (fork !== null) facts.push(fork);
+  const compaction = compactionFact(agent);
+  if (compaction !== null) facts.push(compaction);
+  return facts;
+}
+
+/** Names the fork source only when its row is absent, so it is not repeated. */
+function forkFact(agent: AgentInfo, parentShown: boolean): string | null {
+  if (agent.origin !== "fork") return null;
+  if (parentShown || agent.parent === null) return "fork";
+  return sanitizeTerminalLine(`fork of ${agent.parent}`);
+}
+
+/**
+ * Compaction spend is never summed here: `agent_exit` already includes it
+ * (ADR-0043), so the row states the count and the context sizes only.
+ */
+function compactionFact(agent: AgentInfo): string | null {
+  if (agent.compactions <= 0) return null;
+  const count = `compacted ×${agent.compactions}`;
+  const last = agent.lastCompaction;
+  if (last === null || last.tokensBefore === null || last.tokensAfter === null) return count;
+  return `${count} · ${tokensText(last.tokensBefore)} → ${tokensText(last.tokensAfter)}`;
+}

package/src/tree/tree-agents.ts

@@ -0,0 +1,21 @@
+import type { TreeNode } from "./tree-node.ts";
+
+/** One Agent node of a tree and how deep its Parent Link chain runs. */
+export interface FlatAgent {
+  readonly agent: TreeNode;
+  readonly depth: number;
+}
+
+/**
+ * Every Agent node of a tree, depth-first, so a frame that draws one line per
+ * Agent cannot drop an Agent that a Parent Link nested (ADR-0042).
+ */
+export function flattenAgents(nodes: readonly TreeNode[], depth = 0): readonly FlatAgent[] {
+  const flat: FlatAgent[] = [];
+  for (const node of nodes) {
+    if (node.kind !== "agent") continue;
+    flat.push({ agent: node, depth });
+    flat.push(...flattenAgents(node.children, depth + 1));
+  }
+  return flat;
+}

package/src/tree/tree-fold.ts

@@ -18,11 +18,15 @@ export function emptyFold(): FoldState {
  * (spec §1). An Agent with no running Nested Node below it stays collapsed,
  * even when it is settled or asking. A user override for the node's path wins
  * over the default.
+ *
+ * A child Agent is not covered by this: a collapsed node still draws its
+ * agent-kind children, because a Parent Link places an Agent in the tree and
+ * must never hide it (ADR-0042). See `visibleRows`.
  */
 export function isExpanded(node: TreeNode, fold: FoldState): boolean {
   const override = fold.overrides.get(node.path);
   if (override !== undefined) return override;
-  if (node.children.length === 0) return false;
+  if (!node.children.some(isFoldable)) return false;
   return leadsToRunningNested(node);
 }
 
@@ -39,8 +43,9 @@ export interface VisibleRow {
 /**
  * Flattens the tree into the rows the renderer draws, in depth-first order.
  *
- * A collapsed node contributes its own row only. The row order and the
- * `lastAtDepth` flags are a pure function of the tree and the fold state.
+ * A collapsed node contributes its own row and its child Agents, which a fold
+ * never hides. The row order and the `lastAtDepth` flags are a pure function of
+ * the tree and the fold state.
  */
 export function visibleRows(tree: readonly TreeNode[], fold: FoldState): readonly VisibleRow[] {
   const rows: VisibleRow[] = [];
@@ -63,15 +68,32 @@ function collect(
       node,
       depth,
       expanded,
-      hasChildren: node.children.length > 0,
+      // A child Agent is always drawn, so it is no reason to offer a fold glyph.
+      hasChildren: node.children.some(isFoldable),
       lastAtDepth,
     });
-    if (expanded) collect(node.children, fold, depth + 1, lastAtDepth, rows);
+    const drawn = expanded ? node.children : node.children.filter(isAgent);
+    collect(drawn, fold, depth + 1, lastAtDepth, rows);
   }
 }
 
+function isAgent(node: TreeNode): boolean {
+  return node.kind === "agent";
+}
+
+function isFoldable(node: TreeNode): boolean {
+  return !isAgent(node);
+}
+
+/**
+ * Whether live nested work sits below this node, inside its own Agent.
+ *
+ * A child Agent is skipped: its rows are drawn whatever this node's fold says,
+ * so its running Nested Nodes are no reason to unfold this Agent's Ask rows.
+ */
 function leadsToRunningNested(node: TreeNode): boolean {
   for (const child of node.children) {
+    if (child.kind === "agent") continue;
     if (child.kind === "nested" && child.state === "running") return true;
     if (leadsToRunningNested(child)) return true;
   }

package/src/tree/tree-lineage.ts

@@ -0,0 +1,40 @@
+/**
+ * Groups Agents by their Parent Link, so the tree can draw a child under its
+ * parent.
+ *
+ * The input is observer data, which may be older, truncated, or hand-edited, so
+ * the grouping is defensive: a parent that names an unknown Agent makes its
+ * child a root, and so does a parent observed no earlier than its child. That
+ * one rule breaks every cycle, because a real Parent Link always names an Agent
+ * that spawned first. Order inside every level stays first-observed order.
+ */
+
+/** One Run's Agent lineage, resolved to roots and child lists. */
+export interface Lineage {
+  readonly roots: readonly string[];
+  children(name: string): readonly string[];
+}
+
+export function lineageOf(
+  order: readonly string[],
+  parentOf: (name: string) => string | null,
+): Lineage {
+  const position = new Map(order.map((name, index) => [name, index] as const));
+  const roots: string[] = [];
+  const children = new Map<string, string[]>();
+  for (const [index, name] of order.entries()) {
+    const parent = parentOf(name);
+    const parentIndex = parent === null ? undefined : position.get(parent);
+    if (parent === null || parentIndex === undefined || parentIndex >= index) {
+      roots.push(name);
+      continue;
+    }
+    const siblings = children.get(parent);
+    if (siblings === undefined) children.set(parent, [name]);
+    else siblings.push(name);
+  }
+  return {
+    roots,
+    children: (name: string): readonly string[] => children.get(name) ?? [],
+  };
+}

package/src/tree/tree-model.ts

@@ -1,14 +1,9 @@
 import type { AgentInfo } from "@yaag/runtime";
-import {
-  activityText,
-  costText,
-  durationText,
-  modelText,
-  sanitizeTerminalLine,
-  tokensText,
-} from "../text/index.ts";
-import { type AgentTimers, agentTimers } from "./agent-timers.ts";
+import { activityText, durationText, modelText, sanitizeTerminalLine } from "../text/index.ts";
+import { agentTimers } from "./agent-timers.ts";
 import { type AskRow, askDwellMs } from "./ask-ledger.ts";
+import { agentFacts } from "./tree-agent-facts.ts";
+import { type Lineage, lineageOf } from "./tree-lineage.ts";
 import { graftNestedNodes } from "./tree-nested.ts";
 import type { TreeNode } from "./tree-node.ts";
 import type { TreeState } from "./tree-state.ts";
@@ -22,21 +17,59 @@ export interface TreeModelOptions {
  * Builds the Run's node tree from the folded state.
  *
  * Pure: the same state and options always build the same tree. Agents come in
- * first-observed order, each Agent's children are its Ask rows, and each Ask's
+ * first-observed order, an Agent with a Parent Link sits under its parent, each
+ * Agent's children are its Ask rows then its child Agents, and each Ask's
  * children are the Nested Nodes grafted under it by path. Pruned rows become
  * one trailing "and N more finished" roll-up node.
  */
 export function buildTree(state: TreeState, options: TreeModelOptions): readonly TreeNode[] {
-  const nodes: TreeNode[] = [];
+  // Resolved once, so every later step reads an Agent that is known to exist.
+  const known = new Map<string, AgentInfo>();
   for (const name of state.agentOrder) {
     const agent = state.summary.agents[name];
+    if (agent !== undefined) known.set(name, agent);
+  }
+  const lineage = lineageOf([...known.keys()], (name) => state.parentLinkOf(name));
+  return subtrees({ state, known, lineage, now: options.now }, lineage.roots, false);
+}
+
+/** What every level of the recursion shares; only the names and depth change. */
+interface BuildContext {
+  readonly state: TreeState;
+  readonly known: ReadonlyMap<string, AgentInfo>;
+  readonly lineage: Lineage;
+  readonly now: number;
+}
+
+function subtrees(
+  context: BuildContext,
+  names: readonly string[],
+  parentShown: boolean,
+): readonly TreeNode[] {
+  const nodes: TreeNode[] = [];
+  for (const name of names) {
+    const agent = context.known.get(name);
     if (agent === undefined) continue;
-    nodes.push(agentNode(state, name, agent, options.now));
+    const children = subtrees(context, context.lineage.children(name), true);
+    nodes.push(agentNode(context, { name, agent, parentShown }, children));
   }
   return nodes;
 }
 
-function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number): TreeNode {
+/** The Agent this node is for, plus whether `lineageOf` gave its parent a row. */
+interface AgentSlot {
+  readonly name: string;
+  readonly agent: AgentInfo;
+  readonly parentShown: boolean;
+}
+
+function agentNode(
+  context: BuildContext,
+  slot: AgentSlot,
+  childAgents: readonly TreeNode[],
+): TreeNode {
+  const { state, now } = context;
+  const { name, agent } = slot;
   const ledger = state.ledger(name);
   const nested = graftNestedNodes(name, agent.nodes, now);
   const gist = agent.activity === null ? null : activityText(agent.activity);
@@ -48,6 +81,7 @@ function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number
       agentModel: agent.model,
     }),
   );
+  children.push(...childAgents);
   const finished = agent.finishedNodesPruned + ledger.settledPruned;
   if (finished > 0) children.push(rollup(`${name}#pruned`, `and ${finished} more finished`));
   return {
@@ -55,11 +89,12 @@ function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number
     kind: "agent",
     label: sanitizeTerminalLine(name),
     state: agentState(agent),
-    facts: agentFacts(
+    facts: agentFacts({
       agent,
-      state.settledAsks(name),
-      agentTimers({ agent, ledger, spawnedAt: state.spawnedAt(name), now }),
-    ),
+      settled: state.settledAsks(name),
+      timers: agentTimers({ agent, ledger, spawnedAt: state.spawnedAt(name), now }),
+      parentShown: slot.parentShown,
+    }),
     children,
     activityGist: gist,
     startedAt: agent.stateChangedAt,
@@ -111,26 +146,3 @@ function agentState(agent: AgentInfo): TreeNode["state"] {
   if (agent.state === "exited") return "exited";
   return agent.state === "asking" ? "running" : "idle";
 }
-
-/**
- * The Agent row's facts. The headline fact keeps the Agent's state and both
- * timers in one string, because the compact and inline frames render only the
- * first fact.
- */
-function agentFacts(agent: AgentInfo, settled: number, timers: AgentTimers): readonly string[] {
-  const clocks = `active ${durationText(timers.activeMs)} · idle ${durationText(timers.idleMs)}`;
-  const facts: string[] = [];
-  if (agent.state === "asking") facts.push(`ask #${agent.askIndex + 1} · ${clocks}`);
-  else if (agent.state === "exited")
-    facts.push(`exited · ${settled} ask${settled === 1 ? "" : "s"} · ${clocks}`);
-  else facts.push(clocks);
-  facts.push(
-    `${costText(agent.cost, agent.incomplete)} · ${tokensText(agent.tokens?.total ?? null)}`,
-  );
-  if (agent.model !== null) facts.push(modelText(agent.model));
-  const last = agent.modelFallbacks.at(-1);
-  if (last !== undefined) {
-    facts.push(sanitizeTerminalLine(`fallback · ${last.failedModel} → ${last.resolvedModel}`));
-  }
-  return facts;
-}

package/src/tree/tree-state.ts

@@ -141,6 +141,11 @@ export class TreeState {
     return this.#spawnedAt.get(agent) ?? this.#summary.startedAt ?? null;
   }
 
+  /** The Agent named as this one's parent (Parent Link), or null for a root Agent. */
+  parentLinkOf(agent: string): string | null {
+    return this.#summary.agents[agent]?.parent ?? null;
+  }
+
   /** The bounded, sanitized two-line output tail for an Agent's live Ask. */
   outputTail(agent: string): readonly string[] {
     const tail = this.#tails.get(agent);

package/src/view/compact-render.ts

@@ -1,6 +1,6 @@
 import { clampToWidth, costText, durationText, sanitizeTerminalLine } from "../text/index.ts";
 import type { TreeNode, TreeState } from "../tree/index.ts";
-import { buildTree, GLYPHS, stateGlyph } from "../tree/index.ts";
+import { buildTree, flattenAgents, GLYPHS, stateGlyph } from "../tree/index.ts";
 
 /** Everything the compact background view needs; `now` keeps it clock-free. */
 export interface CompactRenderOptions {
@@ -38,19 +38,22 @@ export function compactHeaderLine(state: TreeState, options: CompactRenderOption
   );
 }
 
-/** One line per Agent, with a one-line nested-work gist for each live Agent. */
+/**
+ * One line per Agent, with a one-line nested-work gist for each live Agent. A
+ * child Agent keeps its own line, indented one level per Parent Link.
+ */
 export function compactAgentLines(
   state: TreeState,
   options: CompactRenderOptions,
 ): readonly string[] {
-  return buildTree(state, { now: options.now }).map((agent) =>
-    compactAgentLine(agent, options.width),
+  return flattenAgents(buildTree(state, { now: options.now })).map((entry) =>
+    compactAgentLine(entry.agent, options.width, entry.depth),
   );
 }
 
 /** The one Agent line of the compact view, drawn for one Agent node. */
-export function compactAgentLine(agent: TreeNode, width: number): string {
-  return clampToWidth(agentLine(agent), width);
+export function compactAgentLine(agent: TreeNode, width: number, depth = 0): string {
+  return clampToWidth(`${"  ".repeat(depth)}${agentLine(agent)}`, width);
 }
 
 function agentLine(agent: TreeNode): string {

package/src/view/inline-render.ts

@@ -12,7 +12,7 @@
 
 import { clampToWidth } from "../text/index.ts";
 import type { TreeNode, TreeState } from "../tree/index.ts";
-import { buildTree } from "../tree/index.ts";
+import { buildTree, type FlatAgent, flattenAgents } from "../tree/index.ts";
 import { compactAgentLine, compactHeaderLine } from "./compact-render.ts";
 
 /** Default line budget; pi truncates a widget past 10 lines. */
@@ -43,15 +43,19 @@ export function renderInlineRun(state: TreeState, options: InlineRenderOptions):
     ...(options.label === undefined ? {} : { label: options.label }),
   };
   const header = compactHeaderLine(state, compact);
-  const agents = buildTree(state, { now: options.now });
+  // Flattened first, so a busy child Agent competes for the budget like any other.
+  const agents = flattenAgents(buildTree(state, { now: options.now }));
   if (budget === 1) return [header];
   if (agents.length + 1 <= budget)
-    return [header, ...agents.map((agent) => compactAgentLine(agent, options.width))];
+    return [
+      header,
+      ...agents.map((entry) => compactAgentLine(entry.agent, options.width, entry.depth)),
+    ];
   const kept = keepWatched(agents, budget - 2);
   const hidden = agents.length - kept.length;
   return [
     header,
-    ...kept.map((agent) => compactAgentLine(agent, options.width)),
+    ...kept.map((entry) => compactAgentLine(entry.agent, options.width, entry.depth)),
     clampToWidth(` … +${hidden} more`, options.width),
   ];
 }
@@ -64,19 +68,19 @@ export function renderInlineRun(state: TreeState, options: InlineRenderOptions):
  * 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[] {
+function keepWatched(agents: readonly FlatAgent[], count: number): readonly FlatAgent[] {
   if (count <= 0) return [];
   const ranked = agents
-    .map((agent, index) => ({ agent, index }))
+    .map((entry, index) => ({ entry, index }))
     .sort(
       (left, right) =>
-        rank(right.agent) - rank(left.agent) ||
-        changedAt(right.agent) - changedAt(left.agent) ||
+        rank(right.entry.agent) - rank(left.entry.agent) ||
+        changedAt(right.entry.agent) - changedAt(left.entry.agent) ||
         left.index - right.index,
     )
     .slice(0, count)
     .sort((left, right) => left.index - right.index);
-  return ranked.map((entry) => entry.agent);
+  return ranked.map((keeper) => keeper.entry);
 }
 
 function rank(agent: TreeNode): number {

package/src/view/snapshot-render.ts

@@ -2,7 +2,7 @@ import type { RunSummary } from "@yaag/runtime";
 import { renderNodeTable } from "../node/index.ts";
 import { clampToWidth, sanitizeTerminalLine } from "../text/index.ts";
 import type { TreeState } from "../tree/index.ts";
-import { buildTree } from "../tree/index.ts";
+import { buildTree, flattenAgents } from "../tree/index.ts";
 import { compactAgentLine, compactHeaderLine } from "./compact-render.ts";
 
 /** Everything the model-facing snapshot needs; `now` keeps it clock-free. */
@@ -33,13 +33,21 @@ export function renderSnapshot(
   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) => {
-    lines.push(compactAgentLine(agent, options.width));
-    const info = state.summary.agents[names[index] ?? ""];
-    if (info !== undefined) lines.push(...renderNodeTable(info, options.width));
-  });
+  // Each Agent line is paired with the Summary by node path, so nesting cannot
+  // shift a Nested Node table under the wrong Agent.
+  for (const { agent, depth } of flattenAgents(buildTree(state, { now: options.now }))) {
+    lines.push(compactAgentLine(agent, options.width, depth));
+    const info = state.summary.agents[agent.path];
+    // The table is indented with its Agent, so it stays visibly that Agent's.
+    // It is drawn into the width the indent leaves, so no line outgrows `width`.
+    if (info !== undefined) {
+      lines.push(
+        ...indent(renderNodeTable(info, tableWidth(options.width, depth)), depth).map((line) =>
+          clampToWidth(line, options.width),
+        ),
+      );
+    }
+  }
   if (options.result === undefined) return lines;
   return [
     ...lines,
@@ -60,6 +68,22 @@ function checkpointLostLine(summary: RunSummary, width: number): string | undefi
   return clampToWidth(sanitizeTerminalLine(`! checkpoint lost: ${summary.checkpointLost}`), width);
 }
 
+/** Columns one indent step takes from a nested Agent's rows. */
+const INDENT = 2;
+
+/** The narrowest table a deep nesting may shrink to, so a row keeps its shape. */
+const MIN_TABLE_WIDTH = 8;
+
+function tableWidth(width: number, depth: number): number {
+  return Math.max(MIN_TABLE_WIDTH, width - INDENT * depth);
+}
+
+function indent(lines: readonly string[], depth: number): readonly string[] {
+  if (depth === 0) return lines;
+  const prefix = " ".repeat(INDENT * depth);
+  return lines.map((line) => (line === "" ? line : `${prefix}${line}`));
+}
+
 function labelOf(options: SnapshotRenderOptions): { readonly label?: string } {
   return options.label === undefined ? {} : { label: options.label };
 }