@yaag/runtime 0.1.0

package/src/jsonl.ts

@@ -0,0 +1,42 @@
+import type { Frame } from "./transport.ts";
+
+/**
+ * Decodes a byte stream into frames using pi's strict JSONL framing: split on
+ * `\n` only, strip a trailing `\r`. A generic line reader is not
+ * protocol-compliant, because U+2028/U+2029 are valid inside JSON strings
+ * (pi `docs/rpc.md`, framing note).
+ *
+ * Non-JSON lines and JSON that is not a frame object are skipped rather than
+ * thrown on: pi emits undocumented frame types and occasional noise (ticket 01).
+ */
+export async function* decodeFrames(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<Frame> {
+  const decoder = new TextDecoder();
+  let buffer = "";
+  for await (const chunk of chunks) {
+    buffer += decoder.decode(chunk, { stream: true });
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      const frame = parseFrame(buffer.slice(0, newline));
+      if (frame) yield frame;
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+    }
+  }
+  const last = parseFrame(buffer);
+  if (last) yield last;
+}
+
+/** Returns null for anything that is not a JSON object with a string `type`. */
+export function parseFrame(line: string): Frame | null {
+  const text = line.endsWith("\r") ? line.slice(0, -1) : line;
+  if (text.trim() === "") return null;
+  let value: unknown;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null) return null;
+  if (!("type" in value) || typeof value.type !== "string") return null;
+  return value as Frame; // narrowed above: an object with a string `type`
+}

package/src/live-transport.ts

