@genesislcap/ai-assistant 15.26.0 → 15.27.0

package/dist/chat-driver.mjs

@@ -3719,70 +3719,6 @@ function clearSession(key) {
 // src/utils/logger.ts
 var logger2 = createLogger("ai-assistant");
 
-// src/state/interaction-context.ts
-function createInteractionContext(interactionId) {
-  const state = {};
-  const onceCache = /* @__PURE__ */ new Map();
-  const listeners = /* @__PURE__ */ new Set();
-  const disposers = /* @__PURE__ */ new Set();
-  let disposed = false;
-  const context = {
-    interactionId,
-    state,
-    once(key, factory) {
-      if (onceCache.has(key)) return onceCache.get(key);
-      if (disposed) {
-        logger2.warn(
-          `InteractionContext.once("${key}") called after dispose; not creating a resource on an ended interaction.`
-        );
-        return null;
-      }
-      const value = factory();
-      onceCache.set(key, value);
-      return value;
-    },
-    notify() {
-      for (const listener of listeners) {
-        try {
-          listener();
-        } catch (e) {
-          logger2.error("InteractionContext subscriber threw during notify()", e);
-        }
-      }
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    onDispose(fn) {
-      if (disposed) {
-        fn();
-        return;
-      }
-      disposers.add(fn);
-    }
-  };
-  return {
-    context,
-    dispose() {
-      if (disposed) return;
-      disposed = true;
-      for (const fn of disposers) {
-        try {
-          fn();
-        } catch (e) {
-          logger2.error("InteractionContext onDispose callback threw", e);
-        }
-      }
-      disposers.clear();
-      listeners.clear();
-      onceCache.clear();
-    }
-  };
-}
-
 // src/suggestions/generate-suggestions.ts
 var HISTORY_WINDOW = 8;
 function capabilities(ctx, allAgentInfo) {
@@ -4755,6 +4691,250 @@ var FoldController = class {
   }
 };
 
+// src/state/interaction-context.ts
+function createInteractionContext(interactionId) {
+  const state = {};
+  const onceCache = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  const disposers = /* @__PURE__ */ new Set();
+  let disposed = false;
+  const context = {
+    interactionId,
+    state,
+    once(key, factory) {
+      if (onceCache.has(key)) return onceCache.get(key);
+      if (disposed) {
+        logger2.warn(
+          `InteractionContext.once("${key}") called after dispose; not creating a resource on an ended interaction.`
+        );
+        return null;
+      }
+      const value = factory();
+      onceCache.set(key, value);
+      return value;
+    },
+    notify() {
+      for (const listener of listeners) {
+        try {
+          listener();
+        } catch (e) {
+          logger2.error("InteractionContext subscriber threw during notify()", e);
+        }
+      }
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    onDispose(fn) {
+      if (disposed) {
+        fn();
+        return;
+      }
+      disposers.add(fn);
+    }
+  };
+  return {
+    context,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      for (const fn of disposers) {
+        try {
+          fn();
+        } catch (e) {
+          logger2.error("InteractionContext onDispose callback threw", e);
+        }
+      }
+      disposers.clear();
+      listeners.clear();
+      onceCache.clear();
+    }
+  };
+}
+
+// src/components/chat-driver/interaction-controller.ts
+var InteractionController = class {
+  constructor(deps) {
+    this.deps = deps;
+    this.pending = /* @__PURE__ */ new Map();
+    /**
+     * Live per-interaction contexts (GENC-1390), keyed by interactionId. Created in `request`
+     * alongside the pending entry, disposed + removed in `resolve`. Non-serialisable (sockets,
+     * timers, subscriber sets), so they live here — not on the DOM, not in the persisted store — and
+     * therefore survive the element remounts (layout reflow/drag, transcript re-render) that this
+     * feature exists to make harmless. At most one is live at a time (see the
+     * one-interaction-at-a-time guard in `request`).
+     */
+    this.contexts = /* @__PURE__ */ new Map();
+  }
+  /** See `ChatDriver.setHostInteractionRequester`. */
+  setHostRequester(fn) {
+    this.hostRequester = fn;
+  }
+  /** See `ChatDriver.requestInteraction`. */
+  request(componentName, data, options) {
+    if (this.hostRequester) {
+      return this.hostRequester(componentName, data, options);
+    }
+    if (this.pending.size > 0) {
+      throw new Error(
+        "requestInteraction: another user interaction is already in flight. Only one interaction may be active at a time \u2014 sequence them in a single tool handler rather than spawning widgets from parallel sub-agents or parallel tool calls."
+      );
+    }
+    const interactionId = crypto.randomUUID();
+    const chatInputDuringExecution = options?.chatInputDuringExecution;
+    const timeoutMs = options?.timeoutMs;
+    const presentation = options?.presentation;
+    return new Promise((resolve, reject) => {
+      this.pending.set(interactionId, {
+        resolve,
+        reject,
+        overrideId: chatInputDuringExecution ? interactionId : void 0,
+        // Resolve the interaction with a timeout result if the user does not
+        // respond in time. `resolve` runs the same teardown a normal resolution
+        // does (marks the widget read-only, reverts any input override) and
+        // clears any still-pending handle.
+        timeoutHandle: timeoutMs != null ? setTimeout(() => {
+          this.resolve(interactionId, {
+            status: "timeout",
+            message: `Interaction timed out after ${timeoutMs}ms.`
+          });
+        }, timeoutMs) : void 0
+      });
+      recordMetaEvent(this.deps.sessionKey, "interaction.requested", {
+        interactionId,
+        component: componentName,
+        agent: this.deps.activeAgentName()
+      });
+      this.deps.activityBus.publish("interaction-requested", void 0);
+      if (chatInputDuringExecution) {
+        this.deps.emit(
+          new CustomEvent("interaction-start", {
+            detail: { interactionId, chatInputDuringExecution }
+          })
+        );
+      }
+      this.contexts.set(interactionId, createInteractionContext(interactionId));
+      this.deps.appendToHistory({
+        role: "assistant",
+        content: "",
+        interaction: {
+          interactionId,
+          componentName,
+          data,
+          ...presentation ? { presentation } : {}
+        }
+      });
+    });
+  }
+  /**
+   * See `ChatDriver.resolveInteraction`. Warns and returns when the id is unknown — a widget can
+   * report twice, and the second report has nothing left to settle.
+   */
+  resolve(interactionId, result) {
+    const interaction = this.pending.get(interactionId);
+    if (!interaction) {
+      logger2.warn(`Interaction with ID ${interactionId} not found.`);
+      return;
+    }
+    if (interaction.timeoutHandle) clearTimeout(interaction.timeoutHandle);
+    this.deps.foldDiagnostics(
+      interactionId,
+      result?.diagnostics
+    );
+    const costUsd = typeof result?.costUsd === "number" && Number.isFinite(result.costUsd) && result.costUsd > 0 ? result.costUsd : void 0;
+    const patched = this.deps.patchInteractionMessage(interactionId, (message) => ({
+      ...message,
+      interaction: { ...message.interaction, resolved: result },
+      ...costUsd != null ? { externalCostUsd: (message.externalCostUsd ?? 0) + costUsd } : {}
+    }));
+    if (patched) this.deps.notifyHistoryUpdated();
+    if (typeof result?.userMessage === "string" && result.userMessage.trim()) {
+      this.deps.appendToHistory({ role: "synthetic-user", content: result.userMessage });
+    }
+    if (interaction.overrideId) {
+      this.deps.emit(new CustomEvent("interaction-stop", { detail: { interactionId } }));
+    }
+    recordMetaEvent(this.deps.sessionKey, "interaction.resolved", { interactionId });
+    this.deps.activityBus.publish("interaction-resolved", void 0);
+    interaction.resolve(result);
+    this.pending.delete(interactionId);
+    this.contexts.get(interactionId)?.dispose();
+    this.contexts.delete(interactionId);
+  }
+  /**
+   * See `ChatDriver.recordExternalCost`.
+   *
+   * **Why this exists separately from `resolve`.** A widget's spend reaches the session total only
+   * through `InteractionResult.costUsd`, which is read exactly once — `resolve` does its whole job
+   * against a live pending entry and then deletes it. That is correct for the resolution itself,
+   * but it assumes a widget stops costing money when it resolves, and several deliberately do not:
+   * a widget that resolves EARLY so the assistant stops waiting (options shown, a preview
+   * rendered) may stay interactive for minutes afterwards and do more paid work on the user's
+   * behalf. Re-emitting `interaction-completed` does not help — with the interaction gone from the
+   * map the call is a silent no-op — so that spend had nowhere to go and was simply missing from
+   * the figure shown to the user.
+   *
+   * Touches only `externalCostUsd`: the recorded `interaction.resolved` payload is left exactly as
+   * the resolution wrote it, because this is not a second resolution and must not read like one.
+   */
+  recordExternalCost(interactionId, costUsd) {
+    const drop = (reason) => {
+      recordMetaEvent(this.deps.sessionKey, "interaction.external-cost-dropped", {
+        interactionId,
+        costUsd,
+        reason
+      });
+      return false;
+    };
+    if (!interactionId) return drop("no interactionId");
+    if (typeof costUsd !== "number" || !Number.isFinite(costUsd) || costUsd <= 0) {
+      return drop("not a positive finite amount");
+    }
+    const patched = this.deps.patchInteractionMessage(interactionId, (message) => ({
+      ...message,
+      externalCostUsd: (message.externalCostUsd ?? 0) + costUsd
+    }));
+    if (!patched) return drop("interaction message no longer in history");
+    recordMetaEvent(this.deps.sessionKey, "interaction.external-cost", { interactionId, costUsd });
+    this.deps.emit(
+      new CustomEvent("external-cost-recorded", {
+        detail: { interactionId, costUsd }
+      })
+    );
+    return true;
+  }
+  /** See `ChatDriver.getInteractionContext`. */
+  context(interactionId) {
+    return this.contexts.get(interactionId)?.context;
+  }
+  /**
+   * Resolve every in-flight interaction with a `'timeout'` result, closing its
+   * widget read-only. Used when a sub-agent that owns the open widget times out:
+   * the widget is parked in *this* driver's map (interactions resolve on the
+   * host, not the child), so cancelling it here unblocks the sub-agent handler
+   * awaiting it. The "one interaction at a time" invariant means there is at
+   * most one.
+   */
+  cancelAll(message) {
+    for (const interactionId of [...this.pending.keys()]) {
+      this.resolve(interactionId, { status: "timeout", message });
+    }
+  }
+  /**
+   * Drop any live interaction contexts on driver teardown. Normally empty (a context is created
+   * and destroyed with its pending interaction, and dispose is not reached mid-interaction);
+   * disposed defensively so a stray context can never leak an open socket/timer.
+   */
+  disposeContexts() {
+    for (const handle of this.contexts.values()) handle.dispose();
+    this.contexts.clear();
+  }
+};
+
 // src/components/chat-driver/turn-failures.ts
 var TURN_FAILURE_EXITS = {
   contextGuard: {
@@ -4836,6 +5016,160 @@ function turnDone(failureReason, budget, providerRefused) {
   };
 }
 
+// src/components/chat-driver/turn-recorder.ts
+var TurnRecorder = class {
+  constructor(sessionKey, maxSnapshots) {
+    this.sessionKey = sessionKey;
+    this.maxSnapshots = maxSnapshots;
+    /**
+     * Ring buffer of per-LLM-call snapshots, capped at `maxSnapshots`; older entries drop off as
+     * new ones arrive.
+     */
+    this.buffer = [];
+    /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
+    this.turnIndex = 0;
+    /**
+     * `turn` + `message` diagnostic entries harvested from an out-of-band source. `event` entries
+     * are NOT kept here — they are folded into the session's meta-event registry so they inherit
+     * fresh host indices, and reach the log through `getMetaEvents`. Append-only, and never cleared:
+     * it lives with the recorder, so a new chat (fresh driver) starts empty while a compaction (same
+     * instance) keeps it. (GENC-1461.)
+     */
+    this.externalEntries = [];
+    /**
+     * Monotonic count of external-diagnostics batches folded this driver-lifetime. Namespaces each
+     * batch's re-keyed `turn` entries so distinct server generations in one chat session can't
+     * collide on `turnIndex` in the forward-capture persister (which dedups turns by that key).
+     */
+    this.externalBatches = 0;
+  }
+  /** Point at the incoming agent's `getDebugSnapshot`, or clear it when the agent supplies none. */
+  setSnapshotter(snapshotter) {
+    this.snapshotter = snapshotter;
+  }
+  /**
+   * The per-turn snapshots captured so far — what the LLM saw on each turn: system prompt, tool
+   * surface, and agent-supplied state (e.g. a machine snapshot).
+   */
+  snapshots() {
+    return this.buffer;
+  }
+  /**
+   * The harvested `turn` + `message` diagnostic entries. Opaque, and chronologically sorted by the
+   * host at assemble time.
+   */
+  externalDiagnostics() {
+    return this.externalEntries;
+  }
+  /**
+   * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
+   * before each LLM call — that's the latest point where the prompt, tool
+   * surface, and agent state line up with what the model is about to see.
+   *
+   * Returns the pushed object so the caller can back-fill what only the response
+   * knows (`usage`). Mutating it after the fact is safe whether or not the ring
+   * buffer has since evicted it — an evicted snapshot is simply no longer exported.
+   */
+  record(turn) {
+    let agentSnapshot;
+    if (this.snapshotter) {
+      try {
+        agentSnapshot = this.snapshotter();
+      } catch (e) {
+        agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
+      }
+    }
+    const turnIndex = String(this.turnIndex);
+    this.turnIndex += 1;
+    const snapshot = {
+      ...turn,
+      turnIndex,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      agentSnapshot
+    };
+    this.buffer.push(snapshot);
+    this.trim();
+    return snapshot;
+  }
+  /**
+   * Merge a sub-agent's turn snapshots into this driver's buffer so they surface
+   * as `kind:'turn'` entries in the exported debug log. The child runs as a
+   * separate, discarded driver, so its snapshots would otherwise be lost. Each is
+   * re-labelled under the parent turn that activated the sub-agent: the child's
+   * own (numeric) turns become `"<parentTurn>-1"`, `"-2"`, … (1-based, in order);
+   * any already-forwarded grand-child labels (strings) have their leading segment
+   * remapped the same way, so nesting composes (`"5-2"` → `"5-2-1"`).
+   *
+   * Note: two sub-agents invoked in the *same* parent turn share the prefix, so
+   * their labels can repeat — `agentName` on each snapshot disambiguates them.
+   */
+  forwardSubAgent(childSnapshots) {
+    if (childSnapshots.length === 0) return;
+    const parentTurn = Math.max(0, this.turnIndex - 1);
+    const ownTurnLabel = /* @__PURE__ */ new Map();
+    let ownPos = 0;
+    for (const snap of childSnapshots) {
+      let turnIndex;
+      if (!snap.turnIndex.includes("-")) {
+        ownPos += 1;
+        turnIndex = `${parentTurn}-${ownPos}`;
+        ownTurnLabel.set(snap.turnIndex, turnIndex);
+      } else {
+        const [lead, ...rest] = snap.turnIndex.split("-");
+        const leadLabel = ownTurnLabel.get(lead) ?? `${parentTurn}-${lead}`;
+        turnIndex = [leadLabel, ...rest].join("-");
+      }
+      this.buffer.push({ ...snap, turnIndex });
+    }
+    this.trim();
+  }
+  /**
+   * Fold a widget's out-of-band diagnostics into this session — typically a server-side
+   * ChatDriver's collated log, arriving on `InteractionResult.diagnostics` — so the host's debug
+   * log and persisted diagnostics stream include them. Independent of the interaction's own
+   * message: these describe the widget's work, not that message. A non-array or empty harvest is
+   * a no-op.
+   */
+  foldDiagnostics(interactionId, harvested) {
+    if (!Array.isArray(harvested) || !harvested.length) return;
+    const batch = this.externalBatches += 1;
+    const externalEvents = [];
+    let turnCount = 0;
+    let messageCount = 0;
+    for (const raw of harvested) {
+      if (!raw || typeof raw !== "object" || typeof raw.kind !== "string") {
+        continue;
+      }
+      const entry = raw;
+      if (entry.kind === "event") {
+        const { kind: _kind, ...event } = entry;
+        externalEvents.push(event);
+      } else if (entry.kind === "turn") {
+        this.externalEntries.push({
+          ...entry,
+          turnIndex: `server-generation.${batch}:${turnCount}`
+        });
+        turnCount += 1;
+      } else if (entry.kind === "message") {
+        messageCount += 1;
+        this.externalEntries.push(entry);
+      }
+    }
+    if (externalEvents.length) mergeMetaEvents(this.sessionKey, externalEvents);
+    recordMetaEvent(this.sessionKey, "external-diagnostics.folded", {
+      interactionId,
+      batch,
+      counts: { turn: turnCount, event: externalEvents.length, message: messageCount }
+    });
+  }
+  /** Hold the ring buffer at its cap, dropping oldest-first. */
+  trim() {
+    while (this.buffer.length > this.maxSnapshots) {
+      this.buffer.shift();
+    }
+  }
+};
+
 // src/components/chat-driver/chat-driver.ts
 var toolResultImages = (result) => {
   if (!result || typeof result !== "object") return void 0;
@@ -4873,17 +5207,6 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.busy = false;
     /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
     this.turnStartedAt = 0;
-    this.pendingInteractions = /* @__PURE__ */ new Map();
-    /**
-     * Live per-interaction contexts (GENC-1390), keyed by interactionId. Created in
-     * `requestInteraction` alongside the pending entry, disposed + removed in
-     * `resolveInteraction`. Non-serialisable (sockets, timers, subscriber sets), so
-     * they live here on the driver — not on the DOM, not in the persisted store — and
-     * therefore survive the element remounts (layout reflow/drag, transcript
-     * re-render) that this feature exists to make harmless. At most one is live at a
-     * time (see the one-interaction-at-a-time guard in `requestInteraction`).
-     */
-    this.interactionContexts = /* @__PURE__ */ new Map();
     /**
      * Tool-declared condensation policies, keyed by tool-call id. Populated by
      * `condenseWhen` (first-wins per call); read by `applyCondensation` before each
@@ -4982,31 +5305,6 @@ var ChatDriver = class _ChatDriver extends EventTarget {
      * doesn't leak forward.
      */
     this.agentReleaseRequested = false;
-    /**
-     * Ring buffer of per-LLM-call snapshots. Cap is configurable via
-     * `chatConfig.agent.maxTurnSnapshots`; older entries drop off as new ones
-     * arrive. See {@link TurnSnapshot} for the captured shape.
-     */
-    this.turnSnapshots = [];
-    /**
-     * `turn` + `message` diagnostic-log entries harvested from an out-of-band source (a resolved
-     * interaction whose widget returned `InteractionResult.diagnostics` — e.g. a server-side
-     * ChatDriver's debug log). `event` entries are NOT kept here — they're folded into the session's
-     * meta-event registry via `mergeMetaEvents` (see `resolveInteraction`) so they inherit fresh host
-     * indices, and reach the log through `getMetaEvents`. Append-only; the host folds these into its
-     * debug log alongside this driver's own timeline. Not cleared here — it lives with the driver
-     * instance, like `turnSnapshots`, so a new chat (fresh driver) starts empty while a compaction
-     * (same instance) keeps it. (GENC-1461.)
-     */
-    this.externalDiagnostics = [];
-    /**
-     * Monotonic count of external-diagnostics batches harvested this driver-lifetime. Namespaces each
-     * batch's re-keyed `turn` entries so distinct server generations in one chat session can't collide
-     * on `turnIndex` in the forward-capture persister (which dedups turns by that key). (GENC-1461.)
-     */
-    this.externalDiagnosticsBatches = 0;
-    /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
-    this.globalTurnIndex = 0;
     /**
      * Aborted by `dispose()` on driver teardown (e.g. an agent-config swap).
      * Threaded into every provider call as `ChatRequestOptions.signal`, so a
@@ -5116,7 +5414,17 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.systemPrompt = systemPrompt;
     this.primerHistory = primerHistory;
     this.maxFoldOperations = maxFoldOperations;
-    this.maxTurnSnapshots = maxTurnSnapshots;
+    this.turnRecorder = new TurnRecorder(sessionKey, maxTurnSnapshots);
+    this.interactions = new InteractionController({
+      sessionKey,
+      activityBus,
+      activeAgentName: () => this.activeAgentName,
+      appendToHistory: (message) => this.appendToHistory(message),
+      patchInteractionMessage: (interactionId, patch) => this.patchInteractionMessage(interactionId, patch),
+      notifyHistoryUpdated: () => this.notifyHistoryUpdated(),
+      emit: (event) => this.dispatchEvent(event),
+      foldDiagnostics: (interactionId, harvested) => this.turnRecorder.foldDiagnostics(interactionId, harvested)
+    });
     if (isObservableAIProviderRegistry(this.providerRegistry)) {
       this.unsubscribeRegistry = this.providerRegistry.subscribe(() => {
         this.resolvedProviderCache.clear();
@@ -5134,7 +5442,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * on to completion or the transport timeout. Called by the host on driver
    * swap and by `OrchestratingDriver.dispose()`. Idempotent.
    *
-   * Deliberately does NOT settle `pendingInteractions` here: dispose is never
+   * Deliberately does NOT settle pending interactions here: dispose is never
    * reached while one is pending. The only host-level dispose is the agent-swap
    * rebuild, which is guarded by `isBusy()` — a pending interaction keeps the
    * tool loop suspended (`busy === true`), so the swap is deferred until the
@@ -5145,8 +5453,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    */
   async dispose() {
     this.lifecycleController.abort(new DOMException("AI assistant driver disposed", "AbortError"));
-    for (const handle of this.interactionContexts.values()) handle.dispose();
-    this.interactionContexts.clear();
+    this.interactions.disposeContexts();
     this.unsubscribeRegistry?.();
     this.unsubscribeRegistry = void 0;
     await this.agentSession.dispose();
@@ -5403,7 +5710,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     this.activeAgentName = config.name;
     this.displayName = config.displayName;
     this.activeAgentLabel = typeof config.displayName === "string" ? config.displayName : config.name;
-    this.debugSnapshotter = config.getDebugSnapshot;
+    this.turnRecorder.setSnapshotter(config.getDebugSnapshot);
     this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
     this.activeProviderInput = config.provider;
     this.activeTemperatureInput = config.temperature;
@@ -5600,93 +5907,21 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * log exporter to show what the LLM saw on each turn — system prompt, tool
    * surface, and agent-supplied state (e.g. a machine snapshot).
    *
-   * Ring-buffered at `MAX_TURN_SNAPSHOTS`; older entries are dropped.
+   * Ring-buffered at `maxTurnSnapshots`; older entries are dropped.
    */
   getTurnSnapshots() {
-    return this.turnSnapshots;
+    return this.turnRecorder.snapshots();
   }
   /**
    * The `turn` + `message` diagnostic-log entries harvested from resolved interactions'
    * `InteractionResult.diagnostics` (e.g. a server-side ChatDriver's collated debug log). The host
    * concatenates these into its own debug log so `downloadDebugLog`/the persisted diagnostics stream
    * include external-engine logs; `event` entries are excluded here because they're merged into the
-   * session's meta-event registry instead (see `resolveInteraction`) and reach the log via
-   * `getMetaEvents`. Opaque, chronologically sorted by the host at assemble time. (GENC-1461.)
+   * session's meta-event registry instead and reach the log via `getMetaEvents`. Opaque,
+   * chronologically sorted by the host at assemble time. (GENC-1461.)
    */
   getExternalDiagnostics() {
-    return this.externalDiagnostics;
-  }
-  /**
-   * Merge a sub-agent's turn snapshots into this driver's buffer so they surface
-   * as `kind:'turn'` entries in the exported debug log. The child runs as a
-   * separate, discarded driver, so its snapshots would otherwise be lost. Each is
-   * re-labelled under the parent turn that activated the sub-agent: the child's
-   * own (numeric) turns become `"<parentTurn>-1"`, `"-2"`, … (1-based, in order);
-   * any already-forwarded grand-child labels (strings) have their leading segment
-   * remapped the same way, so nesting composes (`"5-2"` → `"5-2-1"`).
-   *
-   * Note: two sub-agents invoked in the *same* parent turn share the prefix, so
-   * their labels can repeat — `agentName` on each snapshot disambiguates them.
-   */
-  forwardSubAgentSnapshots(childSnapshots) {
-    if (childSnapshots.length === 0) return;
-    const parentTurn = Math.max(0, this.globalTurnIndex - 1);
-    const ownTurnLabel = /* @__PURE__ */ new Map();
-    let ownPos = 0;
-    for (const snap of childSnapshots) {
-      let turnIndex;
-      if (!snap.turnIndex.includes("-")) {
-        ownPos += 1;
-        turnIndex = `${parentTurn}-${ownPos}`;
-        ownTurnLabel.set(snap.turnIndex, turnIndex);
-      } else {
-        const [lead, ...rest] = snap.turnIndex.split("-");
-        const leadLabel = ownTurnLabel.get(lead) ?? `${parentTurn}-${lead}`;
-        turnIndex = [leadLabel, ...rest].join("-");
-      }
-      this.turnSnapshots.push({ ...snap, turnIndex });
-    }
-    while (this.turnSnapshots.length > this.maxTurnSnapshots) {
-      this.turnSnapshots.shift();
-    }
-  }
-  /**
-   * Push one snapshot to the ring buffer. Called inside `runToolLoop` just
-   * before each LLM call — that's the latest point where the prompt, tool
-   * surface, and agent state line up with what the model is about to see.
-   *
-   * Returns the pushed object so the caller can back-fill what only the response
-   * knows (`usage`). Mutating it after the fact is safe whether or not the ring
-   * buffer has since evicted it — an evicted snapshot is simply no longer exported.
-   */
-  recordTurnSnapshot(resolvedSystemPrompt, temperature, toolChoice, tailContext) {
-    let agentSnapshot;
-    if (this.debugSnapshotter) {
-      try {
-        agentSnapshot = this.debugSnapshotter();
-      } catch (e) {
-        agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
-      }
-    }
-    const turnIndex = String(this.globalTurnIndex);
-    this.globalTurnIndex += 1;
-    const snapshot = {
-      turnIndex,
-      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-      agentName: this.activeAgentName,
-      agentLabel: this.activeAgentLabel,
-      systemPrompt: resolvedSystemPrompt,
-      tailContext,
-      toolNames: this.toolDefinitions.map((t) => t.name),
-      temperature,
-      toolChoice,
-      agentSnapshot
-    };
-    this.turnSnapshots.push(snapshot);
-    if (this.turnSnapshots.length > this.maxTurnSnapshots) {
-      this.turnSnapshots.shift();
-    }
-    return snapshot;
+    return this.turnRecorder.externalDiagnostics();
   }
   /**
    * Set the mid-loop context guard. Its margin is deliberately far smaller than
@@ -5731,6 +5966,10 @@ var ChatDriver = class _ChatDriver extends EventTarget {
     );
     return { estimated, threshold };
   }
+  /**
+   * Optional transform applied to conversation history immediately before each LLM request.
+   * Cleared when `undefined`. Does not alter stored history.
+   */
   setProviderHistoryTransform(transform) {
     this.providerHistoryTransform = transform;
   }
@@ -5884,7 +6123,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * naturally: a grandchild → child → root.
    */
   setHostInteractionRequester(fn) {
-    this.hostInteractionRequester = fn;
+    this.interactions.setHostRequester(fn);
   }
   /**
    * Request a custom UI interaction. Emits a new message with the interaction.
@@ -5906,76 +6145,15 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    *   bubble and/or shows the "Assistant" label.
    */
   async requestInteraction(componentName, data, options) {
-    if (this.hostInteractionRequester) {
-      return this.hostInteractionRequester(componentName, data, options);
-    }
-    if (this.pendingInteractions.size > 0) {
-      throw new Error(
-        "requestInteraction: another user interaction is already in flight. Only one interaction may be active at a time \u2014 sequence them in a single tool handler rather than spawning widgets from parallel sub-agents or parallel tool calls."
-      );
-    }
-    const interactionId = crypto.randomUUID();
-    const chatInputDuringExecution = options?.chatInputDuringExecution;
-    const timeoutMs = options?.timeoutMs;
-    const presentation = options?.presentation;
-    return new Promise((resolve, reject) => {
-      this.pendingInteractions.set(interactionId, {
-        resolve,
-        reject,
-        overrideId: chatInputDuringExecution ? interactionId : void 0,
-        // Resolve the interaction with a timeout result if the user does not
-        // respond in time. `resolveInteraction` runs the same teardown a normal
-        // resolution does (marks the widget read-only, reverts any input
-        // override) and clears any still-pending handle.
-        timeoutHandle: timeoutMs != null ? setTimeout(() => {
-          this.resolveInteraction(interactionId, {
-            status: "timeout",
-            message: `Interaction timed out after ${timeoutMs}ms.`
-          });
-        }, timeoutMs) : void 0
-      });
-      recordMetaEvent(this.sessionKey, "interaction.requested", {
-        interactionId,
-        component: componentName,
-        agent: this.activeAgentName
-      });
-      this.activityBus.publish("interaction-requested", void 0);
-      if (chatInputDuringExecution) {
-        this.dispatchEvent(
-          new CustomEvent("interaction-start", {
-            detail: { interactionId, chatInputDuringExecution }
-          })
-        );
-      }
-      this.interactionContexts.set(interactionId, createInteractionContext(interactionId));
-      this.appendToHistory({
-        role: "assistant",
-        content: "",
-        interaction: {
-          interactionId,
-          componentName,
-          data,
-          ...presentation ? { presentation } : {}
-        }
-      });
-    });
+    return this.interactions.request(componentName, data, options);
   }
   /**
-   * Add external (non-LLM) spend to an interaction's message AFTER it has resolved.
+   * Add external (non-LLM) spend to an interaction's message AFTER it has resolved — for a widget
+   * that resolves early so the assistant stops waiting, then keeps doing paid work on the user's
+   * behalf. `InteractionController.recordExternalCost` explains why the resolution path cannot
+   * carry this.
    *
-   * **Why this exists separately from `resolveInteraction`.** A widget's spend reaches the session
-   * total only through `InteractionResult.costUsd`, which is read exactly once — `resolveInteraction`
-   * does its whole job inside `if (interaction)` and then deletes the entry from
-   * `pendingInteractions`. That is correct for the resolution itself, but it assumes a widget stops
-   * costing money when it resolves, and several deliberately do not: a widget that resolves EARLY so
-   * the assistant stops waiting (options shown, a preview rendered) may stay interactive for minutes
-   * afterwards and do more paid work on the user's behalf. Re-emitting `interaction-completed` does
-   * not help — with the interaction gone from the map the call is a silent no-op — so that spend had
-   * nowhere to go and was simply missing from the figure shown to the user.
-   *
-   * Additive by design: the caller reports a DELTA, not a running total, so repeated calls sum. It
-   * touches only `externalCostUsd`; the recorded `interaction.resolved` payload is left exactly as
-   * the resolution wrote it, because this is not a second resolution and must not read like one.
+   * Additive by design: the caller reports a DELTA, not a running total, so repeated calls sum.
    *
    * Deliberately does NOT require the interaction to be pending, does not resurrect it, and has no
    * loading/turn side effects — this is bookkeeping about a turn that already happened.
@@ -5985,106 +6163,19 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * @returns `true` when the spend was recorded; `false` when it was not — either the value was
    *   not a positive finite amount, or the message is no longer in history (trimmed or condensed
    *   away). A real outcome a caller may want to log rather than a failure to throw on; every
-   *   `false` also records an `interaction.external-cost-dropped` meta event here, so money can
-   *   never disappear without a trace.
+   *   `false` also records an `interaction.external-cost-dropped` meta event, so money can never
+   *   disappear without a trace.
    * @beta
    */
   recordExternalCost(interactionId, costUsd) {
-    const drop = (reason) => {
-      recordMetaEvent(this.sessionKey, "interaction.external-cost-dropped", {
-        interactionId,
-        costUsd,
-        reason
-      });
-      return false;
-    };
-    if (!interactionId) return drop("no interactionId");
-    if (typeof costUsd !== "number" || !Number.isFinite(costUsd) || costUsd <= 0) {
-      return drop("not a positive finite amount");
-    }
-    const idx = this.history.findIndex((m) => m.interaction?.interactionId === interactionId);
-    if (idx === -1) return drop("interaction message no longer in history");
-    this.history[idx] = {
-      ...this.history[idx],
-      externalCostUsd: (this.history[idx].externalCostUsd ?? 0) + costUsd
-    };
-    recordMetaEvent(this.sessionKey, "interaction.external-cost", { interactionId, costUsd });
-    this.dispatchEvent(
-      new CustomEvent("external-cost-recorded", {
-        detail: { interactionId, costUsd }
-      })
-    );
-    return true;
+    return this.interactions.recordExternalCost(interactionId, costUsd);
   }
   /**
    * Resolve a pending interaction. The wrapper component calls this on completion.
    * Marks the interaction message as resolved so it renders read-only on re-render.
    */
   resolveInteraction(interactionId, result) {
-    const interaction = this.pendingInteractions.get(interactionId);
-    if (interaction) {
-      if (interaction.timeoutHandle) clearTimeout(interaction.timeoutHandle);
-      const harvestedDiagnostics = result?.diagnostics;
-      if (Array.isArray(harvestedDiagnostics) && harvestedDiagnostics.length) {
-        const batch = this.externalDiagnosticsBatches += 1;
-        const externalEvents = [];
-        let turnCount = 0;
-        let messageCount = 0;
-        for (const raw of harvestedDiagnostics) {
-          if (!raw || typeof raw !== "object" || typeof raw.kind !== "string") {
-            continue;
-          }
-          const entry = raw;
-          if (entry.kind === "event") {
-            const { kind: _kind, ...event } = entry;
-            externalEvents.push(event);
-          } else if (entry.kind === "turn") {
-            this.externalDiagnostics.push({
-              ...entry,
-              turnIndex: `server-generation.${batch}:${turnCount}`
-            });
-            turnCount += 1;
-          } else if (entry.kind === "message") {
-            messageCount += 1;
-            this.externalDiagnostics.push(entry);
-          }
-        }
-        if (externalEvents.length) mergeMetaEvents(this.sessionKey, externalEvents);
-        recordMetaEvent(this.sessionKey, "external-diagnostics.folded", {
-          interactionId,
-          batch,
-          counts: { turn: turnCount, event: externalEvents.length, message: messageCount }
-        });
-      }
-      const idx = this.history.findIndex((m) => m.interaction?.interactionId === interactionId);
-      if (idx !== -1) {
-        const costUsd = typeof result?.costUsd === "number" && Number.isFinite(result.costUsd) && result.costUsd > 0 ? result.costUsd : void 0;
-        this.history[idx] = {
-          ...this.history[idx],
-          interaction: { ...this.history[idx].interaction, resolved: result },
-          ...costUsd != null ? { externalCostUsd: (this.history[idx].externalCostUsd ?? 0) + costUsd } : {}
-        };
-        this.dispatchEvent(
-          new CustomEvent("history-updated", {
-            detail: this.history
-          })
-        );
-      }
-      if (typeof result?.userMessage === "string" && result.userMessage.trim()) {
-        this.appendToHistory({ role: "synthetic-user", content: result.userMessage });
-      }
-      if (interaction.overrideId) {
-        this.dispatchEvent(new CustomEvent("interaction-stop", { detail: { interactionId } }));
-      }
-      recordMetaEvent(this.sessionKey, "interaction.resolved", { interactionId });
-      this.activityBus.publish("interaction-resolved", void 0);
-      interaction.resolve(result);
-      this.pendingInteractions.delete(interactionId);
-      this.interactionContexts.get(interactionId)?.dispose();
-      this.interactionContexts.delete(interactionId);
-    } else {
-      logger2.warn(`Interaction with ID ${interactionId} not found.`);
-    }
+    this.interactions.resolve(interactionId, result);
   }
   /**
    * The live {@link InteractionContext} for a pending interaction (GENC-1390), or
@@ -6092,23 +6183,17 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    * host) to build the widget's pending `interaction` descriptor.
    */
   getInteractionContext(interactionId) {
-    return this.interactionContexts.get(interactionId)?.context;
+    return this.interactions.context(interactionId);
   }
   /**
-   * Resolve every in-flight interaction with a `'timeout'` result, closing its
-   * widget read-only. Used when a sub-agent that owns the open widget times out:
-   * the widget is parked in *this* driver's map (interactions resolve on the
-   * host, not the child), so cancelling it here unblocks the sub-agent handler
-   * awaiting it. The "one interaction at a time" invariant means there is at
-   * most one.
+   * Replace the history message owning `interactionId`. `false` when it is no longer in history.
+   * Does not announce the change — the interaction paths differ on whether they should.
    */
-  cancelPendingInteractions(message) {
-    for (const interactionId of [...this.pendingInteractions.keys()]) {
-      this.resolveInteraction(interactionId, {
-        status: "timeout",
-        message
-      });
-    }
+  patchInteractionMessage(interactionId, patch) {
+    const idx = this.history.findIndex((m) => m.interaction?.interactionId === interactionId);
+    if (idx === -1) return false;
+    this.history[idx] = patch(this.history[idx]);
+    return true;
   }
   /**
    * Seeds the driver with a prior conversation history so a new component instance
@@ -6116,11 +6201,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
    */
   loadHistory(messages) {
     this.history = [...messages];
-    this.dispatchEvent(
-      new CustomEvent("history-updated", {
-        detail: this.history
-      })
-    );
+    this.notifyHistoryUpdated();
   }
   async sendMessage(userInput, attachments) {
     if (this.busy || !userInput.trim() && !attachments?.length) return { reason: "done" };
@@ -6340,7 +6421,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
           if (winner === "timeout") {
             timedOut = true;
             child.dispose();
-            this.cancelPendingInteractions(`Sub-agent "${name}" timed out after ${timeoutMs}ms.`);
+            this.interactions.cancelAll(`Sub-agent "${name}" timed out after ${timeoutMs}ms.`);
             await runPromise.catch(() => void 0);
           }
         } finally {
@@ -6353,7 +6434,7 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       child.removeEventListener("provider-changed", forwardProviderChanged);
       child.dispose();
       this.dispatchEvent(new CustomEvent("sub-agent-stop", { detail: lifecycleDetail }));
-      this.forwardSubAgentSnapshots(child.getTurnSnapshots());
+      this.turnRecorder.forwardSubAgent(child.getTurnSnapshots());
       const parentName = this.activeAgentName ?? "?";
       const harvested = getMetaEvents(childSessionKey).filter((e) => HARVESTED_SUBAGENT_EVENTS.has(e.type)).map((e) => {
         const existing = e.detail?.subAgent;
@@ -6441,7 +6522,10 @@ var ChatDriver = class _ChatDriver extends EventTarget {
   // ---------------------------------------------------------------------------
   // Tool loop
   // ---------------------------------------------------------------------------
-  // oxlint-disable-next-line complexity
+  // Over both ceilings deliberately: the per-iteration phases share a dozen accumulators, so
+  // splitting threads that state through signatures rather than removing it. `turn-setup.ts`
+  // (docs/code-health.md §11.3) is the intended carve-up.
+  // oxlint-disable-next-line complexity, max-lines-per-function
   async runToolLoop(userInput, attachments, transientPrimer) {
     if (!this.systemPrompt) {
       logger2.warn(
@@ -6597,12 +6681,15 @@ ${EMPTY_RESPONSE_NUDGE}` : "";
 ${tailBody}
 </system-reminder>` : void 0;
       const effectiveToolChoice = resolvedToolChoice ?? (this.isSubAgent ? "required" : void 0);
-      const turnSnapshot = this.recordTurnSnapshot(
+      const turnSnapshot = this.turnRecorder.record({
+        agentName: this.activeAgentName,
+        agentLabel: this.activeAgentLabel,
         systemPrompt,
-        resolvedTemperature,
-        effectiveToolChoice,
-        tailContext
-      );
+        tailContext,
+        toolNames: this.toolDefinitions.map((t) => t.name),
+        temperature: resolvedTemperature,
+        toolChoice: effectiveToolChoice
+      });
       const userInputForCall = currentInput;
       const attachmentsForCall = currentAttachments;
       currentInput = "";
@@ -7104,11 +7191,7 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
           };
         });
         this.history[tcMsgIdx] = { ...tcMsg, toolCalls: annotatedCalls };
-        this.dispatchEvent(
-          new CustomEvent("history-updated", {
-            detail: this.history
-          })
-        );
+        this.notifyHistoryUpdated();
       }
       if (hitUnknownToolLimit) {
         logger2.error(
@@ -7191,6 +7274,10 @@ RECOVERY: this tool failed once \u2014 you may retry it, or take a different val
       } : {}
     };
     this.history = [...this.history, tagged];
+    this.notifyHistoryUpdated();
+  }
+  /** Announce the current history to the host. */
+  notifyHistoryUpdated() {
     this.dispatchEvent(
       new CustomEvent("history-updated", {
         detail: this.history