@animalabs/connectome-host 0.3.1

package/src/session-manager.ts

@@ -0,0 +1,278 @@
+/**
+ * Session manager — isolated Chronicle stores with a JSON index.
+ *
+ * Each session is an independent Chronicle store directory under
+ * `{dataDir}/sessions/{id}/`. The index file `{dataDir}/sessions.json`
+ * tracks metadata (name, timestamps, manual naming flag).
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SessionMeta {
+  id: string;
+  name: string;
+  manuallyNamed: boolean;
+  createdAt: string;
+  lastAccessedAt: string;
+  messageCount?: number;
+}
+
+export interface SessionIndex {
+  version: 1;
+  activeSessionId: string;
+  sessions: Record<string, SessionMeta>;
+}
+
+/**
+ * Provenance recorded by the claude.ai importer alongside each session.
+ * Fields are optional because older sessions imported before a given field
+ * existed will simply omit it. Callers reading this should treat every
+ * property as "may be missing" and provide their own fallbacks.
+ *
+ * Lives in `{dataDir}/sessions/{id}.import-source.json`, NOT inside the
+ * Chronicle store directory. Written once by the importer, never updated.
+ */
+export interface ImportSource {
+  conversationUuid?: string;
+  name?: string;
+  summary?: string | null;
+  /** Original `conv.created_at` from the export. */
+  createdAt?: string;
+  /** Original `conv.updated_at` from the export. */
+  updatedAt?: string;
+  /**
+   * Participant name assigned to assistant turns at import time. Warmup and
+   * conhost both read this so they don't disagree about the agent's identity
+   * — disagreement leaves strategy state in the wrong Chronicle namespace
+   * and the live agent silently amnesiac.
+   */
+  agentName?: string;
+  originalMessageCount?: number;
+  importedMessageCount?: number;
+  branched?: boolean;
+  importedAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// SessionManager
+// ---------------------------------------------------------------------------
+
+export class SessionManager {
+  private readonly dataDir: string;
+  private readonly indexPath: string;
+  private readonly sessionsDir: string;
+
+  constructor(dataDir: string) {
+    this.dataDir = dataDir;
+    this.indexPath = join(dataDir, 'sessions.json');
+    this.sessionsDir = join(dataDir, 'sessions');
+  }
+
+  /** Load the session index from disk. Returns empty index if file doesn't exist. */
+  load(): SessionIndex {
+    if (!existsSync(this.indexPath)) {
+      return { version: 1, activeSessionId: '', sessions: {} };
+    }
+    const raw = readFileSync(this.indexPath, 'utf-8');
+    return JSON.parse(raw) as SessionIndex;
+  }
+
+  /** Persist the session index to disk. */
+  save(index: SessionIndex): void {
+    mkdirSync(this.dataDir, { recursive: true });
+    writeFileSync(this.indexPath, JSON.stringify(index, null, 2) + '\n');
+  }
+
+  /** Generate a short random hex ID. */
+  private generateId(): string {
+    return randomBytes(4).toString('hex'); // 8 hex chars
+  }
+
+  /** Create a new session and persist the index. Returns the new session metadata. */
+  createSession(name?: string): SessionMeta {
+    const index = this.load();
+    const id = this.generateId();
+    const now = new Date().toISOString();
+
+    const session: SessionMeta = {
+      id,
+      name: name ?? `Session ${Object.keys(index.sessions).length + 1}`,
+      manuallyNamed: !!name,
+      createdAt: now,
+      lastAccessedAt: now,
+    };
+
+    // Ensure the sessions parent directory exists.
+    // Don't create the store directory itself — JsStore.openOrCreate needs it
+    // absent to know it should create (not open) the store.
+    mkdirSync(this.sessionsDir, { recursive: true });
+
+    index.sessions[id] = session;
+    index.activeSessionId = id;
+    this.save(index);
+
+    return session;
+  }
+
+  /** Delete a session (removes store directory and index entry). Cannot delete the active session. */
+  deleteSession(id: string): void {
+    const index = this.load();
+    if (!index.sessions[id]) {
+      throw new Error(`Session "${id}" not found`);
+    }
+    if (index.activeSessionId === id) {
+      throw new Error('Cannot delete the active session');
+    }
+
+    const storePath = this.getStorePath(id);
+    if (existsSync(storePath)) {
+      rmSync(storePath, { recursive: true, force: true });
+    }
+
+    delete index.sessions[id];
+    this.save(index);
+  }
+
+  /** Rename a session and mark it as manually named. */
+  renameSession(id: string, name: string, manual = true): void {
+    const index = this.load();
+    const session = index.sessions[id];
+    if (!session) {
+      throw new Error(`Session "${id}" not found`);
+    }
+
+    session.name = name;
+    if (manual) session.manuallyNamed = true;
+    this.save(index);
+  }
+
+  /** Get the Chronicle store directory path for a session. */
+  getStorePath(id: string): string {
+    return join(this.sessionsDir, id);
+  }
+
+  /**
+   * Read the import-source sidecar for a session, if one exists.
+   *
+   * Returns null when the session wasn't created by the importer (no
+   * sidecar), when the file can't be read, when its contents don't parse
+   * as JSON, or when the parsed value isn't a plain object (e.g. someone
+   * wrote `null` or an array). The caller gets a partial record — every
+   * field is optional, because sidecars written by older importer
+   * versions may be missing newer fields.
+   *
+   * Field-level types are NOT validated here: this is a filesystem trust
+   * boundary, but field-shape regressions would touch each consumer's
+   * usage site anyway, and the typeof-string guards in
+   * `resolveAgentName`/inline at call sites catch the values that
+   * actually flow through.
+   */
+  getImportSource(id: string): ImportSource | null {
+    const path = join(this.sessionsDir, `${id}.import-source.json`);
+    if (!existsSync(path)) return null;
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(path, 'utf-8'));
+      if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+      }
+      return parsed as ImportSource;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Get the currently active session, or null if none. */
+  getActiveSession(): SessionMeta | null {
+    const index = this.load();
+    if (!index.activeSessionId) return null;
+    return index.sessions[index.activeSessionId] ?? null;
+  }
+
+  /** Set the active session and update its lastAccessedAt. */
+  setActiveSession(id: string): void {
+    const index = this.load();
+    if (!index.sessions[id]) {
+      throw new Error(`Session "${id}" not found`);
+    }
+    index.activeSessionId = id;
+    index.sessions[id]!.lastAccessedAt = new Date().toISOString();
+    this.save(index);
+  }
+
+  /** Find a session by name or ID. */
+  findSession(nameOrId: string): SessionMeta | null {
+    const index = this.load();
+    // Exact ID match
+    if (index.sessions[nameOrId]) return index.sessions[nameOrId]!;
+    // Name match (case-insensitive)
+    for (const session of Object.values(index.sessions)) {
+      if (session.name.toLowerCase() === nameOrId.toLowerCase()) return session;
+    }
+    // Prefix match on ID
+    for (const session of Object.values(index.sessions)) {
+      if (session.id.startsWith(nameOrId)) return session;
+    }
+    return null;
+  }
+
+  /** List all sessions, sorted by lastAccessedAt descending. */
+  listSessions(): SessionMeta[] {
+    const index = this.load();
+    return Object.values(index.sessions)
+      .sort((a, b) => b.lastAccessedAt.localeCompare(a.lastAccessedAt));
+  }
+
+  /**
+   * Migrate legacy single-store layout to session-based layout.
+   *
+   * If `{dataDir}/store/` exists but `{dataDir}/sessions.json` doesn't,
+   * moves the store into `{dataDir}/sessions/{id}/` and creates the index.
+   */
+  migrateIfNeeded(): void {
+    if (existsSync(this.indexPath)) return;
+
+    const legacyStorePath = join(this.dataDir, 'store');
+    if (!existsSync(legacyStorePath)) return;
+
+    const id = this.generateId();
+    const now = new Date().toISOString();
+
+    // Move legacy store into sessions directory
+    mkdirSync(this.sessionsDir, { recursive: true });
+    const newPath = join(this.sessionsDir, id);
+    renameSync(legacyStorePath, newPath);
+
+    const index: SessionIndex = {
+      version: 1,
+      activeSessionId: id,
+      sessions: {
+        [id]: {
+          id,
+          name: 'Initial Session',
+          manuallyNamed: false,
+          createdAt: now,
+          lastAccessedAt: now,
+        },
+      },
+    };
+
+    this.save(index);
+    console.log(`Migrated legacy store to session "${id}" (Initial Session)`);
+  }
+
+  /** Update the message count snapshot for a session. */
+  updateMessageCount(id: string, count: number): void {
+    const index = this.load();
+    const session = index.sessions[id];
+    if (session) {
+      session.messageCount = count;
+      this.save(index);
+    }
+  }
+}