@@ -0,0 +1,210 @@
+import { YaagError } from "./errors.ts";
+import { FrameQueue } from "./frame-queue.ts";
+import { decodeFrames } from "./jsonl.ts";
+import { piCommand, readModel, readSessionFile, readStats } from "./pi-state.ts";
+import { reap } from "./reap.ts";
+import {
+  createToolProbe,
+  requestedToolNames,
+  TOOL_PROBE_EXTENSION_PATH,
+  type ToolProbe,
+  verifyEffectiveTools,
+} from "./tool-probe.ts";
+import type {
+  AgentStats,
+  AgentTransport,
+  AskMarker,
+  Frame,
+  OpenOptions,
+  TransportFactory,
+  TransportStartupObserver,
+} from "./transport.ts";
+
+/** How long the startup `get_state` round-trip may take before spawn fails. */
+const READY_TIMEOUT_MS = 30_000;
+/** Cost is a local read answering in ~0ms, but the kill must never block on it. */
+const STATS_TIMEOUT_MS = 2_000;
+
+/** Agents are real `pi --mode rpc` child processes (ADR-0001). */
+export const liveTransport: TransportFactory = {
+  async open(
+    options: OpenOptions,
+    observeStartup?: TransportStartupObserver,
+  ): Promise<AgentTransport> {
+    const transport = new LiveTransport(options);
+    await transport.ready(observeStartup);
+    return transport;
+  },
+};
+
+class LiveTransport implements AgentTransport {
+  model = "";
+
+  readonly #name: string;
+  readonly #process: Bun.Subprocess<"pipe", "pipe", "ignore">;
+  readonly #queue = new FrameQueue();
+  readonly #pending = new Map<string, (frame: Frame) => void>();
+  readonly #toolProbe: ToolProbe | null;
+  readonly #promisedTools: readonly string[] | null;
+  #nextId = 0;
+  #closing: Promise<AgentStats> | null = null;
+
+  constructor(options: OpenOptions) {
+    this.#name = options.name;
+    this.#promisedTools = requestedToolNames(options.tools, options.disallowedTools);
+    this.#toolProbe = createToolProbe(options.tools, options.disallowedTools);
+    this.#process = Bun.spawn({
+      cmd: piCommand(options, this.#toolProbe ? TOOL_PROBE_EXTENSION_PATH : undefined),
+      cwd: options.cwd,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "ignore",
+      // Its own process group, so the Agent sees stdin EOF rather than a signal
+      // when the Orchestrator dies — EOF is the path that reaps grandchildren.
+      detached: true,
+    });
+    void this.#read();
+  }
+
+  /** Confirms the Agent is up and speaking the protocol, and resolves its model. */
+  async ready(observeStartup?: TransportStartupObserver): Promise<void> {
+    try {
+      const state = await this.#command({ type: "get_state" }, READY_TIMEOUT_MS);
+      const model = readModel(state);
+      if (!model) throw new Error(`agent "${this.#name}" reported no model`);
+      if (this.#toolProbe && this.#promisedTools) {
+        verifyEffectiveTools(this.#promisedTools, await this.#toolProbe.wait());
+      }
+      this.model = model;
+      const sessionFile = readSessionFile(state);
+      observeStartup?.(sessionFile === null ? {} : { sessionFile });
+    } catch (error) {
+      // Startup has not returned this transport to spawn.ts, so cleanup belongs here.
+      // A secondary stats or reap failure must not hide the startup diagnostic.
+      try {
+        await this.close();
+      } catch {
+        // The original startup error remains the useful failure.
+      }
+      if (error instanceof YaagError) throw error;
+      const message = error instanceof Error ? error.message : "agent startup failed";
+      throw new YaagError("SPAWN_FAILED", message, this.#name);
+    }
+  }
+
+  send(frame: Frame): void {
+    if (this.#closing) return;
+    this.#process.stdin.write(`${JSON.stringify(frame)}\n`);
+    this.#process.stdin.flush();
+  }
+
+  frames(): AsyncIterable<Frame> {
+    return this.#queue.frames();
+  }
+
+  beginAsk(_marker: AskMarker): undefined {
+    // Nothing to do live; a recording implementation groups frames by this.
+    return undefined;
+  }
+
+  finishAsk(): void {
+    // Live transport has no Cassette outcome to complete.
+  }
+
+  close(): Promise<AgentStats> {
+    this.#closing ??= this.#shutdown();
+    return this.#closing;
+  }
+
+  async #shutdown(): Promise<AgentStats> {
+    // Stats first: they are unavailable once the process is gone (ticket 02).
+    const stats = await this.#readStats();
+    const pid = this.#process.pid;
+    await reap({
+      exited: this.#process.exited,
+      endStdin: () => this.#process.stdin.end(),
+      terminate: () => this.#process.kill("SIGTERM"),
+      destroyGroup: () => {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {
+          this.#process.kill("SIGKILL");
+        }
+      },
+    });
+    this.#queue.end();
+    this.#toolProbe?.fail(
+      new Error(`agent "${this.#name}" exited before tool verification completed`),
+    );
+    return stats;
+  }
+
+  async #readStats(): Promise<AgentStats> {
+    try {
+      const response = await this.#command({ type: "get_session_stats" }, STATS_TIMEOUT_MS);
+      return readStats(response);
+    } catch {
+      return { tokens: null, cost: null };
+    }
+  }
+
+  /** A command the transport issues for itself; its response never reaches the seam. */
+  #command(frame: Frame, timeoutMs: number): Promise<Frame> {
+    const id = `yaag-transport-${this.#nextId++}`;
+    const response = new Promise<Frame>((resolve) => {
+      this.#pending.set(id, resolve);
+    });
+    this.#process.stdin.write(`${JSON.stringify({ ...frame, id })}\n`);
+    this.#process.stdin.flush();
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const failure = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(
+        () =>
+          reject(
+            new YaagError(
+              "SPAWN_FAILED",
+              `agent "${this.#name}" did not answer ${frame.type}`,
+              this.#name,
+            ),
+          ),
+        timeoutMs,
+      );
+    });
+    const death = this.#process.exited.then((code) => {
+      throw new YaagError("SPAWN_FAILED", `agent "${this.#name}" exited (${code})`, this.#name);
+    });
+    return Promise.race([response, failure, death]).finally(() => clearTimeout(timer));
+  }
+
+  async #read(): Promise<void> {
+    for await (const frame of decodeFrames(readChunks(this.#process.stdout))) {
+      if (this.#toolProbe?.accept(frame)) continue;
+      const id = typeof frame.id === "string" ? frame.id : "";
+      const waiting = frame.type === "response" ? this.#pending.get(id) : undefined;
+      if (waiting) {
+        this.#pending.delete(id);
+        waiting(frame);
+        continue;
+      }
+      this.#queue.push(frame);
+    }
+    this.#queue.end();
+    this.#toolProbe?.fail(
+      new Error(`agent "${this.#name}" exited before tool verification completed`),
+    );
+  }
+}
+
+async function* readChunks(stream: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {
+  const reader = stream.getReader();
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      if (value) yield value;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/node-decoder-subagent.ts

@@ -0,0 +1,67 @@
+import type { NodeState } from "./events.ts";
+import type { DecodedNode, NodeDecoder } from "./node-decoder.ts";
+import { isRecord, nodeGist, nodeUsage } from "./node-details.ts";
+
+/**
+ * Decodes the reference `subagent` tool's `SubagentDetails`: one Nested Node per
+ * `results[]` entry, in the order the tool reports them. `exitCode === -1` means
+ * "still running" in that tool, so it stays a running node.
+ */
+export const subagentNodeDecoder: NodeDecoder = {
+  id: "subagent",
+  matches(toolName: string): boolean {
+    return toolName === "subagent";
+  },
+  decode(details: unknown): readonly DecodedNode[] | null {
+    if (!isRecord(details) || !Array.isArray(details.results)) return null;
+    const nodes: DecodedNode[] = [];
+    for (const entry of details.results) {
+      const node = decodeResult(entry);
+      if (node !== null) nodes.push(node);
+    }
+    return nodes;
+  },
+};
+
+function decodeResult(entry: unknown): DecodedNode | null {
+  if (!isRecord(entry) || typeof entry.agent !== "string") return null;
+  const state = resultState(entry);
+  const gist = resultGist(entry);
+  const usage = nodeUsage(entry.usage);
+  return {
+    segments: [entry.agent],
+    state,
+    ...(gist === undefined ? {} : { activityGist: gist }),
+    ...(usage === undefined ? {} : { usage }),
+  };
+}
+
+function resultState(entry: Readonly<Record<string, unknown>>): NodeState {
+  const exitCode = typeof entry.exitCode === "number" ? entry.exitCode : -1;
+  const stopReason = typeof entry.stopReason === "string" ? entry.stopReason : undefined;
+  if (stopReason === "error" || stopReason === "aborted") return "failed";
+  if (exitCode < 0) return "running";
+  return exitCode === 0 ? "exited" : "failed";
+}
+
+function resultGist(entry: Readonly<Record<string, unknown>>): string | undefined {
+  const failure =
+    typeof entry.errorMessage === "string" && entry.errorMessage !== ""
+      ? entry.errorMessage
+      : undefined;
+  const text = failure ?? lastAssistantText(entry.messages);
+  return text === undefined ? undefined : nodeGist(text);
+}
+
+function lastAssistantText(messages: unknown): string | undefined {
+  if (!Array.isArray(messages)) return undefined;
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message: unknown = messages[index];
+    if (!isRecord(message) || message.role !== "assistant") continue;
+    if (!Array.isArray(message.content)) continue;
+    for (const part of message.content) {
+      if (isRecord(part) && part.type === "text" && typeof part.text === "string") return part.text;
+    }
+  }
+  return undefined;
+}

package/src/node-decoder-workflow.ts

@@ -0,0 +1,74 @@
+import type { NodeState } from "./events.ts";
+import type { DecodedNode, NodeDecoder } from "./node-decoder.ts";
+import { isRecord, nodeGist, nodeUsage } from "./node-details.ts";
+
+/**
+ * Decodes pi-extensible-workflows' progress shape: `details.run.agents[]`, each
+ * an `AgentRecord` with a state, an optional structural path, activity and
+ * accounting.
+ *
+ * Tool-name matching is best-effort (spec §3): a workflow tool may register
+ * under `workflow` or a `workflow_`-prefixed name, and a tool that matches but
+ * reports another shape still yields no nodes. A backgrounded run
+ * carries no `run`, so it yields no nodes — its facts leave the RPC stream.
+ */
+export const workflowNodeDecoder: NodeDecoder = {
+  id: "workflow",
+  matches(toolName: string): boolean {
+    return toolName === "workflow" || toolName.startsWith("workflow_");
+  },
+  decode(details: unknown): readonly DecodedNode[] | null {
+    if (!isRecord(details)) return null;
+    const run: unknown = details.run;
+    if (!isRecord(run)) return typeof details.runId === "string" ? [] : null;
+    if (!Array.isArray(run.agents)) return [];
+    const nodes: DecodedNode[] = [];
+    for (const entry of run.agents) {
+      const node = decodeAgent(entry);
+      if (node !== null) nodes.push(node);
+    }
+    return nodes;
+  },
+};
+
+const NODE_STATE_BY_AGENT_STATE: Readonly<Record<string, NodeState>> = {
+  queued: "running",
+  running: "running",
+  waiting_for_child: "running",
+  paused: "running",
+  retrying: "running",
+  completed: "exited",
+  failed: "failed",
+  cancelled: "failed",
+};
+
+function decodeAgent(entry: unknown): DecodedNode | null {
+  if (!isRecord(entry) || typeof entry.name !== "string") return null;
+  if (typeof entry.state !== "string") return null;
+  const state = NODE_STATE_BY_AGENT_STATE[entry.state];
+  if (state === undefined) return null;
+  const gist = agentGist(entry);
+  const usage = nodeUsage(entry.accounting);
+  return {
+    segments: segments(entry),
+    state,
+    ...(gist === undefined ? {} : { activityGist: gist }),
+    ...(usage === undefined ? {} : { usage }),
+  };
+}
+
+function segments(entry: Readonly<Record<string, unknown>>): readonly string[] {
+  const name = typeof entry.label === "string" && entry.label !== "" ? entry.label : entry.name;
+  if (typeof name !== "string") return [];
+  if (!Array.isArray(entry.structuralPath)) return [name];
+  const parents = entry.structuralPath.filter(
+    (part: unknown): part is string => typeof part === "string" && part !== "",
+  );
+  return [...parents, name];
+}
+
+function agentGist(entry: Readonly<Record<string, unknown>>): string | undefined {
+  const activity: unknown = entry.activity;
+  if (!isRecord(activity) || typeof activity.text !== "string") return undefined;
+  return nodeGist(activity.text);
+}

package/src/node-decoder.ts

@@ -0,0 +1,23 @@
+import type { NodeState, NodeUsage } from "./events.ts";
+
+/** One decoded Nested Node, relative to the tool call that produced it. */
+export interface DecodedNode {
+  /** Names from the tool call downwards, e.g. `["test-writer", "1", "fixture-gen"]`. */
+  readonly segments: readonly string[];
+  readonly state: NodeState;
+  readonly activityGist?: string;
+  readonly usage?: NodeUsage;
+}
+
+/**
+ * Knows one nesting tool's detail shape.
+ *
+ * `matches` is best-effort tool-name matching, not a protocol guarantee, so an
+ * unrecognised tool yields no decoder and therefore no nodes. `decode` returns
+ * null when the details do not carry this tool's shape, and never throws.
+ */
+export interface NodeDecoder {
+  readonly id: string;
+  matches(toolName: string): boolean;
+  decode(details: unknown): readonly DecodedNode[] | null;
+}

package/src/node-decoders.ts

@@ -0,0 +1,9 @@
+import type { NodeDecoder } from "./node-decoder.ts";
+import { subagentNodeDecoder } from "./node-decoder-subagent.ts";
+import { workflowNodeDecoder } from "./node-decoder-workflow.ts";
+
+/** The decoders the runtime consults, in order, for every observed tool call. */
+export const DEFAULT_NODE_DECODERS: readonly NodeDecoder[] = [
+  subagentNodeDecoder,
+  workflowNodeDecoder,
+];

package/src/node-details.ts

@@ -0,0 +1,70 @@
+import type { NodeUsage } from "./events.ts";
+import type { TokenBreakdown } from "./transport.ts";
+import { NODE_GIST_MAX_CHARS } from "./wire-constants.ts";
+
+/**
+ * Reading untrusted nesting-tool detail payloads. Every decoder narrows from
+ * `unknown` through here, so a malformed payload is skipped, never thrown on.
+ */
+
+/** Narrows a detail payload to a plain object, the shape every decoder needs. */
+export function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Flattens decoded text to one capped line for a Nested Node's `activityGist`.
+ * Prompts never reach this function (ticket 09).
+ */
+export function nodeGist(value: string): string {
+  return value.replaceAll(/\s+/g, " ").trim().slice(0, NODE_GIST_MAX_CHARS);
+}
+
+/**
+ * Reads one nesting tool's accounting record into a Nested Node's `usage`.
+ *
+ * `NodeUsage` holds optional facts, so this function emits validated facts
+ * only. It emits a token breakdown when all four counts are finite and not
+ * negative, and it emits a cost when the cost is finite and not negative. It
+ * emits each fact independently, and it returns `undefined` when the record
+ * holds no valid fact. It never reports a missing or malformed field as zero.
+ */
+export function nodeUsage(value: unknown): NodeUsage | undefined {
+  if (!isRecord(value)) return undefined;
+  const tokens = tokenBreakdown(value);
+  const cost = count(value.cost);
+  if (tokens === undefined && cost === undefined) return undefined;
+  return {
+    ...(tokens === undefined ? {} : { tokens }),
+    ...(cost === undefined ? {} : { cost }),
+  };
+}
+
+function tokenBreakdown(value: Readonly<Record<string, unknown>>): TokenBreakdown | undefined {
+  const input = count(value.input);
+  const output = count(value.output);
+  const cacheRead = count(value.cacheRead);
+  const cacheWrite = count(value.cacheWrite);
+  if (
+    input === undefined ||
+    output === undefined ||
+    cacheRead === undefined ||
+    cacheWrite === undefined
+  ) {
+    return undefined;
+  }
+  const reported = count(value.total);
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    total: reported ?? input + output + cacheRead + cacheWrite,
+  };
+}
+
+/** A finite, not-negative number, or `undefined` for every other value. */
+function count(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+  return value;
+}

