@genesislcap/ai-assistant 15.25.1 → 15.27.0-agent-log-submit.3

package/dist/esm/components/chat-driver/chat-driver.js

@@ -3,7 +3,6 @@ import { BudgetExhaustedError, ContextOverflowError, ProviderRefusedError, isObs
 import { NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
 import { resolveChatProvider } from '../../config/validate-providers';
 import { clearSession, getMetaEvents, mergeMetaEvents, recordMetaEvent, recordTurnError, recordTurnRetry, } from '../../state/debug-event-log';
-import { createInteractionContext, } from '../../state/interaction-context';
 import { generateSuggestions } from '../../suggestions/generate-suggestions';
 import { applyCondensation, condenseForPersistence, } from '../../utils/condense-history';
 import { estimatePreambleTokens, estimateRequestTokens, } from '../../utils/context-tokens';
@@ -14,7 +13,9 @@ import { messageUsage, sumUsage } from '../../utils/sum-usage';
 import { AgentSession } from '../agent-session/agent-session';
 import { DEFAULT_MAX_FOLD_OPERATIONS, DEFAULT_MAX_TOOL_ITERATIONS, DEFAULT_MAX_TURN_SNAPSHOTS, DEFAULT_MAX_UNKNOWN_TOOL_CALLS, EMPTY_RESPONSE_NUDGE, HANDOFF_TOOL_RESULT_PLACEHOLDER, HARVESTED_SUBAGENT_EVENTS, MALFORMED_CALL_NUDGE, MAX_EMPTY_RESPONSE_RETRIES, MAX_MALFORMED_RETRIES, MAX_SETUP_TRANSPORT_RETRIES, MAX_STALE_TOOL_CALLS, REQUEST_CONTINUATION_TOOL, } from './chat-driver.constants';
 import { FoldController } from './fold-controller';
+import { InteractionController } from './interaction-controller';
 import { TURN_FAILURE_EXITS, turnDone } from './turn-failures';
+import { TurnRecorder } from './turn-recorder';
 /** Re-exported so `from './chat-driver'` keeps resolving these. */
 export { EMPTY_RESPONSE_NUDGE, MALFORMED_CALL_NUDGE, REQUEST_CONTINUATION_TOOL, } from './chat-driver.constants';
 /**
@@ -85,17 +86,6 @@ export 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 = 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 = new Map();
         /**
          * Tool-declared condensation policies, keyed by tool-call id. Populated by
          * `condenseWhen` (first-wins per call); read by `applyCondensation` before each
@@ -194,31 +184,6 @@ export 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
@@ -316,7 +281,17 @@ export 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),
+        });
         // Runtime provider switching: when the host registered an observable
         // registry, drop our memoised provider lookups whenever its mapping/default
         // changes so the next turn re-resolves against the new providers. Resetting
@@ -343,7 +318,7 @@ export 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
@@ -361,13 +336,8 @@ export class ChatDriver extends EventTarget {
             // fires this and forgets (`main.ts`, `void old.dispose()`). Awaiting anything first opened a
             // window in which a disposed driver was still subscribed to the provider registry.
             this.lifecycleController.abort(new DOMException('AI assistant driver disposed', 'AbortError'));
-            // Drop any live interaction contexts (GENC-1390). Normally empty at teardown
-            // (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.
-            for (const handle of this.interactionContexts.values())
-                handle.dispose();
-            this.interactionContexts.clear();
+            // Drop any live interaction contexts (GENC-1390).
+            this.interactions.disposeContexts();
             // Detach from the provider registry so the long-lived registry doesn't pin
             // this driver (and its closure) after teardown. Guard-cleared so a second
             // dispose is a no-op, matching this method's idempotent contract.
@@ -687,7 +657,7 @@ export class ChatDriver extends EventTarget {
         // canonical name when displayName is unset.
         this.activeAgentLabel =
             typeof config.displayName === 'string' ? config.displayName : config.name;
-        this.debugSnapshotter = config.getDebugSnapshot;
+        this.turnRecorder.setSnapshotter(config.getDebugSnapshot);
         this.subAgentsMap = new Map(((_c = config.subAgents) !== null && _c !== void 0 ? _c : []).map((s) => [s.name, s]));
         this.activeProviderInput = config.provider;
         this.activeTemperatureInput = config.temperature;
@@ -911,104 +881,21 @@ export 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) {
-        var _a;
-        if (childSnapshots.length === 0)
-            return;
-        // The activating parent turn = the most recent snapshot this driver recorded
-        // before entering the tool handler that invoked the sub-agent.
-        const parentTurn = Math.max(0, this.globalTurnIndex - 1);
-        const ownTurnLabel = new Map();
-        let ownPos = 0;
-        for (const snap of childSnapshots) {
-            let turnIndex;
-            if (!snap.turnIndex.includes('-')) {
-                // The child's own turn (a bare counter) → number it under the parent turn.
-                ownPos += 1;
-                turnIndex = `${parentTurn}-${ownPos}`;
-                ownTurnLabel.set(snap.turnIndex, turnIndex);
-            }
-            else {
-                // An already-forwarded grand-child label — remap its leading segment.
-                const [lead, ...rest] = snap.turnIndex.split('-');
-                const leadLabel = (_a = ownTurnLabel.get(lead)) !== null && _a !== void 0 ? _a : `${parentTurn}-${lead}`;
-                turnIndex = [leadLabel, ...rest].join('-');
-            }
-            this.turnSnapshots.push(Object.assign(Object.assign({}, 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) {
-                // A snapshotter throwing must not derail the LLM call — capture the
-                // error string in place of the snapshot so the export still shows
-                // *something* happened.
-                agentSnapshot = `<getDebugSnapshot threw: ${e instanceof Error ? e.message : String(e)}>`;
-            }
-        }
-        const turnIndex = String(this.globalTurnIndex);
-        this.globalTurnIndex += 1;
-        const snapshot = {
-            turnIndex,
-            timestamp: 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
@@ -1074,6 +961,10 @@ export class ChatDriver extends EventTarget {
         logger.error(`ChatDriver: ending the turn — the request would fill the context window (~${estimated} of ${limit})`);
         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;
     }
@@ -1237,7 +1128,7 @@ export 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.
@@ -1260,80 +1151,16 @@ export class ChatDriver extends EventTarget {
      */
     requestInteraction(componentName, data, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            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 — 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 === null || options === void 0 ? void 0 : options.chatInputDuringExecution;
-            const timeoutMs = options === null || options === void 0 ? void 0 : options.timeoutMs;
-            const presentation = options === null || options === void 0 ? void 0 : options.presentation;
-            return new Promise((resolve, reject) => {
-                this.pendingInteractions.set(interactionId, {
-                    resolve,
-                    reject,
-                    overrideId: chatInputDuringExecution ? interactionId : undefined,
-                    // 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)
-                        : undefined,
-                });
-                recordMetaEvent(this.sessionKey, 'interaction.requested', {
-                    interactionId,
-                    component: componentName,
-                    agent: this.activeAgentName,
-                });
-                // Signal the park boundary on the activity bus so turn-aware UI can tell
-                // "actively computing" from "parked awaiting the user" — the latter is a
-                // safe window for actions disallowed mid-request (e.g. switching provider
-                // during a long journey step). Paired with `interaction-resolved`.
-                this.activityBus.publish('interaction-requested', undefined);
-                if (chatInputDuringExecution) {
-                    this.dispatchEvent(new CustomEvent('interaction-start', {
-                        detail: { interactionId, chatInputDuringExecution },
-                    }));
-                }
-                // Create the live context (GENC-1390) BEFORE the widget can mount, so the
-                // wrapper finds it when it builds the pending `interaction` descriptor.
-                this.interactionContexts.set(interactionId, createInteractionContext(interactionId));
-                this.appendToHistory({
-                    role: 'assistant',
-                    content: '',
-                    interaction: Object.assign({ 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.
@@ -1343,187 +1170,19 @@ export 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) {
-        var _a;
-        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) => { var _a; return ((_a = m.interaction) === null || _a === void 0 ? void 0 : _a.interactionId) === interactionId; });
-        // The message is gone (trimmed or condensed): the spend is real and already billed, so it is
-        // recorded as dropped rather than silently discarded — an invisible gap in the session total
-        // is exactly what this whole channel exists to close.
-        if (idx === -1)
-            return drop('interaction message no longer in history');
-        this.history[idx] = Object.assign(Object.assign({}, this.history[idx]), { externalCostUsd: ((_a = this.history[idx].externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd });
-        recordMetaEvent(this.sessionKey, 'interaction.external-cost', { interactionId, costUsd });
-        // A NARROW event, deliberately not `history-updated`.
-        //
-        // The host answers `history-updated` by reassigning `messages`, which re-evaluates
-        // `activeInteractionRow` — and the trailing interaction slot renders through a
-        // `repeat(..., { recycle: false })`, so every view in it is disposed and rebuilt regardless of
-        // item identity. That is correct for a PENDING interaction (GENC-1429: a recycled wrapper
-        // carries the previous interaction's truthy `resolved` and swallows the next completion), and
-        // survivable because `buildInteraction` hands a remounted pending widget the same driver-owned
-        // `interactionContext`.
-        //
-        // A RESOLVED one has no such context — `resolveInteraction` disposed and deleted it — so
-        // announcing this on `history-updated` would tear down and blank the very widget that just
-        // reported, in exactly the flow this channel exists for (a user tweaking an option after the
-        // interaction resolved). Bookkeeping about a finished turn must stay invisible, so the host
-        // recomputes its totals from this driver's history and saves, without touching what is
-        // rendered. Reviewer catch on #2474 — confirmed against the layout widget, whose tweak result
-        // went off screen because the rebuild raced the session write that would have restored it.
-        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) {
-        var _a, _b;
-        const interaction = this.pendingInteractions.get(interactionId);
-        if (interaction) {
-            // Clear the timeout so a user resolution doesn't later fire a stale
-            // timeout (and a timeout firing here clears its own already-fired handle).
-            if (interaction.timeoutHandle)
-                clearTimeout(interaction.timeoutHandle);
-            // Harvest any out-of-band diagnostic entries the widget collated (e.g. from a server-side
-            // ChatDriver) so the host's debug log + persisted diagnostics include them. Independent of the
-            // message `idx` below — they describe the widget's own work, not this message.
-            //
-            // The harvested entries carry the SOURCE engine's own index space (0-based turns/events), which
-            // would collide with this host's cursors in the forward-capture persister — turns dedup by
-            // `turnIndex`, events by an `index` high-water mark — so foreign entries get silently dropped
-            // from the persisted stream. Route each kind through the host's own collision-safe machinery,
-            // mirroring how a sub-agent's log is folded in (see `invokeSubAgent`):
-            //   • `event`   → `mergeMetaEvents`, which re-indexes them onto this session's monotonic event
-            //                 counter (clearing the high-water) while preserving their timestamps; they then
-            //                 reach the log via `getMetaEvents` in `buildTimelineEntries`, not this buffer.
-            //   • `turn`    → re-key `turnIndex` to the turn's local position within a per-batch namespace,
-            //                 so turns stay unique even when one interaction folds in several independent
-            //                 server runs that each number their own turns from 0 (a consolidator carries a
-            //                 consolidator-code run AND a table-code run), and never collide with the host's
-            //                 own bare-integer turn keys.
-            //   • `message` → kept as-is; the persister already keys messages by content, so they survive.
-            // TODO(GENC-1461, option 2 / streaming): expose an imperative `appendDiagnostics(entries)` on
-            // the handler context (see buildHandlerContext) that runs this same decomposition as SSE ticks
-            // arrive, so a streaming widget can surface its external engine's log live rather than only at
-            // resolve time. Batch-at-resolve (here) is the current, non-streaming path.
-            const harvestedDiagnostics = result === null || result === void 0 ? void 0 : 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) {
-                    // The harvest is external and typed `unknown[]`, so an element could be a primitive, null,
-                    // or an object without a string `kind`. Guard before reading `.kind` so a malformed entry
-                    // can't throw here (and gets skipped rather than derailing the whole fold).
-                    if (!raw ||
-                        typeof raw !== 'object' ||
-                        typeof raw.kind !== 'string') {
-                        continue;
-                    }
-                    const entry = raw;
-                    if (entry.kind === 'event') {
-                        const { kind: _kind } = entry, event = __rest(entry, ["kind"]);
-                        externalEvents.push(event);
-                    }
-                    else if (entry.kind === 'turn') {
-                        // Local position within THIS harvest, not the source engine's own `turnIndex`: one
-                        // interaction can carry several independent server runs (a consolidator folds in its
-                        // consolidator-code run and its table-code run), each numbering its turns from 0, so
-                        // keying by the source index would collide them. The local position keeps every turn key
-                        // distinct within the batch, so the persister's per-`turnIndex` dedup keeps them all.
-                        this.externalDiagnostics.push(Object.assign(Object.assign({}, entry), { turnIndex: `server-generation.${batch}:${turnCount}` }));
-                        turnCount += 1;
-                    }
-                    else if (entry.kind === 'message') {
-                        messageCount += 1;
-                        this.externalDiagnostics.push(entry);
-                    }
-                    // Any other kind is intentionally dropped, not folded. A sibling's `buildTimelineEntries`
-                    // only ever emits message/turn/event; `meta-snapshot` is host/DOM-owned (latest-wins on
-                    // reassembly, plus its own persister dedup), so folding a foreign one would pollute this
-                    // host's timeline and meta cursor. Restricting to the three real kinds also keeps the
-                    // manifest counts accurate (nothing miscounted as a `message`).
-                }
-                if (externalEvents.length)
-                    mergeMetaEvents(this.sessionKey, externalEvents);
-                // Manifest: one provenance marker for the fold itself — records that an out-of-band engine's
-                // log crossed into this session and how much of each kind, so a regression that silently
-                // drops a generation's diagnostics (e.g. a new path that forgets to thread them across the
-                // boundary) surfaces as a zero/absent manifest rather than only by diffing a download. Also
-                // the natural seed for the streaming PR's open/close bracket. Stamped at resolve, so it
-                // closes the block on the sorted timeline. (GENC-1461.)
-                recordMetaEvent(this.sessionKey, 'external-diagnostics.folded', {
-                    interactionId,
-                    batch,
-                    counts: { turn: turnCount, event: externalEvents.length, message: messageCount },
-                });
-            }
-            const idx = this.history.findIndex((m) => { var _a; return ((_a = m.interaction) === null || _a === void 0 ? void 0 : _a.interactionId) === interactionId; });
-            if (idx !== -1) {
-                // Fold any widget-reported external (non-LLM) cost onto the message, so
-                // the host's `sumCosts` recompute includes it in the session total.
-                // Accumulates defensively in case a widget reports more than once.
-                const costUsd = typeof (result === null || result === void 0 ? void 0 : result.costUsd) === 'number' &&
-                    Number.isFinite(result.costUsd) &&
-                    result.costUsd > 0
-                    ? result.costUsd
-                    : undefined;
-                this.history[idx] = Object.assign(Object.assign(Object.assign({}, this.history[idx]), { interaction: Object.assign(Object.assign({}, this.history[idx].interaction), { resolved: result }) }), (costUsd != null
-                    ? { externalCostUsd: ((_a = this.history[idx].externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd }
-                    : {}));
-                this.dispatchEvent(new CustomEvent('history-updated', {
-                    detail: this.history,
-                }));
-            }
-            // A widget may opt into echoing its outcome on the user's side of the
-            // chat by returning `userMessage`. Appended as a display-only
-            // `'synthetic-user'` message: it is tracked in history (and the debug log)
-            // and rendered like a user message, but transports never serialize it —
-            // the model already learns the outcome from this handler's return value.
-            // Appended before `interaction.resolve` so it precedes the tool result and
-            // any follow-up turn the resumed handler produces.
-            if (typeof (result === null || result === void 0 ? void 0 : 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 });
-            // The park is ending and the loop is about to resume computing — paired
-            // with `interaction-requested`. Fires for every resolution path (user
-            // completion, timeout, cancellation), since all route through here.
-            this.activityBus.publish('interaction-resolved', undefined);
-            interaction.resolve(result);
-            this.pendingInteractions.delete(interactionId);
-            // Tear down the live context on RESOLVE (not on element unmount) — this closes
-            // any sockets/timers the widget parked on it via `onDispose`. (GENC-1390)
-            (_b = this.interactionContexts.get(interactionId)) === null || _b === void 0 ? void 0 : _b.dispose();
-            this.interactionContexts.delete(interactionId);
-        }
-        else {
-            logger.warn(`Interaction with ID ${interactionId} not found.`);
-        }
+        this.interactions.resolve(interactionId, result);
     }
     /**
      * The live {@link InteractionContext} for a pending interaction (GENC-1390), or
@@ -1531,24 +1190,18 @@ export class ChatDriver extends EventTarget {
      * host) to build the widget's pending `interaction` descriptor.
      */
     getInteractionContext(interactionId) {
-        var _a;
-        return (_a = this.interactionContexts.get(interactionId)) === null || _a === void 0 ? void 0 : _a.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) => { var _a; return ((_a = m.interaction) === null || _a === void 0 ? void 0 : _a.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
@@ -1556,9 +1209,7 @@ export class ChatDriver extends EventTarget {
      */
     loadHistory(messages) {
         this.history = [...messages];
-        this.dispatchEvent(new CustomEvent('history-updated', {
-            detail: this.history,
-        }));
+        this.notifyHistoryUpdated();
     }
     sendMessage(userInput, attachments) {
         return __awaiter(this, void 0, void 0, function* () {
@@ -1831,7 +1482,7 @@ export class ChatDriver extends EventTarget {
                             // interaction to close the widget and unblock the child. Without this,
                             // `await runPromise` below would hang forever and the timeout would
                             // never complete (or record `subagent.failed`).
-                            this.cancelPendingInteractions(`Sub-agent "${name}" timed out after ${timeoutMs}ms.`);
+                            this.interactions.cancelAll(`Sub-agent "${name}" timed out after ${timeoutMs}ms.`);
                             yield runPromise.catch(() => undefined);
                         }
                     }
@@ -1860,7 +1511,7 @@ export class ChatDriver extends EventTarget {
                 // the registry, and a crashed sub-agent still leaves its turns/events behind.
                 // Forward the child's per-LLM-call snapshots so they show as `kind:'turn'`
                 // entries in the exported debug log, re-numbered under the activating parent turn.
-                this.forwardSubAgentSnapshots(child.getTurnSnapshots());
+                this.turnRecorder.forwardSubAgent(child.getTurnSnapshots());
                 // Fold the sub-agent's high-value meta events (retries/errors/tool failures —
                 // see HARVESTED_SUBAGENT_EVENTS) into THIS session, preserving their original
                 // timestamps so they interleave within the subagent.started→completed/failed
@@ -2003,7 +1654,10 @@ export 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
     runToolLoop(userInput, attachments, transientPrimer) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
@@ -2251,7 +1905,15 @@ export class ChatDriver extends EventTarget {
                 // on a free-text answer; top-level agents stay 'auto'. (Transports no-op a
                 // force when no tools are advertised.)
                 const effectiveToolChoice = resolvedToolChoice !== null && resolvedToolChoice !== void 0 ? resolvedToolChoice : (this.isSubAgent ? 'required' : undefined);
-                const turnSnapshot = this.recordTurnSnapshot(systemPrompt, resolvedTemperature, effectiveToolChoice, tailContext);
+                const turnSnapshot = this.turnRecorder.record({
+                    agentName: this.activeAgentName,
+                    agentLabel: this.activeAgentLabel,
+                    systemPrompt,
+                    tailContext,
+                    toolNames: this.toolDefinitions.map((t) => t.name),
+                    temperature: resolvedTemperature,
+                    toolChoice: effectiveToolChoice,
+                });
                 // Capture the pending user input, then clear the slots BEFORE the chat
                 // call. `sendMessage` already appended the user message to `this.history`,
                 // so on retries (empty / malformed) we must rely on history alone —
@@ -2307,7 +1969,7 @@ export class ChatDriver extends EventTarget {
                 // oxlint-disable-next-line no-await-in-loop
                 const activeProvider = yield this.resolveProviderForTurn(promptCtx);
                 // Attribute the turn to the tier/model it resolved. Stamped HERE, not inside
-                // `recordTurnSnapshot`: the snapshot is taken before this line runs, so reading
+                // `TurnRecorder.record`: the snapshot is taken before this line runs, so reading
                 // `lastResolved*` there yields the PREVIOUS call's model — wrong on precisely the
                 // turn where an agent's per-state `provider` selector switches tier, which is the
                 // turn a reader is looking for. `model` is refined to the serving model once the
@@ -2909,9 +2571,7 @@ export class ChatDriver extends EventTarget {
                             stale: staleToolIds.has(tc.id) || undefined, subAgentTrace: (_e = executedById.get(tc.id)) === null || _e === void 0 ? void 0 : _e.subAgentTrace });
                     });
                     this.history[tcMsgIdx] = Object.assign(Object.assign({}, tcMsg), { toolCalls: annotatedCalls });
-                    this.dispatchEvent(new CustomEvent('history-updated', {
-                        detail: this.history,
-                    }));
+                    this.notifyHistoryUpdated();
                 }
                 if (hitUnknownToolLimit) {
                     logger.error(`ChatDriver: unknown-tool limit (${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}) reached — stopping`);
@@ -3005,6 +2665,10 @@ export class ChatDriver extends EventTarget {
             }
             : {}));
         this.history = [...this.history, tagged];
+        this.notifyHistoryUpdated();
+    }
+    /** Announce the current history to the host. */
+    notifyHistoryUpdated() {
         this.dispatchEvent(new CustomEvent('history-updated', {
             detail: this.history,
         }));