package/src/state/agent-tree-reducer.ts

@@ -0,0 +1,431 @@
+/**
+ * AgentTreeReducer — folds framework TraceEvents into a tree of agent nodes
+ * with phase / token / tool-count / parent-edge state.
+ *
+ * Single fold logic, three call sites:
+ *   1. Parent process, against local `framework.onTrace()` — drives local TUI.
+ *   2. Parent process, against `fleetModule.onChildEvent(name, ...)` — one
+ *      reducer per fleet child, drives that child's subtree in the TUI.
+ *   3. Inside each headless child, against its own `framework.onTrace()` —
+ *      `describe` IPC handler returns `reducer.getTree()` over the wire.
+ *
+ * Mirrors the canonical fold currently scattered across:
+ *   - tui.ts:1019-1037     (token aggregation on inference:usage / completed)
+ *   - tui.ts:1280-1341     (phase transitions)
+ *   - tui.ts:1100-1107     (parent-edge inference from subagent--spawn calls)
+ *   - subagent-module.ts:262-340 (callId routing, live state tracking)
+ *
+ * The dispatch table EVENT_HANDLERS is the canonical source of truth: each
+ * key is an event type the reducer acts on, and `REDUCER_REQUIRED_EVENTS`
+ * is derived from `Object.keys(EVENT_HANDLERS)`. Adding a new case requires
+ * adding to the table; the wire-level subscription floor enforced by
+ * FleetModule picks up the addition automatically. There is no parallel
+ * "list of events the reducer needs" to keep in sync by hand.
+ */
+
+import type { TraceEvent } from '@animalabs/agent-framework';
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type AgentPhase =
+  | 'idle'
+  | 'sending'
+  | 'streaming'
+  | 'invoking'
+  | 'executing'
+  | 'done'
+  | 'failed'
+  // Terminal-but-benign: user cancel, zombie-reclaim, supersession, agent
+  // reboot, budget-restart. Postmortem 2026-05-28 P1 #3: renderers must
+  // treat this as neutral (not red) and terminal (not 'running'). It is the
+  // result of `inference:aborted` and reboot-induced `inference:exhausted`,
+  // both of which are NOT faults.
+  | 'cancelled';
+
+export type AgentKind = 'framework' | 'subagent';
+
+export type AgentStatus = 'running' | 'completed' | 'failed' | 'cancelled';
+
+export interface AgentTokens {
+  /** Last-seen input tokens. Represents *current context window size*, not cumulative. */
+  input: number;
+  /** Cumulative output tokens across all rounds. */
+  output: number;
+  /** Cumulative cache-read tokens. */
+  cacheRead: number;
+  /** Cumulative cache-write (creation) tokens. */
+  cacheWrite: number;
+}
+
+export interface AgentNode {
+  /** Stable identifier within this reducer's scope. For framework agents this is
+   *  the framework's agent name. For subagents it's the spawn/fork display name. */
+  name: string;
+  kind: AgentKind;
+  /** Subagent-only: spawn vs. fork (fork inherits parent context). */
+  subagentType?: 'spawn' | 'fork';
+  /** Subagent-only: the task string from the spawning tool call. */
+  task?: string;
+  /** Parent agent name (the agent that spawned this one), if any. */
+  parent?: string;
+  status: AgentStatus;
+  phase: AgentPhase;
+  tokens: AgentTokens;
+  toolCallsCount: number;
+  findingsCount: number;
+  startedAt?: number;
+  completedAt?: number;
+  lastEventAt?: number;
+}
+
+export interface AgentTreeSnapshot {
+  /** Wall-clock at which this snapshot was produced. Receivers should drop
+   *  events with `timestamp < asOfTs` after applying. */
+  asOfTs: number;
+  nodes: AgentNode[];
+  /** callId → agentName, for routing tool:* events that arrive after the snapshot. */
+  callIdIndex: Record<string, string>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function freshTokens(): AgentTokens {
+  return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+}
+
+interface SpawnCallInput {
+  name?: string;
+  task?: string;
+  prompt?: string;
+}
+
+interface AnyEvent {
+  type: string;
+  agentName?: string;
+  callId?: string;
+  timestamp?: number;
+  [k: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Event handler table — single source of truth for "which events does the
+// reducer act on" and (by extension) "which events must the wire deliver."
+// ---------------------------------------------------------------------------
+
+type EventHandler = (r: AgentTreeReducer, e: AnyEvent, ts: number) => void;
+
+/** The dispatch table. `applyEvent` is just a Map lookup over this; recipes
+ *  can't accidentally turn off rendering because `REDUCER_REQUIRED_EVENTS`
+ *  (below) is derived from the keys here. */
+const EVENT_HANDLERS: Record<string, EventHandler> = {
+  'inference:started': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'sending';
+    node.status = 'running';
+    node.lastEventAt = ts;
+    if (node.startedAt === undefined) node.startedAt = ts;
+  },
+
+  'inference:tokens': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'streaming';
+    node.lastEventAt = ts;
+  },
+
+  'inference:tool_calls_yielded': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'invoking';
+    node.lastEventAt = ts;
+    const calls = (e.calls as Array<{ id: string; name: string; input?: unknown }> | undefined) ?? [];
+    for (const call of calls) {
+      r._setCallIdAgent(call.id, e.agentName);
+      // Edge inference: subagent--spawn / subagent--fork / fleet--launch
+      // tool calls create a parent edge from the calling agent to the child.
+      if (call.name === 'subagent--spawn' || call.name === 'subagent--fork') {
+        const childName = (call.input as SpawnCallInput | undefined)?.name;
+        if (childName) {
+          const child = r._ensureNode(childName, 'subagent');
+          child.parent = e.agentName;
+          child.subagentType = call.name === 'subagent--fork' ? 'fork' : 'spawn';
+          const inp = call.input as SpawnCallInput | undefined;
+          if (inp?.task) child.task = inp.task;
+          else if (inp?.prompt) child.task = inp.prompt;
+          if (child.startedAt === undefined) child.startedAt = ts;
+        }
+      } else if (call.name === 'fleet--launch') {
+        const childName = (call.input as SpawnCallInput | undefined)?.name;
+        if (childName) {
+          const child = r._ensureNode(childName, 'framework');
+          child.parent = e.agentName;
+        }
+      }
+    }
+  },
+
+  'inference:usage': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    const usage = e.tokenUsage as { input?: number; output?: number; cacheRead?: number; cacheCreation?: number } | undefined;
+    if (usage) r._applyTokenUsage(node, usage);
+    node.lastEventAt = ts;
+  },
+
+  'inference:completed': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'done';
+    // Postmortem 2026-05-28 F1: writing 'completed' here closes a one-way
+    // failed latch. Before this, the only status transitions were
+    // running → failed (via aborted/exhausted/failed) and the only way out
+    // was a fresh inference:started. So a benign abort followed by a clean
+    // completion left the admin UI red forever for that node.
+    node.status = 'completed';
+    node.completedAt = ts;
+    node.lastEventAt = ts;
+    const usage = e.tokenUsage as { input?: number; output?: number; cacheRead?: number; cacheCreation?: number } | undefined;
+    if (usage) r._applyTokenUsage(node, usage);
+  },
+
+  'inference:failed': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'failed';
+    node.status = 'failed';
+    node.completedAt = ts;
+    node.lastEventAt = ts;
+  },
+
+  // inference:exhausted = budget exhaustion / stream-side cancel / reboot-
+  // induced. Postmortem 2026-05-28 P1 #3: not strictly a fault — flip both
+  // fields to the dedicated 'cancelled' terminal state so the renderer can
+  // distinguish "stopped on purpose" from "errored out".
+  'inference:exhausted': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'cancelled';
+    node.status = 'cancelled';
+    node.completedAt = ts;
+    node.lastEventAt = ts;
+  },
+
+  // inference:aborted = user cancel / zombie-reclaim / supersession.
+  // Postmortem 2026-05-28 P1 #3: same as exhausted — terminal, but benign.
+  'inference:aborted': (r, e, ts) => {
+    if (!e.agentName) return;
+    const node = r._ensureNode(e.agentName);
+    node.phase = 'cancelled';
+    node.status = 'cancelled';
+    node.completedAt = ts;
+    node.lastEventAt = ts;
+  },
+
+  'inference:stream_resumed': (r, e, ts) => {
+    if (!e.agentName) return;
+    r._ensureNode(e.agentName).lastEventAt = ts;
+  },
+
+  'inference:stream_restarted': (r, e, ts) => {
+    if (!e.agentName) return;
+    r._ensureNode(e.agentName).lastEventAt = ts;
+  },
+
+  'inference:turn_ended': (r, e, ts) => {
+    if (!e.agentName) return;
+    r._ensureNode(e.agentName).lastEventAt = ts;
+  },
+
+  'tool:started': (r, e, ts) => {
+    if (typeof e.callId !== 'string') return;
+    const agentName = r._getCallIdAgent(e.callId);
+    if (!agentName) return;
+    const node = r._ensureNode(agentName);
+    node.phase = 'executing';
+    node.toolCallsCount += 1;
+    node.lastEventAt = ts;
+  },
+
+  'tool:completed': (r, e, ts) => {
+    if (typeof e.callId !== 'string') return;
+    const agentName = r._getCallIdAgent(e.callId);
+    if (!agentName) return;
+    r._ensureNode(agentName).lastEventAt = ts;
+    // Phase stays 'executing' until the next inference:* event re-binds it.
+    // Mirrors tui.ts behavior where tool:completed only clears the per-agent
+    // current-tool indicator without changing the high-level phase.
+  },
+
+  'tool:failed': (r, e, ts) => {
+    if (typeof e.callId !== 'string') return;
+    const agentName = r._getCallIdAgent(e.callId);
+    if (!agentName) return;
+    r._ensureNode(agentName).lastEventAt = ts;
+  },
+};
+
+/**
+ * The minimum set of framework TraceEvent types this reducer needs to fold an
+ * accurate per-agent tree. **Derived** from `EVENT_HANDLERS` at module load —
+ * adding a new case to the table automatically propagates here, so the wire-
+ * subscription floor in FleetModule (`unionWithReducerRequired`) self-extends
+ * with no manual constant maintenance.
+ *
+ * If a new event type is wired into the reducer, no other file needs to
+ * change for the wire to start delivering it.
+ */
+export const REDUCER_REQUIRED_EVENTS: readonly string[] = Object.freeze(Object.keys(EVENT_HANDLERS));
+
+// ---------------------------------------------------------------------------
+// Reducer
+// ---------------------------------------------------------------------------
+
+export class AgentTreeReducer {
+  private nodes = new Map<string, AgentNode>();
+  /** callId → agentName, populated from inference:tool_calls_yielded. Tool events
+   *  carry only callId, no agentName, so we route them through here. */
+  private callIdIndex = new Map<string, string>();
+
+  /** Pre-register top-level framework agents so the tree shows them before
+   *  they emit any events. Lazy creation also works on first event. */
+  seedFrameworkAgents(names: string[]): void {
+    for (const name of names) {
+      if (!this.nodes.has(name)) {
+        this.nodes.set(name, this.makeNode(name, 'framework'));
+      }
+    }
+  }
+
+  applyEvent(event: TraceEvent | { type: string }): void {
+    // We only branch on event.type and read fields the handler table expects;
+    // fields outside the type's static shape are accessed dynamically. Widen
+    // here so callers can pass any tagged event object (TraceEvent, WireEvent,
+    // synthetic test events) without an `as never` escape hatch.
+    const e = event as AnyEvent;
+    const ts = typeof e.timestamp === 'number' ? e.timestamp : Date.now();
+    const handler = EVENT_HANDLERS[e.type];
+    if (!handler) return;
+    handler(this, e, ts);
+  }
+
+  applySnapshot(snapshot: AgentTreeSnapshot): void {
+    this.nodes.clear();
+    this.callIdIndex.clear();
+    for (const node of snapshot.nodes) {
+      // Defensive copy so subsequent mutations don't escape into caller's data.
+      this.nodes.set(node.name, {
+        ...node,
+        tokens: { ...node.tokens },
+      });
+    }
+    for (const [callId, agentName] of Object.entries(snapshot.callIdIndex)) {
+      this.callIdIndex.set(callId, agentName);
+    }
+  }
+
+  reset(): void {
+    this.nodes.clear();
+    this.callIdIndex.clear();
+  }
+
+  /** Returns a deep copy of the current tree state plus the asOfTs marker
+   *  needed for receivers to dedupe events. */
+  getSnapshot(): AgentTreeSnapshot {
+    return {
+      asOfTs: Date.now(),
+      nodes: this.getNodes(),
+      callIdIndex: Object.fromEntries(this.callIdIndex),
+    };
+  }
+
+  /** Returns a deep copy of all current nodes. */
+  getNodes(): AgentNode[] {
+    return [...this.nodes.values()].map(n => ({
+      ...n,
+      tokens: { ...n.tokens },
+    }));
+  }
+
+  getNode(name: string): AgentNode | undefined {
+    const n = this.nodes.get(name);
+    if (!n) return undefined;
+    return { ...n, tokens: { ...n.tokens } };
+  }
+
+  /** Returns the children of a given agent (one level deep).
+   *  Iterates the live map directly — no full tree clone. */
+  getChildren(parentName: string): AgentNode[] {
+    const out: AgentNode[] = [];
+    for (const n of this.nodes.values()) {
+      if (n.parent === parentName) out.push({ ...n, tokens: { ...n.tokens } });
+    }
+    return out;
+  }
+
+  /** Returns top-level (parent-less) nodes. */
+  getRoots(): AgentNode[] {
+    const out: AgentNode[] = [];
+    for (const n of this.nodes.values()) {
+      if (n.parent === undefined) out.push({ ...n, tokens: { ...n.tokens } });
+    }
+    return out;
+  }
+
+  // ----- @internal: exposed for the module-scope EVENT_HANDLERS table. ----
+  // Underscore-prefixed by convention; not part of the public API.
+  // External callers should use the public read methods (getNode, getNodes,
+  // getChildren, getRoots) and applyEvent / applySnapshot for mutation.
+
+  /** @internal */
+  _ensureNode(name: string, kindHint: AgentKind = 'framework'): AgentNode {
+    let node = this.nodes.get(name);
+    if (!node) {
+      node = this.makeNode(name, kindHint);
+      this.nodes.set(name, node);
+    }
+    return node;
+  }
+
+  /** @internal */
+  _setCallIdAgent(callId: string, agentName: string): void {
+    this.callIdIndex.set(callId, agentName);
+  }
+
+  /** @internal */
+  _getCallIdAgent(callId: string): string | undefined {
+    return this.callIdIndex.get(callId);
+  }
+
+  /** @internal */
+  _applyTokenUsage(
+    node: AgentNode,
+    usage: { input?: number; output?: number; cacheRead?: number; cacheCreation?: number },
+  ): void {
+    // Input represents context window size at this round; overwrite, don't sum
+    // (summing inputs would double-count history that's already in the next round's input).
+    if (typeof usage.input === 'number') node.tokens.input = usage.input;
+    // Output / cache are per-round costs; accumulate.
+    if (typeof usage.output === 'number') node.tokens.output += usage.output;
+    if (typeof usage.cacheRead === 'number') node.tokens.cacheRead += usage.cacheRead;
+    if (typeof usage.cacheCreation === 'number') node.tokens.cacheWrite += usage.cacheCreation;
+  }
+
+  // ----- private --------------------------------------------------------
+
+  private makeNode(name: string, kind: AgentKind): AgentNode {
+    return {
+      name,
+      kind,
+      status: 'running',
+      phase: 'idle',
+      tokens: freshTokens(),
+      toolCallsCount: 0,
+      findingsCount: 0,
+    };
+  }
+}