package/src/node-path.ts

@@ -0,0 +1,36 @@
+/**
+ * The Nested Node path grammar `name(:askIndex(/childName…))` (spec §1).
+ *
+ * The Ask index is the wire index carried by `ask_start.index` — 0-based, so a
+ * path always equals a fact already on the wire. Renderers keep displaying
+ * `#index + 1`; they never re-derive identity from the display form.
+ */
+
+/** One Nested Node's identity, e.g. `dev:3/test-writer:1/fixture-gen`. */
+export type NodePath = string;
+
+/** Builds the path of one Agent's Ask from its name and the wire Ask index. */
+export function agentAskPath(agent: string, askIndex: number): NodePath {
+  return `${sanitizeNodeName(agent)}:${askIndex}`;
+}
+
+/** Appends one child segment below a parent path, sanitizing the child name. */
+export function childPath(parent: NodePath, childName: string): NodePath {
+  return `${parent}/${sanitizeNodeName(childName)}`;
+}
+
+/**
+ * Removes the path separators `:` and `/`, control characters, and newlines
+ * from an untrusted node name, so a decoded name cannot forge another node's
+ * path. Returns `node` when nothing printable remains.
+ */
+export function sanitizeNodeName(name: string): string {
+  let text = "";
+  for (const character of name) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code < 32 || code === 127 || (code >= 0x80 && code <= 0x9f)) continue;
+    text += character === ":" || character === "/" ? "-" : character;
+  }
+  const collapsed = text.replaceAll(/\s+/g, " ").trim();
+  return collapsed === "" ? "node" : collapsed;
+}

