@yaag/tui 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaag/tui",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,6 +19,6 @@
   },
   "dependencies": {
     "@earendil-works/pi-tui": "^0.84.0",
-    "@yaag/runtime": "0.9.0"
+    "@yaag/runtime": "0.10.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-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

@@ -9,6 +9,7 @@ import {
 } from "../text/index.ts";
 import { type AgentTimers, agentTimers } from "./agent-timers.ts";
 import { type AskRow, askDwellMs } from "./ask-ledger.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 +23,46 @@ 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, lineage.roots, known, lineage, options.now);
+}
+
+function subtrees(
+  state: TreeState,
+  names: readonly string[],
+  known: ReadonlyMap<string, AgentInfo>,
+  lineage: Lineage,
+  now: number,
+): readonly TreeNode[] {
+  const nodes: TreeNode[] = [];
+  for (const name of names) {
+    const agent = known.get(name);
     if (agent === undefined) continue;
-    nodes.push(agentNode(state, name, agent, options.now));
+    const children = subtrees(state, lineage.children(name), known, lineage, now);
+    nodes.push(agentNode(state, name, agent, now, children));
   }
   return nodes;
 }
 
-function agentNode(state: TreeState, name: string, agent: AgentInfo, now: number): TreeNode {
+function agentNode(
+  state: TreeState,
+  name: string,
+  agent: AgentInfo,
+  now: number,
+  childAgents: readonly TreeNode[],
+): TreeNode {
   const ledger = state.ledger(name);
   const nested = graftNestedNodes(name, agent.nodes, now);
   const gist = agent.activity === null ? null : activityText(agent.activity);
@@ -48,6 +74,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 {

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 };
 }