package/src/node-tracker.ts

@@ -0,0 +1,143 @@
+import type { NodeState, NodeUsage } from "./events.ts";
+import type { DecodedNode, NodeDecoder } from "./node-decoder.ts";
+import { DEFAULT_NODE_DECODERS } from "./node-decoders.ts";
+import { isRecord } from "./node-details.ts";
+import { sanitizeNodeName } from "./node-path.ts";
+import type { Frame } from "./transport.ts";
+
+/** One Nested Node observation, relative to the tool call that produced it. */
+export interface NodeSnapshot {
+  readonly segments: readonly string[];
+  readonly state: NodeState;
+  readonly activityGist?: string;
+  readonly usage?: NodeUsage;
+}
+
+interface TrackedCall {
+  readonly decoder: NodeDecoder;
+  /** First-seen disambiguation of duplicate child names inside one tool call. */
+  readonly names: Map<string, string>;
+  readonly reported: Map<string, NodeSnapshot>;
+}
+
+export interface NodeTrackerOptions {
+  readonly report: (node: NodeSnapshot) => void;
+  readonly decoders?: readonly NodeDecoder[];
+}
+
+/**
+ * Reports Nested Node snapshots decoded from an Agent's own `tool_execution_*`
+ * frames — a sibling of `AskActivityTracker`, above the transport seam, so it
+ * knows frames only (architecture §2).
+ *
+ * Coalescing is dedupe-only, with no timer: a snapshot is reported only when it
+ * differs from the last one reported for that node. That keeps the event stream
+ * a pure function of the frames, so a Cassette replay re-derives it exactly
+ * (ADR-0013).
+ */
+export class NodeTracker {
+  readonly #report: (node: NodeSnapshot) => void;
+  readonly #decoders: readonly NodeDecoder[];
+  readonly #calls = new Map<string, TrackedCall>();
+
+  constructor(options: NodeTrackerOptions) {
+    this.#report = options.report;
+    this.#decoders = options.decoders ?? DEFAULT_NODE_DECODERS;
+  }
+
+  /** Inspects one Agent frame and ignores malformed or unsupported shapes. */
+  observe(frame: Frame): void {
+    const id = typeof frame.toolCallId === "string" ? frame.toolCallId : null;
+    if (id === null) return;
+    if (frame.type === "tool_execution_start") this.#start(id, frame);
+    else if (frame.type === "tool_execution_update") this.#update(id, frame.partialResult);
+    else if (frame.type === "tool_execution_end") this.#end(id, frame);
+  }
+
+  #start(id: string, frame: Frame): void {
+    const toolName = frame.toolName;
+    if (typeof toolName !== "string") return;
+    const decoder = this.#decoders.find((candidate) => candidate.matches(toolName));
+    if (decoder === undefined) return;
+    this.#calls.set(id, { decoder, names: new Map(), reported: new Map() });
+  }
+
+  #update(id: string, payload: unknown): void {
+    const call = this.#calls.get(id);
+    if (call === undefined || !isRecord(payload)) return;
+    this.#decode(call, payload.details);
+  }
+
+  #end(id: string, frame: Frame): void {
+    const call = this.#calls.get(id);
+    if (call === undefined) return;
+    if (isRecord(frame.result)) this.#decode(call, frame.result.details);
+    this.#settle(call, frame.isError === true);
+    this.#calls.delete(id);
+  }
+
+  #decode(call: TrackedCall, details: unknown): void {
+    let decoded: readonly DecodedNode[] | null = null;
+    try {
+      decoded = call.decoder.decode(details);
+    } catch {
+      return;
+    }
+    if (decoded === null) return;
+    const seen = new Map<string, number>();
+    for (const node of decoded) this.#emit(call, node, seen);
+  }
+
+  #emit(call: TrackedCall, node: DecodedNode, seen: Map<string, number>): void {
+    const segments = this.#uniqueSegments(call, node.segments, seen);
+    if (segments === null) return;
+    const snapshot: NodeSnapshot = {
+      segments,
+      state: node.state,
+      ...(node.activityGist === undefined || node.activityGist === ""
+        ? {}
+        : { activityGist: node.activityGist }),
+      ...(node.usage === undefined ? {} : { usage: node.usage }),
+    };
+    const key = segments.join("/");
+    if (same(call.reported.get(key), snapshot)) return;
+    call.reported.set(key, snapshot);
+    this.#report(snapshot);
+  }
+
+  /**
+   * Two calls to the same nested agent inside one tool call are distinct nodes,
+   * but the path grammar has no occurrence slot, so the second and later get a
+   * `-2`, `-3`, … suffix in first-seen order.
+   */
+  #uniqueSegments(
+    call: TrackedCall,
+    segments: readonly string[],
+    seen: Map<string, number>,
+  ): readonly string[] | null {
+    if (segments.length === 0) return null;
+    const sanitized = segments.map(sanitizeNodeName);
+    const base = sanitized.join("/");
+    const occurrence = (seen.get(base) ?? 0) + 1;
+    seen.set(base, occurrence);
+    const key = `${base}#${occurrence}`;
+    const assigned = call.names.get(key) ?? (occurrence === 1 ? base : `${base}-${occurrence}`);
+    call.names.set(key, assigned);
+    return assigned.split("/");
+  }
+
+  /** A tool call that ends with a node still running settles that node (spec §3). */
+  #settle(call: TrackedCall, isError: boolean): void {
+    for (const [key, snapshot] of call.reported) {
+      if (snapshot.state !== "running") continue;
+      const settled: NodeSnapshot = { ...snapshot, state: isError ? "failed" : "exited" };
+      call.reported.set(key, settled);
+      this.#report(settled);
+    }
+  }
+}
+
+function same(left: NodeSnapshot | undefined, right: NodeSnapshot): boolean {
+  if (left === undefined) return false;
+  return JSON.stringify(left) === JSON.stringify(right);
+}