@genesislcap/ai-assistant 15.19.0 → 15.19.1

package/src/components/chat-driver/chat-driver.ts

@@ -1,3925 +0,0 @@
-import type {
-  AggregateUsage,
-  AIProvider,
-  AIProviderRegistry,
-  AIProviderType,
-  CachePolicy,
-  ChatAttachment,
-  ChatDriverResult,
-  ChatFallback,
-  ChatImageAttachment,
-  ChatMessage,
-  ChatRequestOptions,
-  ChatThinkingPolicy,
-  ChatToolCall,
-  ChatToolChoice,
-  ChatToolDefinition,
-  ChatToolHandlers,
-  CondensePolicy,
-  CondenseTrigger,
-  InteractionRequestOptions,
-  InteractionResult,
-  SubAgentFailureReason,
-  SubAgentRequestOptions,
-  TurnFailureReason,
-} from '@genesislcap/foundation-ai';
-import {
-  BudgetExhaustedError,
-  DEFAULT_BUDGET_EXHAUSTED_MESSAGE,
-  DEFAULT_PROVIDER_REFUSED_MESSAGE,
-  ProviderRefusedError,
-  isObservableAIProviderRegistry,
-  MalformedFunctionCallError,
-  ResponseTruncatedError,
-  vendorTypeOfLabel,
-} from '@genesislcap/foundation-ai';
-import { type ActivityBus, NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
-import type {
-  AgentConfig,
-  CachePolicyInput,
-  ProviderInput,
-  ResponseSchemaInput,
-  SystemPromptContext,
-  SystemPromptInput,
-  TailContextInput,
-  TemperatureInput,
-  ThinkingPolicyInput,
-  ToolChoiceInput,
-  ToolDefinitionsInput,
-  ToolHandlersInput,
-  UnresolvedToolInput,
-} from '../../config/config';
-import { resolveChatProvider } from '../../config/validate-providers';
-import {
-  clearSession,
-  getMetaEvents,
-  type MetaEvent,
-  mergeMetaEvents,
-  type MetaEventType,
-  recordMetaEvent,
-  recordTurnError,
-  recordTurnRetry,
-} from '../../state/debug-event-log';
-import {
-  createInteractionContext,
-  type InteractionContextHandle,
-} from '../../state/interaction-context';
-import type { DiagnosticEntry } from '../../state/persistence/diagnostics';
-import type { InteractionContext } from '../../types/interaction-context';
-import { applyCondensation, type RegisteredCondensePolicy } from '../../utils/condense-history';
-import {
-  applyHistoryCap,
-  buildCompactionSummaryPrompt,
-  findCompactionCut,
-  normalizeForProvider,
-} from '../../utils/history-transform';
-import { logger } from '../../utils/logger';
-import { messageUsage, sumUsage } from '../../utils/sum-usage';
-import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
-import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
-
-/**
- * The `budget` payload carried on a `'budget-exhausted'` {@link ChatDriverResult}.
- * Derived from the type rather than restated so the two cannot drift.
- */
-type BudgetDetail = NonNullable<Extract<ChatDriverResult, { reason: 'done' }>['budget']>;
-/** The `providerRefused` payload on a `'provider-refused'` {@link ChatDriverResult} (GENC-1506). */
-type ProviderRefusedDetail = NonNullable<
-  Extract<ChatDriverResult, { reason: 'done' }>['providerRefused']
->;
-
-/**
- * Lift the reportable facts off a {@link BudgetExhaustedError}, or `undefined`
- * when it carries none.
- *
- * "None" means **no figures AND no attributable vendor** — not merely no
- * figures. Dropping the whole object on a figure-less 402 also dropped
- * `vendorLabel`, which is the authoritative attribution source, and left the
- * element's latch falling back to the driver's last-resolved provider, i.e. the
- * PREVIOUS turn's vendor. A turn-1 Gemini call followed by a turn-2 classifier
- * refused by Anthropic with a figure-less 402 then walled *Gemini* and advised
- * switching to the vendor that had actually run out. Three live shapes reach
- * here with no figures — a bare gateway 402, a code-only body, and the framed
- * err frame whose figures are `null` (which the proxy now prefers over a
- * misleading `0`, so this path is getting more common, not less).
- *
- * The figures alone still decide whether banner copy is composed — see
- * `formatBlockedReason`, which returns `undefined` for a figure-less budget so a
- * host-set explanation survives the latch.
- */
-/**
- * The images on a tool handler's return, or `undefined` if it did not return any.
- *
- * Deliberately strict: `attachments` must be a non-empty array in which EVERY entry carries
- * `kind: 'image'`. A handler returning an ordinary object that happens to have an
- * `attachments` key therefore still JSON-stringifies exactly as it did before, and a
- * half-populated array fails the check rather than silently sending some of the images.
- */
-const toolResultImages = (result: unknown): ChatImageAttachment[] | undefined => {
-  if (!result || typeof result !== 'object') return undefined;
-  const candidate = (result as { attachments?: unknown }).attachments;
-  if (!Array.isArray(candidate) || candidate.length === 0) return undefined;
-  const allImages = candidate.every(
-    (att) => !!att && typeof att === 'object' && (att as { kind?: unknown }).kind === 'image',
-  );
-  return allImages ? (candidate as ChatImageAttachment[]) : undefined;
-};
-
-/**
- * Lift the reportable facts off a {@link ProviderRefusedError} (GENC-1506).
- *
- * Unlike `budgetDetailOf` this is total — it always returns a detail. The budget version can answer
- * `undefined` because its payload is figures the proxy may not have sent; here every field either
- * comes from the transport that was refused (`vendorLabel`, `kind`) or is plainly optional, so there
- * is no "nothing worth reporting" case to model.
- */
-const providerRefusedDetailOf = (e: ProviderRefusedError): ProviderRefusedDetail => ({
-  vendorLabel: e.vendorLabel,
-  kind: e.kind,
-  ...(e.upstreamStatus != null ? { upstreamStatus: e.upstreamStatus } : {}),
-  ...(e.upstreamType ? { upstreamType: e.upstreamType } : {}),
-});
-
-const budgetDetailOf = (e: BudgetExhaustedError): BudgetDetail | undefined => {
-  // The typed vendor is derived from the LABEL, not from `lastResolvedProvider`:
-  // the label comes from the transport that was actually refused, whereas the
-  // last-resolved provider is stale on the classification seam (an orchestrated
-  // turn classifies against the registry default, which this driver may never
-  // have resolved). The proxy's own `vendor` is the fallback for a transport
-  // whose static label no vendor claims (a multiplexing or white-labelled
-  // gateway). Omitted rather than set to `undefined` when neither resolves, so
-  // "we know the vendor" stays testable by presence alone.
-  const vendor = vendorTypeOfLabel(e.vendorLabel) ?? vendorTypeOfLabel(e.serverVendor);
-  if (e.budgetUsd == null && e.spentUsd == null && !vendor) return undefined;
-  return {
-    budgetUsd: e.budgetUsd,
-    spentUsd: e.spentUsd,
-    vendorLabel: e.vendorLabel,
-    ...(vendor ? { vendor } : {}),
-    // Server-known truth the client cannot re-derive, so it rides all the way to
-    // the banner rather than being re-guessed there from registry membership.
-    ...(e.otherVendorAvailable != null ? { otherVendorAvailable: e.otherVendorAvailable } : {}),
-  };
-};
-
-const DEFAULT_MAX_TOOL_ITERATIONS = 50;
-const DEFAULT_MAX_FOLD_OPERATIONS = 5;
-// TODO: dedup system prompts in-memory to allow raising this cap much higher.
-// Each TurnSnapshot stores the full resolved `systemPrompt`, so the buffer's
-// memory cost scales with cap × prompt size — a stable agent repeats a multi-KB
-// prompt every turn. `getDebugLog` already dedups identical consecutive prompts
-// at export time (`<repeated — identical to turn N>`); applying the same dedup
-// at capture time (store the prompt only when it changes, back-reference
-// otherwise) would make snapshots nearly as cheap as meta events and let this
-// cap reach thousands for full-session capture without the memory blowup.
-const DEFAULT_MAX_TURN_SNAPSHOTS = 400;
-const DEFAULT_MAX_UNKNOWN_TOOL_CALLS = 5;
-// Stale tools (advertised in an earlier state, retired now) and fold-hidden tools are
-// self-correcting — the model drops them once guided — so they get a higher loop-protection
-// ceiling than hallucinated names: a few legitimate stale calls across state transitions must
-// not prematurely end the turn. Still bounded so a genuinely stuck loop terminates.
-const MAX_STALE_TOOL_CALLS = DEFAULT_MAX_UNKNOWN_TOOL_CALLS * 2;
-// Gemini in particular emits short bursts of MALFORMED_FUNCTION_CALL; allow more CONSECUTIVE
-// retries. These counters reset on any productive response, so this is a consecutive-failure
-// ceiling, not a per-turn total.
-const MAX_MALFORMED_RETRIES = 5;
-const MAX_EMPTY_RESPONSE_RETRIES = 3;
-// Transient throws while building the per-turn tool surface or calling the provider retry the
-// SAME iteration up to this many times before propagating, rather than tearing down the turn.
-const MAX_SETUP_TRANSPORT_RETRIES = 3;
-const SUGGESTIONS_HISTORY_WINDOW = 8;
-
-/**
- * Sub-agent meta events worth folding into the parent's debug timeline: the
- * per-attempt and per-failure signals that do NOT otherwise surface in the
- * sub-agent's (now hoisted) messages — a retried-away malformed/empty attempt
- * produces no message, and the stale-vs-hallucinated/streak diagnostics live only
- * on the event. High-volume, message-derivable events (turn.start/turn.end,
- * provider.selected, context.updated) are intentionally excluded: read the
- * sub-agent's hoisted messages for model/tokens/cost and turn-by-turn activity.
- * See `ChatDriver.invokeSubAgent`.
- */
-const HARVESTED_SUBAGENT_EVENTS: ReadonlySet<MetaEventType> = new Set([
-  'turn.retry',
-  'turn.error',
-  'tool.failed',
-  'tool.unresolved',
-]);
-
-/** Name reserved for the cross-agent handoff tool — injected by OrchestratingDriver. */
-export const REQUEST_CONTINUATION_TOOL = 'request_continuation';
-
-/** Paired in history for each `request_continuation` so tool_calls stay balanced for the provider. */
-const HANDOFF_TOOL_RESULT_PLACEHOLDER =
-  'Handoff to another specialist — routing continues on the next turn.';
-
-/**
- * Event emitted when the chat history is updated (new message appended).
- *
- * @beta
- */
-export type ChatHistoryUpdatedEvent = CustomEvent<ReadonlyArray<ChatMessage>>;
-
-/**
- * One captured frame of what the LLM saw on a single tool-loop iteration.
- * The driver records these as a ring buffer (cap: configurable via
- * `chatConfig.agent.maxTurnSnapshots`, default 400) so the export log can show,
- * per turn: which agent was active, the resolved system prompt, the tool names
- * visible to the LLM, and any agent-supplied debug snapshot (e.g. machine
- * state for stateful agents).
- *
- * @beta
- */
-export interface TurnSnapshot {
-  /**
-   * Turn identifier, always a string. A driver's own turns are the bare counter
-   * (`"0"`, `"1"`, … — monotonic, does not reset on agent swap). Turns forwarded
-   * up from a sub-agent are re-labelled under the parent turn that activated them
-   * — a sub-agent invoked on parent turn 5 contributes `"5-1"`, `"5-2"`, …, and a
-   * nested sub-agent on `"5-2"` contributes `"5-2-1"`, …. See
-   * `forwardSubAgentSnapshots`.
-   */
-  turnIndex: string;
-  /** ISO timestamp captured just before the LLM call. */
-  timestamp: string;
-  /** Name of the agent active when this LLM call ran. */
-  agentName?: string;
-  /**
-   * The agent's resolved system prompt sent to the LLM, verbatim. NOTE: this is
-   * now the *bare* prompt — the fold-surface suffix and the malformed/empty retry
-   * nudge no longer mutate it (they kept it byte-unstable and busted prompt
-   * caching), so they moved to {@link TurnSnapshot.tailContext}. To reconstruct
-   * exactly what the model saw, read both fields.
-   */
-  systemPrompt?: string;
-  /**
-   * The framed `<system-reminder>` tail appended to the final user turn for this
-   * call, verbatim — never part of stored history, so this snapshot is the only
-   * record of it. Carries the framework's volatile additions (fold suffix, retry
-   * nudge) and the agent's per-turn `tailContext` (e.g. current file spec, live
-   * diagnostics). Undefined when the tail was empty (the normal case).
-   */
-  tailContext?: string;
-  /** Tool names sent to the LLM, in order — definitions are static per name so names alone suffice. */
-  toolNames: string[];
-  /**
-   * Normalized `0`–`1` sampling temperature in effect for this call, if the
-   * agent (or its current state) configured one. Undefined → provider/model
-   * default. Mirrors the value resolved from `BaseAgentConfig.temperature`.
-   */
-  temperature?: number;
-  /**
-   * Tool-call mode actually sent to the provider this call — the effective
-   * value, including the sub-agent `'required'` default. Undefined → `'auto'`.
-   * Mirrors the value resolved from `BaseAgentConfig.toolChoice`.
-   */
-  toolChoice?: ChatToolChoice;
-  /**
-   * Per-turn display label resolved from the agent's `displayName`, e.g.
-   * "Guided Booking (Counterparties)". `agentName` stays as the canonical
-   * identity used for routing/filtering.
-   */
-  agentLabel?: string;
-  /** Agent-supplied snapshot — machine state/context for stateful agents, undefined otherwise. */
-  agentSnapshot?: unknown;
-  /**
-   * Concrete model that ran this call (e.g. `'claude-sonnet-4-6'`) — the serving model
-   * where the provider reports one, else the model the resolved tier was configured
-   * with. Undefined when the provider exposes no `getStatus` and the transport stamped
-   * nothing.
-   *
-   * Recorded per call, so an agent whose `provider` selector varies by state (a tier
-   * switch between steps of a flow) has each step attributed to the model that actually
-   * ran it — without the reader having to join the turn to the message after it, which
-   * is impossible for a call that produced no message.
-   */
-  model?: string;
-  /**
-   * Registry slot the provider resolved under for this call — a tier name like
-   * `'high'`/`'low'`, or the registry default's name. Kept alongside {@link
-   * TurnSnapshot.model} because they answer different questions: the slot is what the
-   * agent asked for, the model is what served it, and repointing a slot at a new model
-   * mid-session is only visible when both are recorded.
-   */
-  providerName?: string;
-  /** Vendor behind the resolved slot (`'anthropic'`, `'gemini'`, …), when the provider reports it. */
-  provider?: AIProviderType;
-  /**
-   * What this one LLM call cost — the four disjoint token buckets plus USD, derived
-   * from the response's usage by `messageUsage`. Back-filled when the response lands
-   * (the rest of the snapshot is captured *before* the call), so it is `undefined`
-   * while the call is in flight, on providers that report no usage, and on a call that
-   * threw rather than returning — a malformed-call/truncation/402 error carries no usage
-   * block, so any tokens the provider billed for it are not recoverable here.
-   *
-   * A snapshot is one **model call**, not one user turn: every tool-loop iteration and
-   * every retried attempt records its own. That makes this the only record of spend on
-   * an attempt that produced no message — a blank or refused response is billed and
-   * then discarded (see the empty-response retries), so summing the transcript alone
-   * under-reports the turn.
-   *
-   * For a call that DID produce a message, this is the same money as that message's
-   * `cost`/token fields, not additional money — never add turn usage to message usage.
-   */
-  usage?: AggregateUsage;
-}
-
-interface FoldStackFrame {
-  foldName: string;
-  previousDefinitions: ChatToolDefinition[];
-  previousHandlers: ChatToolHandlers;
-}
-
-/**
- * Construction-time configuration for {@link ChatDriver}. Everything except the provider
- * registry is optional — most fields are also settable per-agent via `applyAgent`, so a
- * bare `new ChatDriver(registry)` is valid. Mirrors the `(registry, options)` shape of
- * `OrchestratingDriver`.
- *
- * @beta
- */
-export interface ChatDriverConfig {
-  /** Initial tool handlers (static map or per-turn factory). Default `{}`. */
-  toolHandlers?: ToolHandlersInput;
-  /** Initial tool definitions (static array or per-turn factory). Default `[]`. */
-  toolDefinitions?: ToolDefinitionsInput;
-  /** Initial system prompt (string or per-turn resolver). */
-  systemPrompt?: SystemPromptInput;
-  /** Primer history prepended to the conversation. */
-  primerHistory?: ChatMessage[];
-  /** Hard cap on tool-loop iterations. Default `50`. */
-  maxToolIterations?: number;
-  /** Hard cap on fold operations. Default `5`. */
-  maxFoldOperations?: number;
-  /**
-   * Collapse `condenseWhen` payloads in batches of this many model-calls rather than as
-   * soon as each trigger fires. A positive integer; decimals are floored and anything
-   * below `1` becomes `1`. Default `1` — collapse immediately, the historical behaviour.
-   *
-   * Condensation rewrites history in place, so collapsing continuously breaks the
-   * provider's prompt cache on nearly every call of a re-read loop. Raising this trades
-   * up to that many calls' worth of extra context for one cache break per batch.
-   */
-  condenseBatchCalls?: number;
-  /** Ring-buffer size for per-turn snapshots. Default `400`. */
-  maxTurnSnapshots?: number;
-  /** Session identity used to file meta events onto the shared debug-log timeline. */
-  sessionKey?: string;
-  /**
-   * Activity bus for lifecycle/halo/tool-loop events. Injected by the browser host
-   * (the shared cross-tab singleton); omitted off-browser (Node, tests, headless), where
-   * it defaults to {@link NOOP_ACTIVITY_BUS} so no `BroadcastChannel` is ever opened.
-   */
-  activityBus?: ActivityBus;
-  /**
-   * Transcript copy appended when the AI-spend budget wall is hit (GENC-1464),
-   * used VERBATIM — set it only to own the copy entirely (white-labelling).
-   * When unset, the driver composes the bubble per wall: the neutral
-   * `DEFAULT_BUDGET_EXHAUSTED_MESSAGE`, upgraded with "switch to another AI
-   * provider" advice only when the 402's `otherVendorAvailable` positively says
-   * another metered vendor still has headroom — the same rule the blocked
-   * banner applies, so the two surfaces can no longer contradict each other.
-   *
-   * The assistant element already lets a host override the blocked **banner**
-   * via `setBlocked(true, reason)`; without this the transcript **bubble** stayed
-   * on the default, so a white-labelled host got its own copy in the banner and
-   * the shipped default directly below it. Passing the same effective copy here
-   * keeps the two surfaces saying one thing.
-   *
-   * Deliberately a driver-config field rather than something read off a chat
-   * config: `ChatDriver` has no `chatConfig` and is used standalone (see
-   * `chat-driver-node`), so threading one in would be a much larger and less
-   * reversible change.
-   */
-  budgetExhaustedMessage?: string;
-
-  /**
-   * Overrides the transcript sentence shown when the upstream PROVIDER refuses the account
-   * (GENC-1506) — see `DEFAULT_PROVIDER_REFUSED_MESSAGE`.
-   *
-   * Separate from `budgetExhaustedMessage` because the two conditions are separate: ours is a spend
-   * cap a host administrator can raise, this is the vendor declining to serve us at all. A host that
-   * white-labels one will usually want to white-label both, but conflating them into one field would
-   * force identical copy on two situations with different remedies.
-   *
-   * Rarely needed: unlike the budget default, the shipped sentence names no vendor and no Genesis, so
-   * it is already safe for a white-labelled deployment.
-   */
-  providerRefusedMessage?: string;
-}
-
-/**
- * Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.
- * Owned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.
- *
- * Dispatches `'history-updated'` events on itself so the owning element can observe changes.
- *
- * @fires history-updated - Fired whenever the in-memory chat history changes (append, tool loop, interaction resolution, post-resolve external cost) with the full history snapshot. detail: `ReadonlyArray<ChatMessage>`
- *
- * @beta
- */
-export class ChatDriver extends EventTarget implements AiDriver {
-  private history: ChatMessage[] = [];
-  private busy = false;
-  /** Epoch ms when the current turn loop began — drives the `turn.end` duration. */
-  private turnStartedAt = 0;
-  private pendingInteractions = new Map<
-    string,
-    {
-      resolve: (value: any) => void;
-      reject: (reason?: any) => void;
-      /** Present when the call requested a chat-input override. */
-      overrideId?: string;
-      /** Present when the call set `timeoutMs`; cleared on resolution. */
-      timeoutHandle?: ReturnType<typeof setTimeout>;
-    }
-  >();
-  /**
-   * 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`).
-   */
-  private interactionContexts = new Map<string, InteractionContextHandle>();
-
-  private systemPrompt?: SystemPromptInput;
-  /**
-   * Resolved tool definitions visible to the LLM. Folds mutate this in place
-   * (push/pop on open/close). When `toolDefinitionsFactory` is set, this is
-   * overwritten each tool-loop iteration with the factory's output.
-   */
-  private toolDefinitions: ChatToolDefinition[];
-  /**
-   * Optional dynamic-tools source. When set, called each tool-loop iteration
-   * to recompute `toolDefinitions` before the LLM call. `defineStatefulAgent`
-   * forbids folds when this is set, so the fold-mutation path is unreachable
-   * in that case.
-   */
-  private toolDefinitionsFactory?: (
-    ctx: SystemPromptContext,
-  ) => ChatToolDefinition[] | Promise<ChatToolDefinition[]>;
-  /**
-   * Resolved tool handler map used for dispatch. When `toolHandlersFactory` is
-   * set, this is overwritten each tool-loop iteration with the factory's output
-   * — keeping it in lockstep with `toolDefinitions` so handlers don't have to
-   * defend themselves against being dispatched in states where their tool
-   * isn't advertised. Folds mutate this in place; `defineStatefulAgent`
-   * forbids folds when a factory is set, so the fold-mutation path is
-   * unreachable in that case.
-   */
-  private toolHandlers: ChatToolHandlers;
-  /**
-   * Optional per-turn handler-map source. Mirrors `toolDefinitionsFactory` so
-   * the LLM-visible tools and the dispatchable handlers can be narrowed in
-   * lockstep. Resolved each tool-loop iteration before the LLM call.
-   */
-  private toolHandlersFactory?: (
-    ctx: SystemPromptContext,
-  ) => ChatToolHandlers | Promise<ChatToolHandlers>;
-  private primerHistory?: ChatMessage[];
-  private activeAgentName?: string;
-  /**
-   * Per-turn display label resolved from the agent's `displayName`. Stamped
-   * onto outgoing messages and turn snapshots for UX; `activeAgentName` stays
-   * stable for routing/history-transform identity matching.
-   */
-  private activeAgentLabel?: string;
-  private displayName?: SystemPromptInput;
-  /**
-   * When set, `requestInteraction` delegates to this callback instead of using
-   * this driver's own pending map. Wired by `invokeSubAgent` so a sub-agent's
-   * widget renders in — and resolves through — the parent (ultimately the
-   * root) driver, where the main UI is listening.
-   */
-  private hostInteractionRequester?: <T>(
-    componentName: string,
-    data: any,
-    options?: InteractionRequestOptions,
-  ) => Promise<T>;
-  /**
-   * When set (e.g. by OrchestratingDriver), applied only to the conversation slice
-   * sent to the model — stored `history` stays unchanged for UI and logging.
-   */
-  private providerHistoryTransform?: (history: ChatMessage[]) => ChatMessage[];
-  /**
-   * Tool-declared condensation policies, keyed by tool-call id. Populated by
-   * `condenseWhen` (first-wins per call); read by `applyCondensation` before each
-   * provider call to collapse stale payloads from the model-bound history only.
-   * Accumulates across agents on a shared driver (a superseded read collapses no
-   * matter which agent made it) and is never cleared — it dies with the driver.
-   */
-  private readonly condensePolicies = new Map<string, RegisteredCondensePolicy>();
-  /**
-   * Monotonic model-call counter for the driver's whole lifetime — the age clock
-   * for `condenseWhen({ on: { kind: 'age' } })`. The per-`sendMessage` `iterations`
-   * loop counter resets to 0 every turn, so it can only measure age WITHIN a
-   * single turn; this never resets, so `age` counts model-calls since the result
-   * appeared across turn boundaries (each short turn still advances it ≥ 1).
-   * Bumped once per tool-loop iteration (provider call).
-   */
-  private modelCallSeq = 0;
-  /**
-   * Monotonic turn counter — the `turnEnd` clock. Bumped once per `sendMessage`
-   * (a user turn; NOT per handoff continuation, which is the same request), never
-   * reset. `turnEnd` collapses a payload once `turnSeq` exceeds the turn it was
-   * created in.
-   */
-  private turnSeq = 0;
-  /**
-   * Monotonic agent-activation counter — the `agentEnd` clock. Advances when the
-   * active flow ends: a swap to a different-named agent (`applyAgent`) OR an
-   * explicit `releaseAgent` / `completeSubAgent`. A stateful agent re-resolving
-   * the same name across turns keeps one activation. `agentEnd` fires for a
-   * payload once a LATER activation is current (`callActivation < currentActivation`)
-   * — so a re-run of a released agent gets a fresh activation and is NOT
-   * collapsed until IT ends.
-   */
-  private currentActivation = 0;
-  /**
-   * Monotonic phase-epoch counter — the `phaseEnd` clock. Advanced by the
-   * handler-context `endPhase()` (an app-declared phase boundary within one
-   * activation), never reset. Unlike `currentActivation` it is NOT tied to agent
-   * swaps or releases — it ticks only when the agent itself declares a phase
-   * done. `phaseEnd` fires for a payload once a LATER epoch is current
-   * (`callPhaseEpoch < currentPhaseEpoch`), with an `agentEnd` backstop.
-   */
-  private currentPhaseEpoch = 0;
-
-  /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
-  private foldStack: FoldStackFrame[] = [];
-  /** Consecutive fold open/close ops without a real tool call. Reset on real tool execution. */
-  private consecutiveFoldOps = 0;
-  /** Consecutive unknown-tool calls without a real tool call. Reset on real tool execution. */
-  private consecutiveUnknownToolCalls = 0;
-  /**
-   * Distinct unknown-tool names seen in the current consecutive streak — stamped
-   * onto the `unknown-tool-limit` turn.error so a triager knows which tools were
-   * hallucinated. Reset alongside `consecutiveUnknownToolCalls`.
-   */
-  private readonly recentUnknownToolNames = new Set<string>();
-  /**
-   * Union of every tool name advertised at any point during the current agent
-   * activation. Lets the unknown-tool path tell a *stale* call (a real tool from
-   * an earlier state, now retired — or one an open exclusive fold is hiding)
-   * apart from a *hallucinated* one. Reset on agent swap in `applyAgent`.
-   */
-  private readonly everSeenToolNames = new Set<string>();
-  /**
-   * Subset of the current unknown-tool streak that was stale (previously
-   * available) rather than hallucinated — surfaced separately on the
-   * `unknown-tool-limit` turn.error so triage can tell a state/prompt-design
-   * problem from a model that's inventing tools. Reset alongside
-   * `recentUnknownToolNames`.
-   */
-  private readonly recentStaleToolNames = new Set<string>();
-  private readonly maxFoldOperations: number;
-
-  /** Sub-agents declared on the active agent config, keyed by name. */
-  private subAgentsMap: Map<string, AgentConfig> = new Map();
-  /**
-   * Set by `completeSubAgent` inside a sub-agent tool handler. Checked at the
-   * same point in the loop as `REQUEST_CONTINUATION_TOOL` — after tool results
-   * are appended — so the exit path mirrors the system-call pattern.
-   * `undefined` means the loop has not been stopped early.
-   */
-  private subAgentCompletion: { result: unknown } | undefined;
-  /**
-   * True when this driver runs as a child sub-agent (created by a parent
-   * driver's `invokeSubAgent`). Sub-agents force tool use every turn so a turn
-   * can only end via their completion tool, and on any non-completion exit they
-   * record a typed `SubAgentFailureReason` instead of appending a
-   * user-facing message — the parent decides how to surface the failure.
-   */
-  private isSubAgent = false;
-  /**
-   * Set when a sub-agent's tool loop ends without `completeSubAgent` being
-   * called. Read by the parent's `invokeSubAgent` to build the `{ ok: false }`
-   * branch of `requestSubAgent`. Only ever set when `isSubAgent` is true.
-   *
-   * `budget` rides along on a `'budget_exhausted'` failure so the parent inherits
-   * the child's ATTRIBUTION, not just the fact of a wall — see
-   * `budgetWallDetail`.
-   */
-  private subAgentFailure:
-    | {
-        reason: SubAgentFailureReason;
-        budget?: BudgetDetail;
-        /**
-         * The refusing vendor and kind, when a child hit the PROVIDER wall (GENC-1506).
-         *
-         * Carried for the same reason `budget` is: the child is a **separate driver instance**, so
-         * nothing it sets on itself is visible to the parent. Without this the parent could report
-         * `provider-refused` but not say which vendor or which kind — losing the only signal that
-         * distinguishes "top up the account" from "rotate the key", since the user copy is cause-free.
-         */
-        providerRefused?: ProviderRefusedDetail;
-      }
-    | undefined;
-  /**
-   * Set by `releaseAgent` inside a top-level tool handler — typically a stateful
-   * agent's terminal-state handler signalling that its flow is complete and the
-   * auto-pin lock can release. Checked by the orchestrator after `sendMessage`
-   * returns; the orchestrator fires `onDeactivate` and clears the pin.
-   *
-   * Reset at the start of each `sendMessage` so a release from a previous turn
-   * doesn't leak forward.
-   */
-  private 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.
-   */
-  private turnSnapshots: TurnSnapshot[] = [];
-  /**
-   * `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.)
-   */
-  private readonly externalDiagnostics: DiagnosticEntry[] = [];
-  /**
-   * 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.)
-   */
-  private externalDiagnosticsBatches = 0;
-  /** Monotonic counter that survives agent swaps — useful for cross-referencing with history. */
-  private globalTurnIndex = 0;
-  /** Captured from `applyAgent` so we don't store the whole `AgentConfig`. */
-  private debugSnapshotter?: () => unknown;
-  private readonly maxTurnSnapshots: number;
-
-  /**
-   * Aborted by `dispose()` on driver teardown (e.g. an agent-config swap).
-   * Threaded into every provider call as `ChatRequestOptions.signal`, so a
-   * disposed driver's in-flight LLM request is cancelled instead of running on
-   * to completion or the transport timeout. Also passed to prompt/tool
-   * factories via `SystemPromptContext.signal`.
-   */
-  private readonly lifecycleController = new AbortController();
-
-  /**
-   * Per-turn abort controller, reset at the start of every turn by `beginTurn`.
-   * Aborted by `cancel()` (user stop) and chained to `lifecycleController` so a
-   * driver dispose also ends the current turn. Its signal — not the lifecycle
-   * one — is what reaches the provider call, so a turn can be cancelled without
-   * bricking the driver for the next message.
-   */
-  private turnController = new AbortController();
-  /** True when the current turn was stopped via `cancel()` (vs a dispose). Drives the "Stopped." marker. */
-  private turnCancelled = false;
-  /** Detaches the lifecycle→turn abort link at turn end; set by `beginTurn`. */
-  private unlinkLifecycleFromTurn?: () => void;
-
-  /**
-   * Active agent's provider selector (static name or per-turn resolver).
-   * `undefined` means "use the registry default".
-   */
-  private activeProviderInput?: ProviderInput;
-  /**
-   * Active agent's temperature selector (static number or per-turn resolver),
-   * normalized to `0`–`1`. `undefined` means "use the provider/model default".
-   */
-  private activeTemperatureInput?: TemperatureInput;
-  /**
-   * Active agent's tool-call mode selector (static value or per-turn resolver).
-   * `undefined` falls back to the per-turn default (sub-agents force a tool
-   * call; top-level turns are `'auto'`).
-   */
-  private activeToolChoiceInput?: ToolChoiceInput;
-  /**
-   * Active agent's prompt-cache policy selector (static value or per-turn resolver).
-   * `undefined` requests no caching (equivalent to `{ scope: 'default' }`).
-   */
-  private activeCachePolicyInput?: CachePolicyInput;
-  /**
-   * Active agent's extended-thinking selector (static value or per-turn resolver). `undefined` —
-   * unset, or returned by the resolver — leaves the model on its own default posture, which is
-   * neither uniformly on nor off, so an agent that never sets this is unaffected by the option.
-   */
-  private activeThinkingPolicyInput?: ThinkingPolicyInput;
-  /**
-   * Active agent's tail-context selector (static value or per-turn resolver). The driver frames
-   * the resolved string in a `<system-reminder>` marker and injects it at the message tail.
-   */
-  private activeTailContextInput?: TailContextInput;
-  /**
-   * Active agent's structured-output schema selector (static value or per-turn resolver).
-   * When it resolves to a schema, the model's final answer is constrained to it this turn.
-   */
-  private activeResponseSchemaInput?: ResponseSchemaInput;
-  /**
-   * Active agent's refusal-fallback chain (static). Passed through to the provider so a refused
-   * turn (e.g. Fable 5) is re-run on the next model server-side.
-   */
-  private activeFallbacks?: ChatFallback[];
-  /**
-   * Active agent's unresolved-tool hook, captured from `applyAgent`. Consulted
-   * only when a tool call cannot be dispatched (a stale or hallucinated name);
-   * `undefined` keeps the framework's default messages. See
-   * `resolveUnresolvedToolContent`.
-   */
-  private activeOnUnresolvedTool?: UnresolvedToolInput;
-  /**
-   * Caches validated provider lookups per name within the current agent. Cleared
-   * by `applyAgent` so each new agent's static/function-resolved names are
-   * validated fresh.
-   */
-  private resolvedProviderCache = new Map<string, AIProvider>();
-  /** Last successfully resolved provider name — drives `getActiveProviderName`. */
-  private lastResolvedProviderName?: string;
-  /** Last dispatched `provider-changed` name; avoids duplicate events on stable turns. */
-  private lastDispatchedProviderName?: string;
-  /**
-   * Concrete model id of the provider resolved for the current turn, read from
-   * its `getStatus()` and stamped onto the resulting assistant message so the
-   * debug log carries per-message model lineage. Re-resolved each turn in
-   * `resolveProviderForTurn`.
-   */
-  private lastResolvedModel?: string;
-  /**
-   * Vendor id from the provider's `getStatus()` for the current turn (e.g.
-   * `'anthropic'`, `'gemini'`). Stamped onto assistant messages alongside
-   * `lastResolvedModel`.
-   */
-  private lastResolvedProvider?: AIProviderType;
-  /**
-   * Memoised `name → getStatus()` lookups, so per-turn resolution doesn't
-   * re-await `getStatus()` every turn. Cleared (with `resolvedProviderCache`) on
-   * an observable-registry change, so a model swapped behind a stable name is
-   * picked up on the next turn.
-   */
-  private resolvedStatusCache = new Map<string, { model?: string; provider?: AIProviderType }>();
-  /**
-   * Unsubscribe handle for the provider-registry change listener (only set when
-   * the injected registry is observable). Called in `dispose` so the long-lived
-   * registry doesn't retain this driver — see the constructor and the sub-agent
-   * teardown in `runSubAgent`.
-   */
-  private unsubscribeRegistry?: () => void;
-
-  /** Hard cap on tool-loop iterations. */
-  private readonly maxToolIterations: number;
-  /** Model-calls per condensation batch; `1` collapses as soon as a trigger fires. */
-  private readonly condenseBatchCalls: number;
-  /** Session identity used to file meta events onto the shared debug-log timeline. */
-  private readonly sessionKey: string;
-  /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
-  private readonly activityBus: ActivityBus;
-  /**
-   * Host override for the budget-wall transcript copy, used verbatim — see
-   * `ChatDriverConfig.budgetExhaustedMessage`. `undefined` means no override,
-   * and the bubble is composed per wall by {@link ChatDriver.budgetExhaustedBubble}.
-   */
-  private readonly budgetExhaustedMessageOverride?: string;
-
-  /**
-   * Host override for the provider-refusal sentence, from
-   * `ChatDriverConfig.providerRefusedMessage`. `undefined` means no override, so the shipped default
-   * is used verbatim.
-   */
-  private readonly providerRefusedMessageOverride?: string;
-
-  /**
-   * A provider refusal was observed this turn, so the tool loop must not call the model again
-   * (GENC-1506).
-   *
-   * Exists for the SUB-AGENT path only, exactly like `budgetExhaustedThisTurn`: this driver's own
-   * refusal returns straight out of the catch, whereas a child's refusal reaches the parent as a tool
-   * result, and without this flag the loop would issue another call into the same wall — N batched
-   * children costing N doomed calls plus a doomed parent one.
-   */
-  private providerRefusedThisTurn = false;
-
-  /** The refusal detail latched off a sub-agent's failure, for the parent's own result. */
-  private providerRefusedDetail?: ProviderRefusedDetail;
-  /**
-   * Set the moment a budget wall is observed anywhere in this turn — this
-   * driver's own 402, or a sub-agent's (which surfaces here only as a
-   * `'budget_exhausted'` tool result). Read at the top of the tool loop to end
-   * the turn before issuing another model call that would hit the same wall.
-   * Reset per turn alongside the other per-turn counters.
-   */
-  private budgetExhaustedThisTurn = false;
-  /**
-   * The refusing vendor's own attribution for the wall `budgetExhaustedThisTurn`
-   * records, when it was knowable. Kept SEPARATE from the flag rather than
-   * replacing it: a figure-less 402 from a transport no vendor claims yields no
-   * detail at all (`budgetDetailOf` returns `undefined`), and folding the two
-   * would make that case stop ending the turn.
-   *
-   * It matters most for a sub-agent's wall. The child can sit on a different
-   * vendor from its parent — `applyAgent` reads `config.provider` — so without
-   * this the parent's short-circuit reports `lastResolvedProvider`, i.e. the one
-   * vendor that did NOT refuse. Under a mixed registry that walls Gemini because
-   * an Anthropic child 402'd, and if those are the only two reachable vendors the
-   * host then derives `blocked` and locks a composer that still had headroom.
-   */
-  private budgetWallDetail?: BudgetDetail;
-  /**
-   * Whether this turn's budget wall came from a SUB-AGENT rather than this
-   * driver's own request. Decides whether `lastResolvedProvider` is a valid
-   * attribution fallback: for an own wall it is the refusing vendor, for a
-   * child's wall it is the parent's vendor — the one known NOT to have refused.
-   * Reset per turn alongside `budgetWallDetail`.
-   */
-  private budgetWallViaSubAgent = false;
-
-  constructor(
-    private readonly providerRegistry: AIProviderRegistry,
-    config: ChatDriverConfig = {},
-  ) {
-    super();
-    const {
-      toolHandlers = {},
-      toolDefinitions = [],
-      systemPrompt,
-      primerHistory,
-      maxToolIterations = DEFAULT_MAX_TOOL_ITERATIONS,
-      maxFoldOperations = DEFAULT_MAX_FOLD_OPERATIONS,
-      condenseBatchCalls = 1,
-      maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS,
-      sessionKey = '',
-      activityBus = NOOP_ACTIVITY_BUS,
-      budgetExhaustedMessage,
-      providerRefusedMessage,
-    } = config;
-    this.maxToolIterations = maxToolIterations;
-    this.condenseBatchCalls = condenseBatchCalls;
-    this.sessionKey = sessionKey;
-    this.activityBus = activityBus;
-    this.budgetExhaustedMessageOverride = budgetExhaustedMessage;
-    this.providerRefusedMessageOverride = providerRefusedMessage;
-    if (typeof toolHandlers === 'function') {
-      this.toolHandlersFactory = toolHandlers;
-      this.toolHandlers = {};
-    } else {
-      this.toolHandlersFactory = undefined;
-      this.toolHandlers = toolHandlers;
-    }
-    if (typeof toolDefinitions === 'function') {
-      this.toolDefinitionsFactory = toolDefinitions;
-      this.toolDefinitions = [];
-    } else {
-      this.toolDefinitionsFactory = undefined;
-      this.toolDefinitions = toolDefinitions;
-    }
-    this.systemPrompt = systemPrompt;
-    this.primerHistory = primerHistory;
-    this.maxFoldOperations = maxFoldOperations;
-    this.maxTurnSnapshots = maxTurnSnapshots;
-    // 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
-    // `lastDispatchedProviderName` forces the next `resolveProviderForTurn` to
-    // re-emit `provider-changed` even when the resolved *name* is unchanged
-    // (e.g. a tier name like 'high' kept, but the vendor underneath swapped) —
-    // that's what lets status UI refresh on a same-name switch. Feature-detect
-    // means immutable/empty registries are a no-op. Child sub-agent drivers get
-    // the same registry and so subscribe here too; each cleans up in `dispose`.
-    if (isObservableAIProviderRegistry(this.providerRegistry)) {
-      this.unsubscribeRegistry = this.providerRegistry.subscribe(() => {
-        this.resolvedProviderCache.clear();
-        this.resolvedStatusCache.clear();
-        this.lastResolvedProviderName = undefined;
-        this.lastResolvedModel = undefined;
-        this.lastResolvedProvider = undefined;
-        this.lastDispatchedProviderName = undefined;
-      });
-    }
-  }
-
-  /**
-   * Tear down the driver: aborts the lifecycle signal so any in-flight provider
-   * request (and prompt/tool factories awaiting it) cancels instead of running
-   * 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
-   * 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
-   * widget resolves. Sub-agent child disposes always have an empty pending map
-   * (widgets park on the parent via `setHostInteractionRequester`). A pending
-   * interaction is instead settled by `resolveInteraction` (user response or
-   * timeout), which also stamps history and reverts the chat-input override.
-   */
-  dispose(): void {
-    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();
-    // 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.
-    this.unsubscribeRegistry?.();
-    this.unsubscribeRegistry = undefined;
-  }
-
-  /**
-   * Stop the current turn (user "stop" button). Aborts the in-flight provider
-   * request immediately; if a tool is mid-execution it runs to completion and
-   * the loop bails at the next boundary (tools are atomic). No-op when idle.
-   * The driver stays usable for the next message.
-   */
-  cancel(): void {
-    if (!this.busy) return;
-    this.turnCancelled = true;
-    this.turnController.abort(new DOMException('Cancelled by user', 'AbortError'));
-  }
-
-  /**
-   * Start a fresh per-turn abort scope. Chains `lifecycleController` into the
-   * new `turnController` so a dispose mid-turn also aborts the request.
-   */
-  private beginTurn(): void {
-    this.turnCancelled = false;
-    this.turnController = new AbortController();
-    const lifecycle = this.lifecycleController.signal;
-    if (lifecycle.aborted) {
-      this.turnController.abort(lifecycle.reason);
-      this.unlinkLifecycleFromTurn = undefined;
-      return;
-    }
-    const onDispose = () => this.turnController.abort(lifecycle.reason);
-    lifecycle.addEventListener('abort', onDispose, { once: true });
-    this.unlinkLifecycleFromTurn = () => lifecycle.removeEventListener('abort', onDispose);
-  }
-
-  /** Detach the lifecycle→turn link so a long-lived lifecycle signal doesn't accumulate listeners. */
-  private endTurn(): void {
-    this.unlinkLifecycleFromTurn?.();
-    this.unlinkLifecycleFromTurn = undefined;
-  }
-
-  /**
-   * Finish a turn whose signal aborted. A user cancel adds a subtle "Stopped."
-   * marker; a dispose-driven abort stops quietly (the widget is gone and the
-   * cached history would otherwise gain a stray marker on remount).
-   */
-  private completeAbortedTurn(): ChatDriverResult {
-    if (this.turnCancelled) {
-      logger.warn('ChatDriver: turn cancelled by user');
-      this.appendToHistory({ role: 'system-event', content: 'Stopped.' });
-    } else {
-      logger.warn('ChatDriver: turn aborted (driver disposed)');
-    }
-    return { reason: 'done' };
-  }
-
-  /**
-   * Build the `done` loop result, carrying the typed failure reason when the turn
-   * bailed (PTC-0). The discriminant stays `'done'` either way — the same value a
-   * clean turn returns — so consumers matching on `reason === 'done'` are unchanged;
-   * `failureReason` is simply present on a failure and absent on success. Omitted
-   * (rather than set to `undefined`) so a happy-path result stays byte-identical to
-   * the historical `{ reason: 'done' }`.
-   */
-  private turnDone(
-    failureReason?: TurnFailureReason,
-    budget?: BudgetDetail,
-    providerRefused?: ProviderRefusedDetail,
-  ): ChatDriverResult {
-    if (!failureReason) return { reason: 'done' };
-    // Both payloads are omitted rather than set to `undefined`, so a failure that carries neither has
-    // a shape unchanged for a consumer that structurally compares it.
-    return {
-      reason: 'done',
-      failureReason,
-      ...(budget ? { budget } : {}),
-      ...(providerRefused ? { providerRefused } : {}),
-    };
-  }
-
-  /**
-   * Terminal budget outcome for a wall hit **outside** the tool loop — today,
-   * `OrchestratingDriver`'s classification phase, which calls the provider
-   * directly and so never enters `runToolLoop`.
-   *
-   * Does **not** publish `tool-loop-end`: no `tool-loop-start` was published for
-   * the classify phase, and an unbalanced end would break start/end pairing for
-   * subscribers that rely on it. The driver **return value** is what reports this
-   * case — see `FoundationAiAssistant`'s latch, which reads both seams for
-   * exactly this reason.
-   *
-   * The non-sub-agent tail of the in-loop `BudgetExhaustedError` branch lives
-   * here so there is one copy of the log line, the debug-log entry, the
-   * transcript bubble and the result shape rather than two that can drift.
-   *
-   * @param pendingUserMessage - a user message that has NOT yet been appended,
-   *   appended first so the answer does not end up replying to nothing. Only the
-   *   classification seam passes it: `OrchestratingDriver` dispatches the user's
-   *   text as an optimistic `history-updated` detail and leaves the real append
-   *   to `chatDriver.sendMessage`, which never runs when `classify()` throws — so
-   *   the bubble below would re-dispatch a history the user's own message was
-   *   never in, and it would vanish from the transcript on the next render. The
-   *   in-loop caller has already appended it and passes nothing.
-   *
-   * @internal
-   */
-  private budgetExhaustedBubble(wall?: {
-    vendorLabel?: string;
-    otherVendorAvailable?: boolean;
-  }): string {
-    // A host override wins verbatim — the white-label contract on
-    // `ChatDriverConfig.budgetExhaustedMessage` (its copy may not even be
-    // English; composing onto it would mangle it).
-    if (this.budgetExhaustedMessageOverride != null) return this.budgetExhaustedMessageOverride;
-    // Only a POSITIVE `otherVendorAvailable` earns the switch advice. `false`
-    // means every other metered vendor is exhausted too, and `undefined` means
-    // an older proxy did not say — in both cases advertising a switch to a
-    // vendor that may itself be walled is worse than the neutral default. This
-    // mirrors the blocked banner's rule, and closes the gap where the banner
-    // said "switch" while the transcript bubble directly under it said only
-    // "contact your administrator" (GENC-1464 tester finding).
-    if (wall?.otherVendorAvailable !== true) return DEFAULT_BUDGET_EXHAUSTED_MESSAGE;
-    // The label is display copy, nothing more — attribution (which vendor gets
-    // WALLED) stays `budgetDetailOf`'s job. The parameter is the shared shape of
-    // both call sites: the thrown `BudgetExhaustedError` on the direct path, and
-    // the latched `budgetWallDetail` on the sub-agent path.
-    const subject = wall?.vendorLabel
-      ? `${wall.vendorLabel}'s AI usage limit`
-      : 'your AI usage limit';
-    return `You've reached ${subject}. Switch to another AI provider in Settings to keep going, or contact your administrator to raise it.`;
-  }
-
-  reportBudgetExhausted(
-    e: BudgetExhaustedError,
-    pendingUserMessage?: ChatMessage,
-  ): ChatDriverResult {
-    if (pendingUserMessage) this.appendToHistory(pendingUserMessage);
-    this.budgetExhaustedThisTurn = true;
-    logger.error('ChatDriver: AI budget exhausted', e);
-    recordTurnError(this.sessionKey, 'budget-exhausted', {
-      agent: this.activeAgentName,
-      provider: this.lastResolvedProviderName,
-      // The registry ALIAS (e.g. 'high') is what `provider` records; the vendor
-      // is the thing a per-vendor budget is actually scoped to, and it was known
-      // at both ends and discarded in the middle until now. Taken from the
-      // refusing transport's label first — this method also serves the
-      // classification seam, where `lastResolvedProvider` is the PREVIOUS turn's
-      // vendor (or nothing), because classify runs against the registry default.
-      vendor:
-        vendorTypeOfLabel(e.vendorLabel) ??
-        vendorTypeOfLabel(e.serverVendor) ??
-        this.lastResolvedProvider,
-      budgetUsd: e.budgetUsd,
-      spentUsd: e.spentUsd,
-      isSubAgent: this.isSubAgent,
-    });
-    this.appendToHistory({ role: 'assistant', content: this.budgetExhaustedBubble(e) });
-    return this.turnDone('budget-exhausted', budgetDetailOf(e));
-  }
-
-  /**
-   * The sentence shown when the upstream provider refuses (GENC-1506).
-   *
-   * Deliberately far simpler than `budgetExhaustedBubble`: no vendor name, no figures, no
-   * switch-provider advice, and no branching on `kind`. The copy is cause-free by design — a user who
-   * can see their own remaining spend must not be told about a limit, and we must not imply the bill
-   * has gone unpaid — so there is nothing here to compose. A host override wins verbatim.
-   */
-  private providerRefusedBubble(): string {
-    return this.providerRefusedMessageOverride ?? DEFAULT_PROVIDER_REFUSED_MESSAGE;
-  }
-
-  /**
-   * Terminal provider-refusal outcome. Mirrors `reportBudgetExhausted` so the two walls behave
-   * identically from the caller's side, while keeping their diagnostics distinct.
-   *
-   * `kind` reaches the debug log and the result but never the transcript: it is what lets an operator
-   * tell "top up the account" from "rotate the key", and with cause-free user copy this is the only
-   * place that distinction survives.
-   */
-  private reportProviderRefused(e: ProviderRefusedError): ChatDriverResult {
-    const detail = providerRefusedDetailOf(e);
-    this.providerRefusedThisTurn = true;
-    this.providerRefusedDetail = detail;
-    logger.error('ChatDriver: provider refused the request', e);
-    recordTurnError(this.sessionKey, 'provider-refused', {
-      agent: this.activeAgentName,
-      provider: this.lastResolvedProviderName,
-      vendor: vendorTypeOfLabel(e.vendorLabel) ?? this.lastResolvedProvider,
-      kind: e.kind,
-      upstreamStatus: e.upstreamStatus,
-      upstreamType: e.upstreamType,
-      isSubAgent: this.isSubAgent,
-    });
-    this.appendToHistory({ role: 'assistant', content: this.providerRefusedBubble() });
-    return this.turnDone('provider-refused', undefined, detail);
-  }
-
-  /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
-  private static failureReasonOf(result: ChatDriverResult): TurnFailureReason | undefined {
-    return result.reason === 'done' ? result.failureReason : undefined;
-  }
-
-  /**
-   * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
-   * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
-   * kept byte-identical so subscribers see exactly what they always have.
-   *
-   * A budget failure additionally carries `vendor` — the concrete vendor
-   * (`'anthropic'`/`'gemini'`) the walled turn resolved to, which the driver knows
-   * and used to discard. Optional and additive: a subscriber reading only
-   * `failureReason` is unaffected, a non-budget failure still emits the historical
-   * `{ failureReason }` with no `vendor` key, and the value is a plain string so
-   * the detail stays structured-cloneable for the cross-tab hop. It is the field a
-   * per-vendor budget model needs and the one that would be awkward to retrofit.
-   */
-  private loopEndDetail(result: ChatDriverResult):
-    | {
-        failureReason: TurnFailureReason;
-        vendor?: AIProviderType;
-        budget?: BudgetDetail;
-      }
-    | undefined {
-    const failureReason = ChatDriver.failureReasonOf(result);
-    if (!failureReason) return undefined;
-    if (failureReason !== 'budget-exhausted') {
-      return { failureReason };
-    }
-    // The figures ride the event, not just the return value: this publish happens in
-    // sendMessage's `finally`, so for an in-loop wall it reaches the host's latch FIRST
-    // and the return-value seam is then a no-op (the latch is idempotent). Omitted
-    // entirely — never set to undefined — when the proxy sent no figures.
-    const budget = result.reason === 'done' ? result.budget : undefined;
-    // Prefer the refusing transport's own attribution over the driver's
-    // last-resolved provider, for the same staleness reason as `budgetDetailOf`.
-    //
-    // The fallback is legitimate ONLY for this driver's own wall — its resolved
-    // provider IS the refuser then. When the wall came from a SUB-AGENT
-    // (`budgetWallViaSubAgent`), the refuser is the child's vendor, and on a
-    // mixed registry `lastResolvedProvider` is the one vendor known NOT to have
-    // refused; an unattributable child wall degrades to the vendor-agnostic
-    // event instead, which the host's latch handles fail-safe.
-    const vendor =
-      budget?.vendor ?? (this.budgetWallViaSubAgent ? undefined : this.lastResolvedProvider);
-    return {
-      failureReason,
-      ...(vendor ? { vendor } : {}),
-      ...(budget ? { budget } : {}),
-    };
-  }
-
-  /**
-   * Swap in a new agent's configuration. Called by OrchestratingDriver before
-   * each specialist turn so the shared driver runs with the right tools and prompt.
-   */
-  applyAgent(config: AgentConfig): void {
-    // A real swap to a different agent begins a NEW activation — the prior agent's
-    // flow is over, so its `agentEnd`-tagged payloads become collapsible. Guarded
-    // on a name change so re-applying the same agent (e.g. a per-turn re-resolve)
-    // does not spuriously advance the clock and prematurely drop its payloads.
-    if (config.name !== this.activeAgentName) this.currentActivation += 1;
-    this.systemPrompt = config.systemPrompt;
-    if (typeof config.toolDefinitions === 'function') {
-      this.toolDefinitionsFactory = config.toolDefinitions;
-      // Cleared each turn by the factory in runToolLoop; empty is safe in the
-      // meantime (no LLM call happens before resolution).
-      this.toolDefinitions = [];
-    } else {
-      this.toolDefinitionsFactory = undefined;
-      this.toolDefinitions = config.toolDefinitions ?? [];
-    }
-    if (typeof config.toolHandlers === 'function') {
-      this.toolHandlersFactory = config.toolHandlers;
-      // Cleared each turn by the factory in runToolLoop; empty is safe in the
-      // meantime (no LLM call happens before resolution).
-      this.toolHandlers = {};
-    } else {
-      this.toolHandlersFactory = undefined;
-      this.toolHandlers = config.toolHandlers ?? {};
-    }
-    this.primerHistory = config.primerHistory;
-    this.activeAgentName = config.name;
-    this.displayName = config.displayName;
-    // Static string form resolves to a stable label up-front; the function
-    // form gets re-resolved each tool-loop iteration. Falls back to the
-    // canonical name when displayName is unset.
-    this.activeAgentLabel =
-      typeof config.displayName === 'string' ? config.displayName : config.name;
-    this.debugSnapshotter = config.getDebugSnapshot;
-    this.subAgentsMap = new Map((config.subAgents ?? []).map((s) => [s.name, s]));
-    this.activeProviderInput = config.provider;
-    this.activeTemperatureInput = config.temperature;
-    this.activeToolChoiceInput = config.toolChoice;
-    this.activeCachePolicyInput = config.cachePolicy;
-    this.activeThinkingPolicyInput = config.thinkingPolicy;
-    this.activeTailContextInput = config.tailContext;
-    this.activeResponseSchemaInput = config.responseSchema;
-    this.activeFallbacks = config.fallbacks;
-    this.activeOnUnresolvedTool = config.onUnresolvedTool;
-    this.resolvedProviderCache.clear();
-    this.lastResolvedProviderName = undefined;
-    // Static validation: resolve the name now so unknown-provider and missing-
-    // capability errors fire at agent swap rather than on the first LLM call.
-    // Function-form `provider` is validated lazily inside `resolveProviderForTurn`.
-    if (typeof config.provider === 'string') {
-      this.resolveProviderByName(config.provider, config.name);
-    }
-    // Reset fold state when agent changes — each specialist starts fresh
-    this.foldStack = [];
-    this.consecutiveFoldOps = 0;
-    // Forget the previous agent's tools — "previously available" is scoped to
-    // the current activation, so a stateful agent accumulates its tools across
-    // states while a swap to a different specialist starts clean.
-    this.everSeenToolNames.clear();
-  }
-
-  /**
-   * Resolve the tool-result content for an unresolved tool call. Consults the
-   * active agent's `onUnresolvedTool` hook (if any) with the attempted tool
-   * name, the failure `kind`, and the currently dispatchable tools, and returns
-   * the hook's non-empty string. Falls back to `fallback` when no hook is set,
-   * the hook returns nothing/empty, or the hook throws — so a misbehaving hook
-   * can never break tool dispatch.
-   */
-  private async resolveUnresolvedToolContent(
-    toolName: string,
-    kind: 'stale' | 'unknown',
-    fallback: string,
-  ): Promise<string> {
-    if (typeof this.activeOnUnresolvedTool !== 'function') {
-      return fallback;
-    }
-    try {
-      const custom = await this.activeOnUnresolvedTool({
-        toolName,
-        kind,
-        availableTools: Object.keys(this.toolHandlers),
-      });
-      return typeof custom === 'string' && custom.trim().length > 0 ? custom : fallback;
-    } catch (e) {
-      logger.warn(
-        `ChatDriver: onUnresolvedTool threw for "${toolName}" — using default message`,
-        e,
-      );
-      return fallback;
-    }
-  }
-
-  /**
-   * Returns the most recently resolved provider name. Falls back to the
-   * registry's default when no per-turn resolution has happened yet.
-   */
-  getActiveProviderName(): string {
-    return this.lastResolvedProviderName ?? this.providerRegistry.defaultName();
-  }
-
-  /**
-   * Resolve a named provider against the registry. Cached per-agent so
-   * repeated lookups during one agent's lifetime don't re-validate.
-   * Validation lives in `resolveChatProvider`; this wrapper just adds the
-   * cache.
-   */
-  private resolveProviderByName(name: string, agentName: string): AIProvider {
-    const cached = this.resolvedProviderCache.get(name);
-    if (cached) return cached;
-    const provider = resolveChatProvider(this.providerRegistry, name, agentName);
-    this.resolvedProviderCache.set(name, provider);
-    return provider;
-  }
-
-  /**
-   * Resolve the provider to use for the current turn. Walks the agent's
-   * `provider` selector (static or function form) or falls back to the
-   * registry default. Dispatches `provider-changed` when the resolved name
-   * differs from the last dispatched value.
-   */
-  private async resolveProviderForTurn(ctx: SystemPromptContext): Promise<AIProvider> {
-    let provider: AIProvider;
-    let resolvedName: string;
-    if (this.activeProviderInput === undefined) {
-      provider = this.providerRegistry.default();
-      resolvedName = this.providerRegistry.defaultName();
-    } else {
-      const name =
-        typeof this.activeProviderInput === 'function'
-          ? await this.activeProviderInput(ctx)
-          : this.activeProviderInput;
-      provider = this.resolveProviderByName(name, this.activeAgentName ?? '<unknown>');
-      resolvedName = name;
-    }
-    this.lastResolvedProviderName = resolvedName;
-    const status = await this.resolveStatusForProvider(resolvedName, provider);
-    this.lastResolvedModel = status.model;
-    this.lastResolvedProvider = status.provider;
-    if (resolvedName !== this.lastDispatchedProviderName) {
-      this.lastDispatchedProviderName = resolvedName;
-      recordMetaEvent(this.sessionKey, 'provider.selected', {
-        // `provider` is the registry SLOT (a tier name like 'high'), kept under that key
-        // for compatibility; `model` and `vendor` are what it resolved to. Recording all
-        // three is the difference between "the agent switched to its high tier" and
-        // knowing which model that actually was — a tier can be repointed mid-session,
-        // and a slot name alone cannot distinguish anthropic from gemini.
-        provider: resolvedName,
-        model: status.model,
-        vendor: status.provider,
-        agent: this.activeAgentName,
-      });
-      this.dispatchEvent(
-        new CustomEvent<{ name: string }>('provider-changed', { detail: { name: resolvedName } }),
-      );
-    }
-    return provider;
-  }
-
-  /**
-   * Resolve model id and vendor from a provider via its optional `getStatus()`,
-   * memoised by registry name. Used to stamp `model` and `provider` onto outgoing
-   * messages. Best-effort: a provider without `getStatus`, a null status, or a
-   * throw all yield empty fields — attribution is diagnostic, never load-bearing.
-   */
-  private async resolveStatusForProvider(
-    name: string,
-    provider: AIProvider,
-  ): Promise<{ model?: string; provider?: AIProviderType }> {
-    if (this.resolvedStatusCache.has(name)) return this.resolvedStatusCache.get(name)!;
-    let status: { model?: string; provider?: AIProviderType } = {};
-    try {
-      const resolved = await provider.getStatus?.();
-      if (resolved) {
-        status = { model: resolved.model, provider: resolved.provider };
-      }
-    } catch {
-      status = {};
-    }
-    this.resolvedStatusCache.set(name, status);
-    return status;
-  }
-
-  /**
-   * Resolve a per-turn config input that is either a static value or a function
-   * of the turn context — the value-or-resolver shape shared by `provider`,
-   * `temperature`, and `toolChoice`. Returns undefined when the input is unset.
-   */
-  private async resolveTurnInput<T>(
-    input: T | ((ctx: SystemPromptContext) => T | Promise<T>) | undefined,
-    ctx: SystemPromptContext,
-  ): Promise<T | undefined> {
-    if (input === undefined) return undefined;
-    return typeof input === 'function'
-      ? (input as (ctx: SystemPromptContext) => T | Promise<T>)(ctx)
-      : input;
-  }
-
-  /**
-   * Returns the early-stop result set by `completeSubAgent`, if any.
-   * Called by a parent `ChatDriver` after running this instance as a sub-agent.
-   */
-  getSubAgentCompletion(): { result: unknown } | undefined {
-    return this.subAgentCompletion;
-  }
-
-  /**
-   * Mark this driver as running as a sub-agent. Called by a parent driver's
-   * `invokeSubAgent` immediately after construction, before the first turn.
-   * Enables forced tool use and typed failure reporting (see `isSubAgent`).
-   */
-  markAsSubAgent(): void {
-    this.isSubAgent = true;
-  }
-
-  /**
-   * Returns the typed failure recorded when a sub-agent run ended without
-   * `completeSubAgent`, if any. Called by a parent `ChatDriver` after running
-   * this instance as a sub-agent.
-   */
-  getSubAgentFailure():
-    | {
-        reason: SubAgentFailureReason;
-        budget?: BudgetDetail;
-        providerRefused?: ProviderRefusedDetail;
-      }
-    | undefined {
-    return this.subAgentFailure;
-  }
-
-  /**
-   * Record a sub-agent failure reason (first one wins). No-op for top-level
-   * agents, so loop-exit sites can call it unconditionally. The parent reads
-   * this via `getSubAgentFailure()` and emits the `subagent.failed` meta event
-   * under its *own* session — see `invokeSubAgent`. (A child sub-agent runs
-   * under a separate session key, so recording here would orphan the event off
-   * the user-visible debug-log timeline.)
-   */
-  private failSubAgent(
-    reason: SubAgentFailureReason,
-    budget?: BudgetDetail,
-    providerRefused?: ProviderRefusedDetail,
-  ): void {
-    if (!this.isSubAgent || this.subAgentFailure) return;
-    // Each payload is omitted rather than set to `undefined` so a failure carrying neither has a shape
-    // unchanged for a structural comparison, matching `turnDone`.
-    this.subAgentFailure = {
-      reason,
-      ...(budget ? { budget } : {}),
-      ...(providerRefused ? { providerRefused } : {}),
-    };
-  }
-
-  /**
-   * Returns true if `releaseAgent` was called during the most recent turn.
-   * Consumed by the orchestrator to trigger the auto-pin release path.
-   */
-  getAgentReleaseRequested(): boolean {
-    return this.agentReleaseRequested;
-  }
-
-  /**
-   * Return the per-turn snapshots captured so far. Used by the host's debug
-   * 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.
-   */
-  getTurnSnapshots(): ReadonlyArray<TurnSnapshot> {
-    return this.turnSnapshots;
-  }
-
-  /**
-   * 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.)
-   */
-  getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry> {
-    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.
-   */
-  private forwardSubAgentSnapshots(childSnapshots: ReadonlyArray<TurnSnapshot>): void {
-    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<string, string>();
-    let ownPos = 0;
-    for (const snap of childSnapshots) {
-      let turnIndex: string;
-      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 = 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.
-   */
-  private recordTurnSnapshot(
-    resolvedSystemPrompt: string | undefined,
-    temperature: number | undefined,
-    toolChoice: ChatToolChoice | undefined,
-    tailContext: string | undefined,
-  ): TurnSnapshot {
-    let agentSnapshot: unknown;
-    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: TurnSnapshot = {
-      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;
-  }
-
-  /**
-   * Optional transform applied to conversation history immediately before each LLM request.
-   * Cleared when `undefined`. Does not alter stored history.
-   */
-  setProviderHistoryTransform(transform?: (history: ChatMessage[]) => ChatMessage[]): void {
-    this.providerHistoryTransform = transform;
-  }
-
-  getHistory(): ReadonlyArray<ChatMessage> {
-    return this.history;
-  }
-
-  getRawHistory(): readonly ChatMessage[] {
-    return this.history;
-  }
-
-  /** Returns the current fold stack names for debugging. */
-  getActiveFoldNames(): string[] {
-    return this.foldStack.map((f) => f.foldName);
-  }
-
-  async getSuggestions(
-    history: ChatMessage[],
-    prompt: string,
-    count: number,
-    allAgentInfo?: AllAgentSummary[],
-  ): Promise<string[]> {
-    // Suggestions are an out-of-turn UI helper, not bound to any single agent —
-    // always run against the registry default. Best-effort: a default with no
-    // `prompt()` just means no suggestions, not a hard error.
-    const defaultProvider = this.providerRegistry.default();
-    if (!defaultProvider.prompt) {
-      logger.warn('ChatDriver: default AI provider does not implement prompt()');
-      return [];
-    }
-
-    let agentContext = '';
-    let toolContext = '';
-
-    if (allAgentInfo?.length) {
-      const agentDescriptions = allAgentInfo
-        .map((agent) => {
-          const tools = agent.tools.map((t) => t.name).join(', ');
-          return `- ${agent.name} (${agent.description}): ${tools ? `(Tools: ${tools})` : 'No tools'}`;
-        })
-        .join('\n');
-      agentContext = `The assistant has the following capabilities:\n${agentDescriptions}`;
-
-      const allToolNames = allAgentInfo
-        .flatMap((agent) => agent.tools.map((t) => t.name))
-        .filter((value, index, self) => self.indexOf(value) === index)
-        .join(', ');
-      toolContext = allToolNames
-        ? `You have access to the following tools across all agents: ${allToolNames}.`
-        : '';
-    } else if (this.activeAgentName) {
-      const toolNames = this.toolDefinitions.map((tool) => tool.name).join(', ');
-      agentContext = `You are currently acting as the "${this.activeAgentName}" agent.`;
-      toolContext = toolNames ? `You have access to the following tools: ${toolNames}.` : '';
-    }
-
-    // System prompt is intentionally short: it sets the role only. Concrete
-    // instructions live in the user message *after* the transcript so the
-    // immediately-preceding context for the model is "here is data, now do X"
-    // rather than "here is a dialogue, continue it". This matters for Anthropic
-    // — without it, Claude reads the transcript as an in-progress conversation
-    // and produces a normal assistant turn instead of a list of suggestions.
-    const systemPrompt =
-      'You generate suggested prompts that a user could send to an AI assistant. ' +
-      'You never continue the conversation or roleplay as the assistant.';
-
-    const capabilitiesBlock =
-      agentContext || toolContext
-        ? `\n\n<capabilities>\n${[agentContext, toolContext].filter(Boolean).join('\n')}\n</capabilities>\nSuggestions must only cover what the agent is capable of. Do not suggest anything outside these capabilities.`
-        : '';
-
-    const guidanceBlock = prompt ? `\n\nAdditional guidance: "${prompt}"` : '';
-
-    let userMessage: string;
-    if (history.length === 0) {
-      userMessage =
-        `Generate exactly ${count} brief starter prompts to show a user what an AI assistant can do. ` +
-        `Phrase each one as the user would write it. Keep them short and generic — do not invent specific names, IDs, or data (e.g. prefer "Search for a trade" over "Find all trades with Client A").` +
-        capabilitiesBlock +
-        guidanceBlock +
-        `\n\nOutput format (strict):\n` +
-        `- Exactly ${count} lines.\n` +
-        `- One suggestion per line.\n` +
-        `- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.\n` +
-        `- No preamble, headings, summary, or commentary before or after the list.`;
-    } else {
-      const conversationContext = history
-        .filter(
-          (m) =>
-            (m.role === 'user' || m.role === 'assistant') &&
-            !m.toolCalls?.length &&
-            !m.thinking &&
-            !!m.content?.trim(),
-        )
-        .slice(-SUGGESTIONS_HISTORY_WINDOW)
-        .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
-        .join('\n');
-
-      userMessage =
-        `<conversation_history>\n${conversationContext}\n</conversation_history>\n\n` +
-        `The conversation above has ended. Do not continue it or respond as the assistant. ` +
-        `Generate exactly ${count} follow-up prompts the *user* might send next, phrased in first person as the user would write them. ` +
-        `The first ${Math.max(0, count - 1)} should be natural follow-ups to the last turn. ` +
-        `Do not invent specific names, IDs, or data values that do not appear in <conversation_history>.` +
-        capabilitiesBlock +
-        guidanceBlock +
-        `\n\nOutput format (strict):\n` +
-        `- Exactly ${count} lines.\n` +
-        `- One suggestion per line.\n` +
-        `- No numbering, bullets, markdown, emojis, code blocks, or quotes around the suggestion.\n` +
-        `- No preamble, headings, summary, or commentary before or after the list.`;
-    }
-
-    const text = await defaultProvider.prompt!(userMessage, { systemPrompt });
-
-    // Lenient parsing as a defensive backstop: even with the strict prompt,
-    // models occasionally slip in numbering, bullets, or surrounding markdown.
-    return (
-      text
-        .split('\n')
-        .map((s) => s.trim())
-        // strip leading bullets/numbers ("- ", "* ", "• ", "1. ", "1) ")
-        .map((s) => s.replace(/^([-*•]|\d+[.)])\s+/, ''))
-        // strip surrounding bold/italic markers
-        .map((s) => s.replace(/^[*_]{1,3}|[*_]{1,3}$/g, '').trim())
-        // drop empty lines, separators, and obvious preamble lines
-        .filter((s) => s.length > 0)
-        .filter((s) => !/^[-=]{2,}$/.test(s))
-        .filter((s) => !/^here (are|is) /i.test(s))
-        .filter((s) => !s.endsWith(':'))
-        .slice(0, count)
-    );
-  }
-
-  /**
-   * Whether `compact()` would do anything right now — a summarizable run of older
-   * turns exists behind a clean boundary. Uses the same `history` `compact()`
-   * acts on, so the UI's gate can't disagree with the action (GENC-1351 follow-up).
-   */
-  canCompact(): boolean {
-    return findCompactionCut(this.history) != null;
-  }
-
-  /**
-   * Destructively compact older turns into a single `compacted-summary` message
-   * (GENC-1351 §5.7). Summarizes everything before a clean recent-tail boundary
-   * via the registry-default provider's one-shot `prompt()`, then **atomically**
-   * replaces the covered turns with one summary message at the head — history is
-   * mutated only on success. Rolling: any existing head summary is folded into
-   * the new one. Returns the created summary message, or `null` when there is
-   * nothing worth compacting or the default provider cannot summarize.
-   */
-  async compact(): Promise<ChatMessage | null> {
-    if (this.busy) return null;
-    const defaultProvider = this.providerRegistry.default();
-    if (!defaultProvider.prompt) {
-      logger.warn('ChatDriver: default AI provider has no prompt(); cannot compact');
-      return null;
-    }
-
-    const history = this.history;
-    const cut = findCompactionCut(history);
-    if (cut == null) return null;
-
-    const toCompact = history.slice(0, cut);
-    const tail = history.slice(cut);
-
-    // Summarize BEFORE mutating history — a failed/empty call leaves the
-    // transcript untouched (atomic generate-then-replace).
-    const { systemPrompt, userMessage } = buildCompactionSummaryPrompt(toCompact);
-    // Surface a failure the way turn errors are surfaced — a brief "sorry" agent
-    // message — while leaving the transcript itself untouched (atomic). Retrying
-    // is safe (nothing was spliced).
-    const failMessage =
-      "Sorry, I couldn't compact the conversation just now. Nothing was changed — please try again.";
-    let summaryText: string;
-    try {
-      summaryText = (await defaultProvider.prompt!(userMessage, { systemPrompt }))?.trim() ?? '';
-    } catch (e) {
-      logger.warn(`ChatDriver: compaction summary failed: ${e instanceof Error ? e.message : e}`);
-      this.appendToHistory({ role: 'assistant', content: failMessage });
-      return null;
-    }
-    if (!summaryText) {
-      logger.warn('ChatDriver: compaction summary was empty; leaving history untouched');
-      this.appendToHistory({ role: 'assistant', content: failMessage });
-      return null;
-    }
-
-    let tokensBefore: number | undefined;
-    for (let i = history.length - 1; i >= 0; i -= 1) {
-      if (history[i].inputTokens != null) {
-        tokensBefore = history[i].inputTokens;
-        break;
-      }
-    }
-    const status = await defaultProvider.getStatus?.();
-    const createdAt = new Date().toISOString();
-    const summaryMessage: ChatMessage = {
-      role: 'compacted-summary',
-      content: summaryText,
-      // Stamp with the covered region's start, not "now": the summary stands in
-      // for the oldest messages and sits at the head of history, so this keeps it
-      // sorted to the head in any timestamp-ordered view (the debug timeline) and
-      // history time-monotonic. Its true creation time is in compaction.createdAt.
-      timestamp: toCompact[0]?.timestamp ?? createdAt,
-      compaction: {
-        compactedCount: toCompact.length,
-        coveredThroughTimestamp: toCompact[toCompact.length - 1]?.timestamp,
-        tokensBefore,
-        model: status?.model,
-        createdAt,
-        // Bank what the replaced turns spent. `toCompact` is dropped from history
-        // below, taking its per-message cost/token fields with it — so a host total
-        // re-derived from the transcript would otherwise fall by exactly this much
-        // on every compaction. Summarising a turn does not refund what it cost.
-        rolledUpUsage: sumUsage(toCompact),
-      },
-    };
-
-    this.loadHistory([summaryMessage, ...tail]);
-    return summaryMessage;
-  }
-
-  isBusy(): boolean {
-    return this.busy;
-  }
-
-  /**
-   * Wire a parent driver as the host for this driver's interactions. When set,
-   * `requestInteraction` delegates upward so the widget renders in (and
-   * resolves through) the parent's history and pending map. Calls chain
-   * naturally: a grandchild → child → root.
-   */
-  public setHostInteractionRequester(
-    fn: <T>(componentName: string, data: any, options?: InteractionRequestOptions) => Promise<T>,
-  ): void {
-    this.hostInteractionRequester = fn;
-  }
-
-  /**
-   * Request a custom UI interaction. Emits a new message with the interaction.
-   * Tool handlers can call this to pause execution until the user completes the UI interaction.
-   *
-   * If a host requester is wired (sub-agent case), the call delegates upward
-   * so the interaction lives on the parent — the main UI is only listening to
-   * the root driver. Only one interaction may be in flight at any time on a
-   * given root: concurrent calls (e.g. two parallel sub-agents both spawning a
-   * widget) throw. Parallel sub-agents are for parallel work, not for user
-   * interaction, which is inherently sequential.
-   *
-   * @param componentName - The custom element name to render.
-   * @param data - Data to pass to the component.
-   * @param options - Optional per-call overrides, including
-   *   `chatInputDuringExecution` to hide or disable the main chat input while
-   *   the widget is awaiting user input (reverts when the interaction resolves),
-   *   and `presentation` to control whether the host wraps the widget in a chat
-   *   bubble and/or shows the "Assistant" label.
-   */
-  public async requestInteraction<T>(
-    componentName: string,
-    data: any,
-    options?: InteractionRequestOptions,
-  ): Promise<T> {
-    if (this.hostInteractionRequester) {
-      return this.hostInteractionRequester<T>(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?.chatInputDuringExecution;
-    const timeoutMs = options?.timeoutMs;
-    const presentation = 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.`,
-                } satisfies InteractionResult);
-              }, 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: {
-          interactionId,
-          componentName,
-          data,
-          ...(presentation ? { presentation } : {}),
-        },
-      });
-    });
-  }
-
-  /**
-   * Add external (non-LLM) spend to an interaction's message AFTER it has resolved.
-   *
-   * **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.
-   *
-   * 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.
-   *
-   * @param interactionId the interaction whose message owns the spend.
-   * @param costUsd a positive delta in USD. Non-finite, zero and negative values are ignored.
-   * @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.
-   * @beta
-   */
-  public recordExternalCost(interactionId: string, costUsd: number): boolean {
-    const drop = (reason: string): false => {
-      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);
-    // 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] = {
-      ...this.history[idx],
-      externalCostUsd: (this.history[idx].externalCostUsd ?? 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<{ interactionId: string; costUsd: number }>('external-cost-recorded', {
-        detail: { interactionId, costUsd },
-      }),
-    );
-    return true;
-  }
-
-  /**
-   * 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.
-   */
-  public resolveInteraction(interactionId: string, result: any): void {
-    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 as { diagnostics?: readonly unknown[] } | undefined)
-        ?.diagnostics;
-      if (Array.isArray(harvestedDiagnostics) && harvestedDiagnostics.length) {
-        const batch = (this.externalDiagnosticsBatches += 1);
-        const externalEvents: MetaEvent[] = [];
-        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 as { kind?: unknown }).kind !== 'string'
-          ) {
-            continue;
-          }
-          const entry = raw as DiagnosticEntry;
-          if (entry.kind === 'event') {
-            const { kind: _kind, ...event } = entry;
-            externalEvents.push(event as unknown as MetaEvent);
-          } 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({
-              ...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) => m.interaction?.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?.costUsd === 'number' &&
-          Number.isFinite(result.costUsd) &&
-          result.costUsd > 0
-            ? result.costUsd
-            : undefined;
-        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<ReadonlyArray<ChatMessage>>('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?.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)
-      this.interactionContexts.get(interactionId)?.dispose();
-      this.interactionContexts.delete(interactionId);
-    } else {
-      logger.warn(`Interaction with ID ${interactionId} not found.`);
-    }
-  }
-
-  /**
-   * The live {@link InteractionContext} for a pending interaction (GENC-1390), or
-   * `undefined` once resolved/evicted. Read by `AiChatInteractionWrapper` (via the
-   * host) to build the widget's pending `interaction` descriptor.
-   */
-  public getInteractionContext(interactionId: string): InteractionContext | undefined {
-    return this.interactionContexts.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.
-   */
-  private cancelPendingInteractions(message: string): void {
-    for (const interactionId of [...this.pendingInteractions.keys()]) {
-      this.resolveInteraction(interactionId, {
-        status: 'timeout',
-        message,
-      } satisfies InteractionResult);
-    }
-  }
-
-  /**
-   * Seeds the driver with a prior conversation history so a new component instance
-   * can continue an existing conversation. Call this before the first user message.
-   */
-  public loadHistory(messages: ChatMessage[]): void {
-    this.history = [...messages];
-    this.dispatchEvent(
-      new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
-        detail: this.history,
-      }),
-    );
-  }
-
-  async sendMessage(userInput: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult> {
-    if (this.busy || (!userInput.trim() && !attachments?.length)) return { reason: 'done' };
-
-    this.busy = true;
-    this.beginTurn();
-    // A new user turn — advances the `turnEnd` clock (continuations after a
-    // handoff stay on the same turn; they go through `continueFromHistory`).
-    this.turnSeq += 1;
-    this.subAgentCompletion = undefined;
-    this.subAgentFailure = undefined;
-    this.agentReleaseRequested = false;
-    this.budgetExhaustedThisTurn = false;
-    this.budgetWallDetail = undefined;
-    this.budgetWallViaSubAgent = false;
-    this.providerRefusedThisTurn = false;
-    this.providerRefusedDetail = undefined;
-    this.appendToHistory({ role: 'user', content: userInput, attachments });
-    this.turnStartedAt = Date.now();
-    recordMetaEvent(this.sessionKey, 'turn.start', {
-      phase: 'sendMessage',
-      agent: this.activeAgentName,
-    });
-    this.activityBus.publish('tool-loop-start', undefined);
-
-    // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
-    let result: ChatDriverResult = { reason: 'done' };
-    try {
-      result = await this.runToolLoop(userInput, attachments);
-      return result;
-    } catch (e) {
-      logger.error('ChatDriver error:', e);
-      recordTurnError(this.sessionKey, 'exception', {
-        phase: 'sendMessage',
-        agent: this.activeAgentName,
-        provider: this.lastResolvedProviderName,
-        name: e instanceof Error ? e.name : undefined,
-        message: e instanceof Error ? e.message : String(e),
-      });
-      this.appendToHistory({
-        role: 'assistant',
-        content: 'Sorry, something went wrong on my end. Please try again in a moment.',
-      });
-      result = this.turnDone('exception');
-      return result;
-    } finally {
-      recordMetaEvent(this.sessionKey, 'turn.end', {
-        phase: 'sendMessage',
-        agent: this.activeAgentName,
-        durationMs: Date.now() - this.turnStartedAt,
-      });
-      this.busy = false;
-      this.endTurn();
-      this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
-    }
-  }
-
-  /**
-   * Builds the context object passed to every tool handler call.
-   * Centralised here so fold shortcut dispatch and the main tool loop use the
-   * same context without duplication.
-   *
-   * @param activeToolCallId - The id of the tool call this context belongs to, so
-   *   `condenseWhen` can register against the right call (it stamps the clocks
-   *   straight off the driver). Absent for dispatch paths with no addressable tool
-   *   call (e.g. the fold-close handler), where `condenseWhen` is a no-op.
-   * @param traceCapture - Optional per-tool-call accumulator. When provided, every
-   *   sub-agent call's trace is **appended** here rather than written to shared
-   *   instance state, so parallel tool calls each capture their own traces
-   *   independently.
-   *
-   *   Deliberately a list of traces, not one slot. A single handler may call
-   *   `requestSubAgent` more than once — a code-driven scheduler dispatching a
-   *   dependency graph, a retry of a timed-out child, any fan-out helper — and a
-   *   single slot kept only the last, so every other child ran, was billed by the
-   *   provider, and then vanished from history. The loss was silent in the worst
-   *   way: `sumUsage` and `usageRows` both recurse into the trace, so they summed a
-   *   truncated input and still agreed with each other. Measured at 1 of 7 traces
-   *   kept on a seven-way fan-out, reporting ~2.3x under the real cost, with the
-   *   error growing as the fan-out widens.
-   */
-  private buildHandlerContext(
-    activeToolCallId?: string,
-    traceCapture?: { traces: ChatMessage[][] },
-  ) {
-    return {
-      requestInteraction: <T>(
-        componentName: string,
-        data: any,
-        options?: InteractionRequestOptions,
-      ): Promise<T> => this.requestInteraction(componentName, data, options),
-      ...(this.subAgentsMap.size > 0 && {
-        requestSubAgent: <T = never>(
-          name: string,
-          options?: SubAgentRequestOptions,
-        ): Promise<
-          | { ok: true; result: T; reason?: never }
-          | { ok: false; result?: never; reason: SubAgentFailureReason }
-        > =>
-          this.invokeSubAgent<T>(name, options).then(({ outcome, trace }) => {
-            // Append, never assign: see `traceCapture` on `buildHandlerContext`. Order
-            // is completion order, which is fine — every message carries its own
-            // timestamp and the timeline sorts on that.
-            if (traceCapture && trace) traceCapture.traces.push(trace);
-            return outcome;
-          }),
-      }),
-      completeSubAgent: (result: unknown): void => {
-        if (this.subAgentCompletion) {
-          logger.warn(
-            `ChatDriver(${this.activeAgentName ?? 'unknown'}): completeSubAgent called more than once — ignoring`,
-          );
-          return;
-        }
-        this.subAgentCompletion = { result };
-        // This activation's flow has ended — advance the clock so its
-        // `agentEnd` payloads collapse and a re-run starts a fresh activation.
-        this.currentActivation += 1;
-      },
-      releaseAgent: (): void => {
-        if (this.agentReleaseRequested) {
-          logger.warn(
-            `ChatDriver(${this.activeAgentName ?? 'unknown'}): releaseAgent called more than once — ignoring`,
-          );
-          return;
-        }
-        this.agentReleaseRequested = true;
-        // The stateful flow has wrapped up — advance the clock so its `agentEnd`
-        // payloads collapse and a re-run starts a fresh activation.
-        this.currentActivation += 1;
-      },
-      endPhase: (): void => {
-        // Advance the phase epoch so payloads registered with `{ on: phaseEnd }`
-        // during the phase that just ended collapse on the next provider call.
-        // Repeatable (no once-only guard, unlike releaseAgent/completeSubAgent):
-        // each call opens a fresh phase for subsequent reads to accumulate in.
-        this.currentPhaseEpoch += 1;
-      },
-      condenseWhen: (policy: CondensePolicy): void => {
-        // No addressable tool call (e.g. fold-close handler) — nothing to attach to.
-        if (!activeToolCallId) return;
-        if (!policy?.args && !policy?.response) {
-          logger.warn(
-            `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called with neither args nor response — ignoring`,
-          );
-          return;
-        }
-        const triggers = Array.isArray(policy.on) ? policy.on : [policy.on];
-        const validTrigger = (t: CondenseTrigger | undefined): boolean =>
-          t?.kind === 'superseded'
-            ? typeof t.by === 'string' && t.by.length > 0
-            : t?.kind === 'age'
-              ? typeof t.turns === 'number' && t.turns >= 1
-              : t?.kind === 'turnEnd' || t?.kind === 'agentEnd' || t?.kind === 'phaseEnd';
-        if (triggers.length === 0 || !triggers.every(validTrigger)) {
-          logger.warn(
-            `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called with an invalid trigger — ignoring`,
-          );
-          return;
-        }
-        // First-wins: a handler declares its policy once per call. A second
-        // declaration for the same tool call is a handler bug, not a refinement.
-        if (this.condensePolicies.has(activeToolCallId)) {
-          logger.error(
-            `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called more than once for the same tool call — keeping the first policy, ignoring this one`,
-          );
-          return;
-        }
-        // Stamp the three clocks NOW (read straight off the driver — the handler
-        // runs during the current model-call's tool batch).
-        this.condensePolicies.set(activeToolCallId, {
-          policy,
-          iteration: this.modelCallSeq,
-          turn: this.turnSeq,
-          activation: this.currentActivation,
-          phaseEpoch: this.currentPhaseEpoch,
-        });
-      },
-    };
-  }
-
-  /**
-   * Creates a child `ChatDriver` for the named sub-agent, runs it to completion,
-   * and returns its structured result (or final text fallback) together with the
-   * full child conversation trace. Callers receive both values so each parallel
-   * invocation can capture its own trace without touching shared instance state.
-   */
-  private async invokeSubAgent<T = never>(
-    name: string,
-    options?: SubAgentRequestOptions,
-  ): Promise<{
-    // Closed union (see ChatToolHandlers.requestSubAgent) — keeps `result`/`reason`
-    // accessible for consumers compiled without strictNullChecks.
-    outcome:
-      | { ok: true; result: T; reason?: never }
-      | { ok: false; result?: never; reason: SubAgentFailureReason };
-    trace: ChatMessage[];
-  }> {
-    const subConfig = this.subAgentsMap.get(name);
-    if (!subConfig) {
-      const available = [...this.subAgentsMap.keys()].join(', ') || '(none)';
-      throw new Error(
-        `Sub-agent "${name}" not found on agent "${this.activeAgentName}". Available: ${available}`,
-      );
-    }
-
-    const { task, historyCap, context, timeoutMs } = options ?? {};
-
-    // Exclude the current in-flight assistant message (the one with tool calls that
-    // triggered this invocation) — it has unresolved tool calls that would confuse
-    // the sub-agent into thinking it needs to handle tools it doesn't own.
-    const lastMsg = this.history[this.history.length - 1];
-    const baseHistory =
-      lastMsg?.role === 'assistant' && lastMsg.toolCalls?.length
-        ? this.history.slice(0, -1)
-        : this.history;
-
-    const snapshotHistory =
-      historyCap != null ? applyHistoryCap(baseHistory, historyCap) : [...baseHistory];
-
-    const contextMessages: ChatMessage[] = context
-      ? [{ role: 'user', content: `[Sub-agent context]: ${JSON.stringify(context)}` }]
-      : [];
-
-    const effectivePrimer: ChatMessage[] = [
-      ...snapshotHistory,
-      ...contextMessages,
-      ...(subConfig.primerHistory ?? []),
-    ];
-
-    // Unique per-invocation id — reused for the lifecycle event bracket below —
-    // and a child session key derived from it. The child files its meta events
-    // under this own bucket (rather than the shared empty-key sink), so they can
-    // be harvested into THIS session on completion and then discarded.
-    const invocationId = crypto.randomUUID();
-    const childSessionKey = `${this.sessionKey}::sub:${invocationId}`;
-    const child = new ChatDriver(this.providerRegistry, {
-      sessionKey: childSessionKey,
-      // Inherit the parent's bus so the sub-agent's tool-loop events still surface
-      // (off-browser this is the shared no-op).
-      activityBus: this.activityBus,
-    });
-    // Mark before the first turn so the child forces tool use and reports a
-    // typed failure (rather than user-facing text) if it never completes.
-    child.markAsSubAgent();
-    // Propagate disposal: if this (parent) driver is torn down while the
-    // sub-agent is mid-flight, dispose the child too so its in-flight request
-    // aborts. Detached in the `finally` below once the sub-agent completes.
-    const disposeChild = () => child.dispose();
-    if (this.lifecycleController.signal.aborted) {
-      disposeChild();
-    } else {
-      this.lifecycleController.signal.addEventListener('abort', disposeChild, { once: true });
-    }
-    child.applyAgent({ ...subConfig, primerHistory: effectivePrimer });
-    // Route interactions back through this driver so widgets render in the
-    // parent's (ultimately the root's) history and resolve via the same
-    // pending map the main UI is wired to. Recurses naturally for nested
-    // sub-agents.
-    child.setHostInteractionRequester(
-      <R>(componentName: string, data: any, opts?: InteractionRequestOptions): Promise<R> =>
-        this.requestInteraction<R>(componentName, data, opts),
-    );
-
-    const forwardTrace = (e: Event) => {
-      this.dispatchEvent(
-        new CustomEvent('sub-agent-history-updated', {
-          detail: { agentName: subConfig.name, history: (e as CustomEvent<ChatMessage[]>).detail },
-        }),
-      );
-    };
-    // Re-dispatch the child's `provider-changed` so the UI reflects whichever
-    // provider is *actually* running right now (the sub-agent may use a
-    // different provider than the parent). Restoration of the parent's
-    // provider on `sub-agent-stop` is handled by the listener in main.ts.
-    const forwardProviderChanged = (e: Event) => {
-      this.dispatchEvent(
-        new CustomEvent('provider-changed', { detail: (e as CustomEvent).detail }),
-      );
-    };
-    child.addEventListener('history-updated', forwardTrace);
-    child.addEventListener('provider-changed', forwardProviderChanged);
-
-    const chatInputDuringExecution = options?.chatInputDuringExecution;
-    const lifecycleDetail = { name, invocationId, chatInputDuringExecution };
-
-    this.dispatchEvent(new CustomEvent('sub-agent-start', { detail: lifecycleDetail }));
-    // Bracket the run on the timeline (mirrors turn.start/turn.end). Recorded
-    // under THIS (parent) session — like subagent.completed/failed below — so the
-    // sub-agent's span is visible on the user-facing timeline, not the child's.
-    recordMetaEvent(this.sessionKey, 'subagent.started', { agent: name });
-    let timedOut = false;
-    const runPromise = child.sendMessage(task ?? '');
-    try {
-      if (timeoutMs == null) {
-        await runPromise;
-      } else {
-        // Race the run against the deadline. On timeout, abort the child (which
-        // cancels its in-flight provider request) and let the aborted run settle
-        // before we tear down and return the timeout outcome.
-        let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-        try {
-          const timeoutSignal = new Promise<'timeout'>((resolveTimeout) => {
-            timeoutHandle = setTimeout(() => resolveTimeout('timeout'), timeoutMs);
-          });
-          const winner = await Promise.race([
-            runPromise.then(() => 'done' as const),
-            timeoutSignal,
-          ]);
-          if (winner === 'timeout') {
-            timedOut = true;
-            child.dispose();
-            // The sub-agent may be parked awaiting a user interaction, which is
-            // routed up to this driver and parked in *this* pending map (widgets
-            // resolve on the host, not the child). Disposing the child does not
-            // settle that promise, so the child stays suspended — cancel the
-            // 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.`);
-            await runPromise.catch(() => undefined);
-          }
-        } finally {
-          // Always clear the timer — even if the race rejects — so it never leaks.
-          if (timeoutHandle) clearTimeout(timeoutHandle);
-        }
-      }
-    } finally {
-      this.lifecycleController.signal.removeEventListener('abort', disposeChild);
-      child.removeEventListener('history-updated', forwardTrace);
-      child.removeEventListener('provider-changed', forwardProviderChanged);
-      // Tear the child down on every exit path, not just timeout/parent-abort.
-      // A child that completes normally is otherwise never disposed, so its
-      // provider-registry subscription (wired in the ChatDriver constructor)
-      // would leak — the long-lived registry would retain every completed
-      // sub-agent driver. dispose() is idempotent and only aborts the (already
-      // settled) lifecycle, so the snapshot/completion reads below still work.
-      child.dispose();
-      this.dispatchEvent(new CustomEvent('sub-agent-stop', { detail: lifecycleDetail }));
-      // Capture the child's diagnostics into THIS session, then ALWAYS discard its
-      // transient bucket — done in the `finally` so an unexpected `sendMessage`
-      // rejection (which propagates out of this method) can't orphan the bucket in
-      // 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());
-      // 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
-      // bracket. Each is breadcrumbed `"<parent> › <sub-agent>"`, composing for a
-      // nested sub-agent whose own breadcrumb the child already merged.
-      const parentName = this.activeAgentName ?? '?';
-      const harvested = getMetaEvents(childSessionKey)
-        .filter((e) => HARVESTED_SUBAGENT_EVENTS.has(e.type))
-        .map((e) => {
-          const existing = e.detail?.subAgent as string | undefined;
-          return { ...e, detail: { ...e.detail, subAgent: `${parentName} › ${existing ?? name}` } };
-        });
-      mergeMetaEvents(this.sessionKey, harvested);
-      clearSession(childSessionKey);
-    }
-
-    const trace = child.getHistory() as ChatMessage[];
-
-    if (timedOut) {
-      // Same failure shape as any other non-completion — the parent handler
-      // recovers on its existing `{ ok: false }` branch. Recorded under THIS
-      // (parent) session so it lands on the user-visible debug-log timeline.
-      recordMetaEvent(this.sessionKey, 'subagent.failed', { agent: name, reason: 'timeout' });
-      return { outcome: { ok: false, reason: 'timeout' }, trace };
-    }
-
-    const completion = child.getSubAgentCompletion();
-
-    if (completion) {
-      recordMetaEvent(this.sessionKey, 'subagent.completed', { agent: name });
-      return { outcome: { ok: true, result: completion.result as T }, trace };
-    }
-
-    // No completion → the sub-agent's loop ended without calling its completion
-    // tool. Surface the typed reason it recorded; default to 'max_iterations'
-    // for the defensive case where the loop ended with no reason set (e.g. a
-    // provider ignored forced tool use and returned text). The previous
-    // final-text fallback is intentionally gone — sub-agents return a
-    // structured outcome only, and the parent handler decides how to recover.
-    const failure = child.getSubAgentFailure();
-    const reason = failure?.reason ?? 'max_iterations';
-    // Record under THIS (parent) driver's session so the failure lands on the
-    // user-visible debug-log timeline — the child ran under its own session key.
-    // This is also the only telemetry for the defensive default above, where the
-    // child's loop ended without recording an explicit failure reason.
-    recordMetaEvent(this.sessionKey, 'subagent.failed', { agent: name, reason });
-    // A child that hit the budget wall walls this driver too — the cap is shared,
-    // and the parent's very next model call would 402 as well. Flagged (not
-    // thrown) because the handler's return value is still appended as a tool
-    // result: the loop reads the flag before the next provider call and ends the
-    // turn there, which is what makes the `'budget_exhausted'` doc's "terminal
-    // for the parent too" actually true.
-    //
-    // The child's attribution is inherited with it: the vendor that refused is
-    // the child's, which under a mixed registry is not this driver's. See
-    // `budgetWallDetail` for what mis-attributing it costs.
-    //
-    // FIRST attribution wins (`??=`). With batched delegations, child A walling
-    // WITH attribution can be followed by child B walling WITHOUT one (a
-    // figure-less 402 behind a transport label no vendor claims); a plain
-    // assignment reset the field to `undefined` and the short-circuit's
-    // fallback then named the parent's own vendor — the one known NOT to have
-    // refused.
-    if (reason === 'budget_exhausted') {
-      this.budgetExhaustedThisTurn = true;
-      this.budgetWallViaSubAgent = true;
-      this.budgetWallDetail ??= failure?.budget;
-    }
-    // The PROVIDER wall via a child (GENC-1506) — the same shape as the budget wall above, and needed
-    // for the same non-obvious reason: **the child is a separate driver instance**, so the flag it set
-    // on itself is invisible here. Without this branch the child's failure was appended as an ordinary
-    // tool result, the parent's short-circuit never fired, and the parent issued another model call
-    // straight into the same wall. Worse, if that call happened to succeed the turn could finish
-    // WITHOUT `failureReason: 'provider-refused'` at all — reporting a clean turn over a dead account.
-    //
-    // FIRST attribution wins (`??=`), for the reason spelled out on `budgetWallDetail`: batched
-    // delegations can pair an attributable child refusal with an unattributable one, and a plain
-    // assignment would let the later `undefined` erase what the earlier child knew.
-    if (reason === 'provider_refused') {
-      this.providerRefusedThisTurn = true;
-      this.providerRefusedDetail ??= failure?.providerRefused;
-    }
-    return { outcome: { ok: false, reason }, trace };
-  }
-
-  /**
-   * Continue the tool loop from current history without appending a new user message.
-   * Used by OrchestratingDriver after an agent handoff.
-   */
-  async continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult> {
-    if (this.busy) return { reason: 'done' };
-
-    this.busy = true;
-    this.beginTurn();
-    this.subAgentCompletion = undefined;
-    this.subAgentFailure = undefined;
-    this.budgetExhaustedThisTurn = false;
-    this.budgetWallDetail = undefined;
-    this.budgetWallViaSubAgent = false;
-    this.providerRefusedThisTurn = false;
-    this.providerRefusedDetail = undefined;
-    this.turnStartedAt = Date.now();
-    recordMetaEvent(this.sessionKey, 'turn.start', {
-      phase: 'continueFromHistory',
-      agent: this.activeAgentName,
-    });
-    this.activityBus.publish('tool-loop-start', undefined);
-    // Captured so the `finally` can carry the turn's outcome onto `tool-loop-end`.
-    let result: ChatDriverResult = { reason: 'done' };
-    try {
-      result = await this.runToolLoop('', undefined, transientPrimer);
-      return result;
-    } catch (e) {
-      logger.error('ChatDriver error:', e);
-      recordTurnError(this.sessionKey, 'exception', {
-        phase: 'continueFromHistory',
-        agent: this.activeAgentName,
-        provider: this.lastResolvedProviderName,
-        name: e instanceof Error ? e.name : undefined,
-        message: e instanceof Error ? e.message : String(e),
-      });
-      this.appendToHistory({
-        role: 'assistant',
-        content: 'Sorry, something went wrong on my end. Please try again in a moment.',
-      });
-      result = this.turnDone('exception');
-      return result;
-    } finally {
-      recordMetaEvent(this.sessionKey, 'turn.end', {
-        phase: 'continueFromHistory',
-        agent: this.activeAgentName,
-        durationMs: Date.now() - this.turnStartedAt,
-      });
-      this.busy = false;
-      this.endTurn();
-      this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
-    }
-  }
-
-  // ---------------------------------------------------------------------------
-  // Fold mechanics
-  // ---------------------------------------------------------------------------
-
-  /** Extract ToolFold metadata from a handler, or undefined if it isn't a fold facade. */
-  private getFold(toolName: string): ToolFold | undefined {
-    const handler = this.toolHandlers[toolName];
-    return handler ? ((handler as any)[TOOL_FOLD_SYMBOL] as ToolFold | undefined) : undefined;
-  }
-
-  /**
-   * Search all currently registered fold facades (and their nested folds recursively)
-   * to find which fold contains a given tool name. Returns the immediate parent fold name.
-   */
-  private findFoldContaining(toolName: string, handlers?: ChatToolHandlers): string | null {
-    const source = handlers ?? this.toolHandlers;
-    for (const [, handler] of Object.entries(source)) {
-      const fold = (handler as any)[TOOL_FOLD_SYMBOL] as ToolFold | undefined;
-      if (!fold) continue;
-      // Direct inner tool match
-      if (fold.handlers[toolName]) return fold.name;
-      // Recurse into nested folds
-      const nested = this.findFoldContaining(toolName, fold.handlers);
-      if (nested) return fold.name;
-    }
-    return null;
-  }
-
-  /**
-   * If an open fold is hiding a previously-available tool, return the name of
-   * the fold to close to start getting it back. Only exclusive folds hide tools
-   * (they replace the tool set on open rather than extending it), so a base tool
-   * that was visible before the fold opened now sits in a fold-stack frame's
-   * `previousHandlers` but not in the live handler map. Only the top fold's
-   * `close_` tool is active, so that's always the actionable next step — even
-   * when the tool lives further down the stack, closing repeatedly walks back to
-   * it. Returns null when no open fold accounts for the tool.
-   */
-  private foldHidingTool(toolName: string): string | null {
-    if (this.foldStack.length === 0) return null;
-    const hidden = this.foldStack.some((f) => f.previousHandlers[toolName]);
-    return hidden ? this.foldStack[this.foldStack.length - 1].foldName : null;
-  }
-
-  /**
-   * Install the fold's inner tool set, replacing (exclusive) or extending (non-exclusive)
-   * the current tool set. Also injects the close tool. Does NOT touch the fold stack.
-   */
-  private applyFoldToolSet(fold: ToolFold, foldName: string): void {
-    const closeToolName = `close_${foldName}`;
-    const newDefs: ChatToolDefinition[] = [];
-    const newHandlers: ChatToolHandlers = {};
-
-    if (!fold.exclusive) {
-      // Non-exclusive: keep existing tools minus the facade we just opened
-      for (const def of this.toolDefinitions) {
-        if (def.name !== foldName) newDefs.push(def);
-      }
-      for (const [name, handler] of Object.entries(this.toolHandlers)) {
-        if (name !== foldName) newHandlers[name] = handler;
-      }
-    }
-
-    // Install inner tools from fold metadata
-    newDefs.push(...fold.tools);
-    Object.assign(newHandlers, fold.handlers);
-
-    // Inject the close tool
-    newDefs.push({
-      name: closeToolName,
-      description: `Close the ${foldName} fold and return to the previous set of tools.`,
-      parameters: { type: 'object', properties: {} },
-    });
-    newHandlers[closeToolName] = async (): Promise<string> => this.closeFold();
-
-    this.toolDefinitions = newDefs;
-    this.toolHandlers = newHandlers;
-  }
-
-  /** Open a fold: push a stack frame, swap the tool set, return the response message. */
-  private openFold(
-    foldName: string,
-    fold: ToolFold,
-    args: Record<string, unknown>,
-    activeToolCallId?: string,
-  ): Promise<string> {
-    // Shortcut dispatch: model passed inner tool args directly, e.g.
-    // trading_tools({ search_trades: { side: "BUY" } })
-    for (const key of Object.keys(args)) {
-      const innerHandler = fold.handlers[key];
-      if (innerHandler) {
-        logger.debug(`ChatDriver: fold shortcut dispatch "${foldName}" → "${key}"`);
-        // Open the fold first so the tool set is correct for subsequent calls
-        this.pushFoldFrame(foldName);
-        this.applyFoldToolSet(fold, foldName);
-        this.consecutiveFoldOps = 0; // shortcut dispatch counts as real work
-        const innerArgs =
-          typeof args[key] === 'object' && args[key] !== null
-            ? (args[key] as Record<string, unknown>)
-            : {};
-        return innerHandler(innerArgs, this.buildHandlerContext(activeToolCallId)).then((r) =>
-          typeof r === 'string' ? r : JSON.stringify(r),
-        );
-      }
-    }
-
-    // Normal two-step open
-    this.pushFoldFrame(foldName);
-    this.applyFoldToolSet(fold, foldName);
-
-    const innerToolNames = fold.tools.map((t) => t.name);
-    const closeToolName = `close_${foldName}`;
-    let message = `Fold opened: ${foldName}. Tools now available: ${[...innerToolNames, closeToolName].join(', ')}.`;
-    if (fold.usageNotes) message += ` Notes: ${fold.usageNotes}`;
-    message += ` Call ${closeToolName} when done to return to the previous tools.`;
-    return Promise.resolve(message);
-  }
-
-  private pushFoldFrame(foldName: string): void {
-    this.foldStack.push({
-      foldName,
-      previousDefinitions: [...this.toolDefinitions],
-      previousHandlers: { ...this.toolHandlers },
-    });
-  }
-
-  /** Close the top fold: pop the stack frame, restore the previous tool set. */
-  private closeFold(): string {
-    const frame = this.foldStack.pop();
-    if (!frame) return 'No fold is currently open.';
-
-    this.toolDefinitions = frame.previousDefinitions;
-    this.toolHandlers = frame.previousHandlers;
-
-    const toolNames = this.toolDefinitions.map((t) => t.name);
-    return `Fold closed: ${frame.foldName}. Tools now available: ${toolNames.join(', ')}.`;
-  }
-
-  /** Build the fold-awareness suffix appended to the system prompt each LLM call. */
-  private buildFoldSystemPromptSuffix(): string {
-    // Collect fold facades from the current handler map
-    const activeFolds: ToolFold[] = [];
-    for (const handler of Object.values(this.toolHandlers)) {
-      const fold = (handler as any)[TOOL_FOLD_SYMBOL] as ToolFold | undefined;
-      if (fold) activeFolds.push(fold);
-    }
-
-    if (activeFolds.length === 0 && this.foldStack.length === 0) return '';
-
-    const parts: string[] = ['\n\n--- Tool Folds ---'];
-    parts.push(
-      'Some tools are grouped into folds. You may see tool calls in the conversation history for tools that are not currently available — they are inside a fold. To access them, invoke the fold tool first.',
-    );
-
-    if (this.foldStack.length > 0) {
-      const current = this.foldStack[this.foldStack.length - 1];
-      parts.push(
-        `You are currently inside the "${current.foldName}" fold. Call close_${current.foldName} when you are done with these tools.`,
-      );
-    }
-
-    for (const fold of activeFolds) {
-      parts.push(`• ${fold.name}: ${fold.description}`);
-    }
-
-    return parts.join('\n');
-  }
-
-  // ---------------------------------------------------------------------------
-  // Tool loop
-  // ---------------------------------------------------------------------------
-
-  // oxlint-disable-next-line complexity
-  private async runToolLoop(
-    userInput: string,
-    attachments?: ChatAttachment[],
-    transientPrimer?: ChatMessage[],
-  ): Promise<ChatDriverResult> {
-    if (!this.systemPrompt) {
-      logger.warn(
-        'ChatDriver: no systemPrompt set. The assistant will have no instructions — provide a systemPrompt via agents config or the foundation-ai-assistant property.',
-      );
-    }
-
-    let currentInput = userInput;
-    let currentAttachments: ChatAttachment[] | undefined = attachments;
-    let iterations = 0;
-    let malformedAttempts = 0;
-    let emptyResponseAttempts = 0;
-    // Bounded retries for transient throws while resolving the per-turn tool surface or
-    // calling the provider. Without this, a single transient throw tears down the whole turn
-    // and strands the agent's unflushed work behind an opaque error.
-    let setupTransportAttempts = 0;
-    // True only for the very first LLM call. Used to exclude the pending user message
-    // from history (it is passed separately as currentInput). Must not be derived from
-    // `iterations` because fold operations decrement iterations, which would incorrectly
-    // re-trigger the slice on subsequent calls after a fold open/close.
-    let firstLlmCall = !!currentInput;
-    // Thinking posture for this WHOLE turn, resolved on the first model call and then held.
-    //
-    // Unlike temperature or toolChoice, this one cannot vary per iteration: a tool-use loop is
-    // a single assistant turn, and Anthropic requires one thinking mode for its duration.
-    // Toggling mid-loop does not error — the API silently disables thinking for that request
-    // and strips blocks that would leave the turn structure invalid, so an `'auto' -> 'off'`
-    // switch loses the reasoning continuity the opening call established while an
-    // `'off' -> 'auto'` switch simply does not deliver the reasoning asked for. It also
-    // invalidates the prompt cache, which costs more than the reasoning it was meant to save.
-    // Resolved per USER turn instead, which is where the docs say to choose it.
-    let pinnedThinkingPolicy: ChatThinkingPolicy | undefined;
-    let thinkingPolicyPinned = false;
-
-    while (iterations < this.maxToolIterations) {
-      iterations += 1;
-      // Monotonic across the driver's life — the age clock. Unlike `iterations`,
-      // it is NOT reset per turn and NOT decremented for folds, so `age` keeps
-      // counting model-calls once a turn ends. (See the `modelCallSeq` field.)
-      this.modelCallSeq += 1;
-
-      // A cancel (or dispose) that landed while the previous iteration's tool
-      // batch was running takes effect here — before issuing another LLM call.
-      // An abort during the call itself is handled by the catch below.
-      if (this.turnController.signal.aborted) {
-        return this.completeAbortedTurn();
-      }
-
-      // A budget wall observed earlier this turn ends it HERE, before another
-      // model call. Reachable only via a sub-agent (this driver's own 402
-      // returns straight out of the catch below) — `invokeSubAgent` sets the
-      // flag, its `{ ok: false, reason: 'budget_exhausted' }` outcome is
-      // appended as a tool result, and without this the loop would call the
-      // provider again into the same wall: N batched sub-agent calls otherwise
-      // cost N doomed children AND a doomed parent call.
-      //
-      // Scoped strictly to the budget reason: every other SubAgentFailureReason
-      // is something the parent can legitimately recover from, so those still
-      // let the loop continue.
-      // A provider refusal seen earlier this turn ends it HERE, before another model call. Reachable
-      // only via a sub-agent — this driver's own refusal returns straight out of the catch — and
-      // without it the loop would call the provider again into the same wall (GENC-1506).
-      if (this.providerRefusedThisTurn) {
-        logger.error('ChatDriver: ending the turn — a sub-agent hit the provider wall');
-        recordTurnError(this.sessionKey, 'provider-refused', {
-          agent: this.activeAgentName,
-          provider: this.lastResolvedProviderName,
-          kind: this.providerRefusedDetail?.kind,
-          via: 'sub-agent',
-          isSubAgent: this.isSubAgent,
-        });
-        if (this.isSubAgent) {
-          // The detail is forwarded, not just the reason — this driver may itself be an INTERMEDIATE
-          // sub-agent, and a refusal that started in a grandchild reaches its own parent only through
-          // this call. Dropping it here still stopped the top-level turn (the reason travels), but
-          // arrived with no vendor and no kind, which is the whole diagnostic this payload exists to
-          // carry across hops. The adjacent budget path forwards `budgetWallDetail` for the same reason.
-          this.failSubAgent('provider_refused', undefined, this.providerRefusedDetail);
-        } else {
-          this.appendToHistory({ role: 'assistant', content: this.providerRefusedBubble() });
-        }
-        return this.turnDone('provider-refused', undefined, this.providerRefusedDetail);
-      }
-      if (this.budgetExhaustedThisTurn) {
-        logger.error('ChatDriver: ending the turn — a sub-agent hit the AI budget wall');
-        recordTurnError(this.sessionKey, 'budget-exhausted', {
-          agent: this.activeAgentName,
-          provider: this.lastResolvedProviderName,
-          // The CHILD's vendor when it knew one, and NOTHING otherwise. On this
-          // path the wall is definitionally the child's, and on a mixed registry
-          // `lastResolvedProvider` is this driver's own vendor — the one known
-          // NOT to have refused. An unattributable child wall must degrade to
-          // the vendor-agnostic block (which `latchBlockedFrom` handles
-          // fail-safe), never to a vendor that is known to be wrong: naming the
-          // parent's vendor here walled BOTH — the child's via its own
-          // tool-loop-end, the parent's via this event — and derived `blocked`
-          // over headroom that still existed.
-          vendor: this.budgetWallDetail?.vendor,
-          via: 'sub-agent',
-          isSubAgent: this.isSubAgent,
-        });
-        if (this.isSubAgent) {
-          this.failSubAgent('budget_exhausted', this.budgetWallDetail);
-        } else {
-          // Composed from the DETAIL, not an error object: on this path the wall
-          // arrived as a sub-agent's failure payload — `budgetWallDetail`, first
-          // attribution wins — and an unattributable child wall (detail
-          // undefined) composes the neutral default.
-          this.appendToHistory({
-            role: 'assistant',
-            content: this.budgetExhaustedBubble(this.budgetWallDetail),
-          });
-        }
-        // Carried onto the result so `loopEndDetail` publishes the refusing
-        // vendor rather than falling through to `lastResolvedProvider`, and the
-        // host's latch walls the vendor that actually ran out.
-        return this.turnDone('budget-exhausted', this.budgetWallDetail);
-      }
-
-      const promptCtx: SystemPromptContext = {
-        agentName: this.activeAgentName ?? '',
-        history: this.history,
-        turnIndex: iterations - 1,
-        signal: this.turnController.signal,
-      };
-
-      // Re-resolve dynamic tool definitions before each LLM call. The static
-      // case is a no-op (factory is undefined and `this.toolDefinitions` was
-      // set by applyAgent). Folds operate on `this.toolDefinitions` and are
-      // forbidden when a factory is set, so the array form is always valid.
-      // Sequential await is required — each iteration must see fresh values
-      // before constructing the LLM request.
-      // A transient throw while building the tool surface should retry the iteration, not
-      // tear down the whole turn and strand the agent's unflushed buffer behind an opaque
-      // error. The handler-map factory re-resolves in lockstep so dispatch sees only the
-      // handlers valid for the current state, in step with the tool definitions exposed
-      // above. Folds are forbidden when either factory is set, so the fold-mutation paths
-      // on `this.toolDefinitions` / `this.toolHandlers` are unreachable.
-      try {
-        if (this.toolDefinitionsFactory) {
-          // oxlint-disable-next-line no-await-in-loop
-          this.toolDefinitions = await this.toolDefinitionsFactory(promptCtx);
-        }
-        if (this.toolHandlersFactory) {
-          // oxlint-disable-next-line no-await-in-loop
-          this.toolHandlers = await this.toolHandlersFactory(promptCtx);
-        }
-      } catch (e) {
-        setupTransportAttempts += 1;
-        if (setupTransportAttempts < MAX_SETUP_TRANSPORT_RETRIES) {
-          logger.warn(
-            `ChatDriver: tool-surface resolution failed, retrying (${setupTransportAttempts}/${MAX_SETUP_TRANSPORT_RETRIES})`,
-          );
-          iterations -= 1;
-          continue;
-        }
-        throw e;
-      }
-
-      // Record everything advertised this turn so the unknown-tool path can tell
-      // a stale tool (real earlier, retired now) from a hallucinated one. Runs
-      // for both the static and factory cases; folds also flow through here as
-      // their inner tools become visible on the iteration after they open.
-      for (const def of this.toolDefinitions) this.everSeenToolNames.add(def.name);
-
-      const resolvedSystemPrompt =
-        typeof this.systemPrompt === 'function'
-          ? // oxlint-disable-next-line no-await-in-loop
-            await this.systemPrompt(promptCtx)
-          : this.systemPrompt;
-
-      // Re-resolve the per-turn display label. Falls back to the canonical
-      // agent name when displayName is unset. Stamped onto outgoing messages
-      // and turn snapshots for UX only; routing/history-transform continues
-      // to read `activeAgentName`.
-      if (typeof this.displayName === 'function') {
-        // oxlint-disable-next-line no-await-in-loop
-        this.activeAgentLabel = await this.displayName(promptCtx);
-      }
-
-      // Volatile framework additions — the fold-surface suffix and the per-attempt malformed/empty
-      // retry nudge — that would otherwise destabilize a cached system prompt. They are routed to
-      // the framed tail (below), never appended to the system string, so the system prompt stays
-      // byte-stable for every agent.
-      const foldSuffix = this.buildFoldSystemPromptSuffix();
-      const retryNudge =
-        malformedAttempts > 0
-          ? '\n\nIMPORTANT: Use only the structured function-call API to invoke tools. Do not write Python code or use Python-style syntax to call tools.'
-          : emptyResponseAttempts > 0
-            ? "\n\nIMPORTANT: You must respond to the user's message. Call the appropriate tool or provide a text response — do not return an empty response."
-            : '';
-      const frameworkSystemSuffix = `${foldSuffix}${retryNudge}`;
-
-      // Normalize the primer at the same chokepoint as the driver's own history
-      // (GENC-1351 §5.7): a parent's `compacted-summary` message rides into a
-      // sub-agent's primer (`requestSubAgent` snapshots the parent's raw history),
-      // and it must be translated to a `<conversation_summary>` user message here —
-      // otherwise the transports' role filter silently drops it and the sub-agent
-      // loses all summarized context. `normalizeForProvider` only touches
-      // `compacted-summary`, so it's a safe pass-through for everything else.
-      const primer = normalizeForProvider([
-        ...(this.primerHistory ?? []),
-        ...(transientPrimer ?? []),
-      ]);
-      const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
-      firstLlmCall = false;
-      // Collapse stale tool payloads this agent declared via `condenseWhen`
-      // (GENC-1369), then translate any compacted-summary → a
-      // <conversation_summary> user message (GENC-1351 §5.7) before any per-agent
-      // masking, so the raw display-only role can never reach a transport. Each
-      // step runs on a copy — stored history is untouched.
-      const condensedHistory = applyCondensation(
-        [...baseHistory],
-        this.condensePolicies,
-        {
-          modelCall: this.modelCallSeq,
-          turn: this.turnSeq,
-          // A call's activation has ended once a later activation is current — a
-          // swap or release/complete both advance the counter.
-          activationEnded: (activation) => activation < this.currentActivation,
-          // A call's phase has ended once the app declared a later phase epoch
-          // current via `endPhase()`.
-          phaseEnded: (phaseEpoch) => phaseEpoch < this.currentPhaseEpoch,
-          batchCalls: this.condenseBatchCalls,
-        },
-        (detail) => recordMetaEvent(this.sessionKey, 'context.condensed', detail),
-      );
-      const normalizedHistory = normalizeForProvider(condensedHistory);
-      const historyForProvider = this.providerHistoryTransform
-        ? this.providerHistoryTransform(normalizedHistory)
-        : normalizedHistory;
-      const historyForCall = [...primer, ...historyForProvider];
-
-      // Resolve the per-turn temperature and tool-call mode the same way the
-      // provider is resolved — static value or a function of the turn context
-      // (which carries the live state for stateful agents). Resolved before the
-      // snapshot so the debug log records the exact request config the model saw.
-      const [
-        resolvedTemperature,
-        resolvedToolChoice,
-        resolvedCachePolicy,
-        resolvedTailContext,
-        resolvedResponseSchema,
-        firstResolvedThinkingPolicy,
-      ] =
-        // oxlint-disable-next-line no-await-in-loop
-        await Promise.all([
-          this.resolveTurnInput<number>(this.activeTemperatureInput, promptCtx),
-          this.resolveTurnInput<ChatToolChoice>(this.activeToolChoiceInput, promptCtx),
-          this.resolveTurnInput<CachePolicy>(this.activeCachePolicyInput, promptCtx),
-          this.resolveTurnInput<string>(this.activeTailContextInput, promptCtx),
-          this.resolveTurnInput<object | undefined>(this.activeResponseSchemaInput, promptCtx),
-          // Only consulted on the first iteration (see `pinnedThinkingPolicy`); resolved
-          // alongside the others so a resolver still sees the same turn context.
-          thinkingPolicyPinned
-            ? Promise.resolve(undefined)
-            : this.resolveTurnInput<ChatThinkingPolicy | undefined>(
-                this.activeThinkingPolicyInput,
-                promptCtx,
-              ),
-        ]);
-      if (!thinkingPolicyPinned) {
-        pinnedThinkingPolicy = firstResolvedThinkingPolicy;
-        thinkingPolicyPinned = true;
-      }
-      // The system prompt is always just the agent's resolved prompt — byte-stable, so it can be
-      // cached. The framework's volatile additions (fold suffix, retry nudge) and the agent's tail
-      // context all go to the framed tail: one uniform channel, no cache-scope branch. On a normal
-      // turn `frameworkSystemSuffix` is empty, so the tail is empty too — a no-op. The framework
-      // owns the framing; the corrective retry nudge lands last (recency).
-      const systemPrompt = resolvedSystemPrompt || undefined;
-      const tailBody = [resolvedTailContext, frameworkSystemSuffix]
-        .map((part) => (part ?? '').trim())
-        .filter((part) => part.length > 0)
-        .join('\n\n');
-      const tailContext = tailBody
-        ? `<system-reminder>\n${tailBody}\n</system-reminder>`
-        : undefined;
-      // An agent/state-configured tool-call mode wins. Otherwise sub-agents must
-      // finish by calling a tool (their completion tool) so the turn can't end
-      // on a free-text answer; top-level agents stay 'auto'. (Transports no-op a
-      // force when no tools are advertised.)
-      const effectiveToolChoice = resolvedToolChoice ?? (this.isSubAgent ? 'required' : undefined);
-
-      const turnSnapshot = this.recordTurnSnapshot(
-        systemPrompt,
-        resolvedTemperature,
-        effectiveToolChoice,
-        tailContext,
-      );
-
-      // 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 —
-      // otherwise the message gets sent twice (once via history, once via
-      // `currentInput`), which Gemini answers with an empty response and then
-      // we retry forever.
-      const userInputForCall = currentInput;
-      const attachmentsForCall = currentAttachments;
-      currentInput = '';
-      currentAttachments = undefined;
-
-      const options: ChatRequestOptions = {
-        systemPrompt,
-        // Strip fold-only properties (foldEvent, foldPath) before sending to provider
-        tools: this.toolDefinitions.length ? this.toolDefinitions : undefined,
-        attachments: attachmentsForCall,
-        // Per-turn signal: aborts on user cancel, and (via beginTurn's chain)
-        // on driver dispose. Cancels the in-flight request either way.
-        signal: this.turnController.signal,
-        toolChoice: effectiveToolChoice,
-        // Agent/state-configured sampling temperature (normalized 0–1); each
-        // transport translates it to its native range. Undefined → provider default.
-        temperature: resolvedTemperature,
-        // Prompt-cache policy for this turn (Anthropic places breakpoints per scope; Gemini
-        // caches implicitly regardless). Undefined → no caching requested.
-        cachePolicy: resolvedCachePolicy,
-        // Extended-thinking posture, pinned for the whole tool loop (one assistant turn) rather
-        // than re-resolved per iteration — see `pinnedThinkingPolicy`. Undefined — unset, or the
-        // resolver's answer for this turn — is NOT "off": it leaves the model on its own default,
-        // so agents that never set this are priced exactly as before. Transports clamp models
-        // that can't honour it.
-        thinkingPolicy: pinnedThinkingPolicy,
-        // Framed volatile context injected at the message tail (never stored). Undefined → none.
-        tailContext,
-        // Structured-output schema for this turn (agent/state-resolved). When set, the transport
-        // constrains the final answer to it natively where the model supports it. Undefined → free text.
-        responseSchema: resolvedResponseSchema,
-        // Refusal-fallback chain (e.g. Fable 5 → Opus 4.8). Passed to the provider; applied
-        // server-side where supported. Undefined → no fallback.
-        fallbacks: this.activeFallbacks,
-      };
-
-      // Resolve the active provider for this turn. Static names were validated
-      // in `applyAgent`; function-form names are validated on first resolution
-      // here and cached for the agent's lifetime.
-      // oxlint-disable-next-line no-await-in-loop
-      const activeProvider = await 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
-      // `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
-      // response lands (see below); until then — and on a call that throws — it is the
-      // model we ASKED for, which is the only thing knowable at that point.
-      if (this.lastResolvedProviderName !== undefined) {
-        turnSnapshot.providerName = this.lastResolvedProviderName;
-      }
-      if (this.lastResolvedProvider !== undefined)
-        turnSnapshot.provider = this.lastResolvedProvider;
-      if (this.lastResolvedModel !== undefined) turnSnapshot.model = this.lastResolvedModel;
-
-      let response: ChatMessage;
-      try {
-        // oxlint-disable-next-line no-await-in-loop
-        response = await activeProvider.chat!(historyForCall, userInputForCall, options);
-      } catch (e) {
-        if (e instanceof MalformedFunctionCallError) {
-          malformedAttempts += 1;
-          if (malformedAttempts < MAX_MALFORMED_RETRIES) {
-            logger.warn(
-              `ChatDriver: MALFORMED_FUNCTION_CALL, retrying (${malformedAttempts}/${MAX_MALFORMED_RETRIES})`,
-            );
-            recordTurnRetry(this.sessionKey, 'malformed-function-call', {
-              agent: this.activeAgentName,
-              provider: this.lastResolvedProviderName,
-              attempt: malformedAttempts,
-              maxAttempts: MAX_MALFORMED_RETRIES,
-              finishMessage: e.finishMessage,
-            });
-            iterations -= 1;
-            continue;
-          }
-          logger.error('ChatDriver: MALFORMED_FUNCTION_CALL, max retries reached');
-          recordTurnError(this.sessionKey, 'malformed-function-call', {
-            agent: this.activeAgentName,
-            provider: this.lastResolvedProviderName,
-            attempts: malformedAttempts,
-            finishMessage: e.finishMessage,
-            isSubAgent: this.isSubAgent,
-          });
-          if (this.isSubAgent) {
-            // Bubble a typed failure to the parent instead of speaking to the user.
-            this.failSubAgent('malformed_tool_call');
-          } else {
-            this.appendToHistory({
-              role: 'assistant',
-              content:
-                'While working on your request, I repeatedly called my tools incorrectly. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
-            });
-          }
-          return this.turnDone('malformed-function-call');
-        }
-        // The response was truncated at the provider's output-token cap while it
-        // still carried a tool call — its arguments are incomplete and unusable.
-        // Unlike a malformed call this is DETERMINISTIC: re-issuing the same
-        // request hits the same cap, so a silent retry just loops. Bail with a
-        // clear, actionable signal instead. The remedy is config (raise the
-        // provider maxTokens) or a smaller step — neither is fixed by retrying.
-        if (e instanceof ResponseTruncatedError) {
-          logger.error('ChatDriver: response truncated at the output-token cap', e);
-          recordTurnError(this.sessionKey, 'response-truncated', {
-            agent: this.activeAgentName,
-            provider: this.lastResolvedProviderName,
-            model: e.model,
-            maxTokens: e.maxTokens,
-            outputTokens: e.outputTokens,
-            tools: e.toolNames,
-            isSubAgent: this.isSubAgent,
-          });
-          if (this.isSubAgent) {
-            // Bubble a typed failure to the parent instead of speaking to the user.
-            this.failSubAgent('response_truncated');
-          } else {
-            this.appendToHistory({
-              role: 'assistant',
-              content:
-                'My response was cut off because a single step reached the model output limit. This usually means one step tried to produce too much at once — try breaking your request into smaller steps.',
-            });
-          }
-          return this.turnDone('response-truncated');
-        }
-        // The AI-spend budget is gone and the proxy refused the request (HTTP
-        // 402). Terminal in the strongest sense available to us: unlike a
-        // truncation — which a smaller request would get past — *no* request
-        // succeeds until someone raises the budget out of band. So there is no
-        // retry here and no "try again" in the copy; the turn ends and the host
-        // locks the composer off the `'budget-exhausted'` failure reason (see
-        // `FoundationAiAssistant.blocked`).
-        // The upstream vendor refused this ACCOUNT (GENC-1506) — its credit is gone, a usage cap is
-        // reached, or the credential is dead. Terminal in the strongest sense available: unlike a
-        // truncation, no smaller request gets past it, and unlike our own budget wall nobody in this
-        // system can raise anything to clear it. So no retry and no "try again" in the copy.
-        //
-        // Placed before the transient-retry step below, which is the whole point: without this the
-        // error is an untyped transport failure, gets re-issued MAX_SETUP_TRANSPORT_RETRIES times
-        // against a wall that cannot move, and then surfaces as "something went wrong on my end" —
-        // wrong twice over, since nothing went wrong on our end and trying again will not help.
-        if (e instanceof ProviderRefusedError) {
-          if (this.isSubAgent) {
-            logger.error('ChatDriver: provider refused the request', e);
-            recordTurnError(this.sessionKey, 'provider-refused', {
-              agent: this.activeAgentName,
-              provider: this.lastResolvedProviderName,
-              vendor: vendorTypeOfLabel(e.vendorLabel) ?? this.lastResolvedProvider,
-              kind: e.kind,
-              upstreamStatus: e.upstreamStatus,
-              upstreamType: e.upstreamType,
-              isSubAgent: true,
-            });
-            // The detail is BUBBLED, not merely flagged. Setting `providerRefusedThisTurn` on `this`
-            // would be pointless here — `this` is the CHILD, and the parent that must stop is a
-            // different driver instance. `invokeSubAgent` reads this payload off the child and sets its
-            // own flag; see the branch there.
-            const detail = providerRefusedDetailOf(e);
-            this.failSubAgent('provider_refused', undefined, detail);
-            return this.turnDone('provider-refused', undefined, detail);
-          }
-          return this.reportProviderRefused(e);
-        }
-        if (e instanceof BudgetExhaustedError) {
-          // Flagged as well as returned: a sub-agent's wall reaches the PARENT
-          // only as a tool result, and the parent must not issue another model
-          // call after it (see the short-circuit at the top of this loop).
-          this.budgetExhaustedThisTurn = true;
-          this.budgetWallDetail = budgetDetailOf(e);
-          // Paired with the detail everywhere it is written: this is the
-          // driver's OWN wall, so the sub-agent marker must not survive from an
-          // earlier child and suppress the `lastResolvedProvider` fallback that
-          // is legitimate here. Unreachable today (the short-circuit fires
-          // before a second wall can land in one turn) — kept structural so the
-          // pairing does not depend on that ordering staying true.
-          this.budgetWallViaSubAgent = false;
-          if (this.isSubAgent) {
-            logger.error('ChatDriver: AI budget exhausted', e);
-            recordTurnError(this.sessionKey, 'budget-exhausted', {
-              agent: this.activeAgentName,
-              provider: this.lastResolvedProviderName,
-              vendor:
-                vendorTypeOfLabel(e.vendorLabel) ??
-                vendorTypeOfLabel(e.serverVendor) ??
-                this.lastResolvedProvider,
-              budgetUsd: e.budgetUsd,
-              spentUsd: e.spentUsd,
-              isSubAgent: true,
-            });
-            // Bubble a typed failure to the parent instead of speaking to the
-            // user, carrying the attribution so the parent walls the vendor that
-            // actually refused rather than its own.
-            this.failSubAgent('budget_exhausted', this.budgetWallDetail);
-            return this.turnDone('budget-exhausted', this.budgetWallDetail);
-          }
-          return this.reportBudgetExhausted(e);
-        }
-        // A request timeout from the transport (tagged `TimeoutError`) is not a
-        // bug on our end — surface it distinctly instead of letting it fall
-        // through to the generic "something went wrong" catch. No auto-retry:
-        // the timeout ceiling is already minutes long, so a silent retry would
-        // just make the user wait again.
-        if (e instanceof DOMException && e.name === 'TimeoutError') {
-          logger.error('ChatDriver: request timed out', e);
-          recordTurnError(this.sessionKey, 'exception', {
-            agent: this.activeAgentName,
-            provider: this.lastResolvedProviderName,
-            name: e.name,
-            message: e.message,
-            isSubAgent: this.isSubAgent,
-          });
-          if (this.isSubAgent) {
-            // Bubble a typed failure to the parent instead of speaking to the user.
-            this.failSubAgent('timeout');
-          } else {
-            this.appendToHistory({
-              role: 'assistant',
-              content:
-                'The request timed out. You can ask me to try again, or break this into a smaller step.',
-            });
-          }
-          // Recorded as `exception` above (there is no separate `timeout` member of
-          // TurnFailureReason for the main turn); surface the same reason here.
-          return this.turnDone('exception');
-        }
-        // The request was aborted: either a user cancel (turnController) or a
-        // driver dispose (lifecycleController, chained into the turn). A user
-        // cancel adds a "Stopped." marker; a dispose stops quietly. Handled
-        // before the transient-retry below so an intentional abort/timeout is
-        // never retried.
-        if (e instanceof DOMException && e.name === 'AbortError') {
-          return this.completeAbortedTurn();
-        }
-        // A transient provider/transport error should retry the SAME iteration a bounded
-        // number of times rather than tearing down the whole turn (which strands the
-        // agent's unflushed buffer behind an opaque error message).
-        setupTransportAttempts += 1;
-        if (setupTransportAttempts < MAX_SETUP_TRANSPORT_RETRIES) {
-          logger.warn(
-            `ChatDriver: provider/transport error, retrying (${setupTransportAttempts}/${MAX_SETUP_TRANSPORT_RETRIES})`,
-          );
-          iterations -= 1;
-          continue;
-        }
-        throw e;
-      }
-
-      // Attribute the response to the concrete model + registry slot that
-      // produced it (resolved for this turn in `resolveProviderForTurn`). Carried
-      // on the assistant message so the debug-log timeline shows per-message
-      // model lineage — and thus per-tool-call, since tool calls ride on the
-      // assistant message that requests them. Harmless on a response later
-      // discarded as empty/retried; only kept copies reach history.
-      //
-      // Attach each key only when resolved: a provider with no `getStatus` (etc.)
-      // leaves the key off entirely rather than carrying it as `undefined`.
-      // JSON.stringify already drops undefined from the exported log, so this is
-      // chiefly about keeping the in-memory message shape honest.
-      // Fill, never overwrite — but still only when there is something to fill with.
-      // A transport that already stamped a model knows something the driver does not:
-      // `lastResolvedModel` is the model we ASKED for, so overwriting would relabel a
-      // fallback-served turn as the requested model and misattribute its spend.
-      // Written as a guard rather than `??=` because `??=` ASSIGNS undefined, which
-      // would create the key and break the omit-when-unresolved contract above.
-      if (response.model === undefined && this.lastResolvedModel !== undefined) {
-        response.model = this.lastResolvedModel;
-      }
-      if (this.lastResolvedProvider !== undefined) response.provider = this.lastResolvedProvider;
-      if (this.lastResolvedProviderName !== undefined) {
-        response.providerName = this.lastResolvedProviderName;
-      }
-
-      // Back-fill what this call cost onto the snapshot taken just before it, so the
-      // exported debug log prices each model call next to the prompt/tools/state that
-      // produced it (GENC-1480 follow-up). Stamped BEFORE the empty-response branch
-      // below deliberately: a blank or refused response is billed and then thrown away,
-      // so the snapshot is the only place that spend is ever recorded.
-      turnSnapshot.usage = messageUsage(response);
-      // Take the SERVING model over the requested one, now that it is known. `response.model`
-      // was just filled from `lastResolvedModel` if the transport left it unset, so this is
-      // the same rule the message gets — which is the point: a turn and the message it
-      // produced must never disagree about which model ran, including when a server-side
-      // fallback chain answered on a different model than the one we asked for.
-      if (response.model !== undefined) turnSnapshot.model = response.model;
-
-      const isThinkingStep = response.content && response.toolCalls?.length;
-      const isEmptyResponse = !response.content?.trim() && !response.toolCalls?.length;
-      // A pre-output refusal (safety-classifier decline, e.g. Fable 5 `stop_reason: 'refusal'`)
-      // comes back with empty content, so it looks like a blank response — but it is deterministic:
-      // retrying re-sends the identical request and refuses again, burning up to
-      // MAX_EMPTY_RESPONSE_RETRIES turns on the most expensive models for the same outcome, ending
-      // in the misleading "blank response" message. Treat it as a terminal, non-retried failure with
-      // its own reason and message. (GENC-1461)
-      const isRefusal = response.responseMeta?.finishReason === 'refusal';
-
-      if (isEmptyResponse) {
-        emptyResponseAttempts += 1;
-        if (!isRefusal && emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
-          logger.warn(
-            `ChatDriver: empty model response, retrying (${emptyResponseAttempts}/${MAX_EMPTY_RESPONSE_RETRIES})`,
-          );
-          recordTurnRetry(this.sessionKey, 'empty-response', {
-            agent: this.activeAgentName,
-            provider: this.lastResolvedProviderName,
-            attempt: emptyResponseAttempts,
-            maxAttempts: MAX_EMPTY_RESPONSE_RETRIES,
-            // Provider diagnostic (Gemini: finishReason, thoughtsTokens, parts,
-            // blockReason) so the timeline shows *why* the turn came back blank —
-            // e.g. a high thoughtsTokens with a 'STOP' finish is "thought, then
-            // stopped without answering".
-            ...response.responseMeta,
-          });
-          iterations -= 1;
-          continue;
-        }
-        const failureReason = isRefusal ? 'refusal' : 'empty-response';
-        logger.error(
-          isRefusal
-            ? 'ChatDriver: model refused the request (safety decline) — not retrying'
-            : 'ChatDriver: empty model response after all retries',
-        );
-        recordTurnError(this.sessionKey, failureReason, {
-          agent: this.activeAgentName,
-          provider: this.lastResolvedProviderName,
-          attempts: emptyResponseAttempts,
-          isSubAgent: this.isSubAgent,
-          ...response.responseMeta,
-        });
-        if (this.isSubAgent) {
-          this.failSubAgent(isRefusal ? 'refusal' : 'empty_response');
-        } else {
-          this.appendToHistory({
-            role: 'assistant',
-            content: isRefusal
-              ? 'This request was declined. Try rephrasing it, or breaking it into smaller steps.'
-              : 'While working on your request, I repeatedly generated a blank response. This often works on a second try — would you like me to try again? If it happens again, try breaking your request into smaller steps.',
-          });
-        }
-        return this.turnDone(failureReason);
-      } else {
-        // Split one model response into separate, individually-toggleable messages so each has its
-        // own visibility toggle and debug-log category:
-        //   - reasoning (chain-of-thought summary) → category 'reasoning', hidden unless showThinkingSteps
-        //   - narration (interstitial prose emitted alongside a tool call) → category 'narration',
-        //     hidden unless showNarration
-        //   - the answer / tool-call message → always shown; carries this turn's usage.
-        // Cost invariant (GENC-1410): exactly ONE message carries cost/tokens and is appended LAST, so
-        // `sumCosts`/`sumTokens` don't double-count and `contextTokens` reads it. Reasoning/narration are
-        // display-only (usage undefined) and are skipped when building the provider request. `model` /
-        // `provider` / `providerName` stay on every split message so each is still attributed.
-        //
-        // EVERY usage field has to be cleared here, not just the three the invariant was
-        // originally written against — keep this list in step with the usage fields on
-        // `ChatMessage`. The cache buckets arrived later (GENC-1475) and were left riding
-        // along on the copies, so a response carrying reasoning AND narration counted its
-        // cache read/write volume three times in `sumUsage`/`usageRows` — invisible in the
-        // cost total (which comes from `cost`) but wrong in every bucket display and in the
-        // exported log.
-        const { reasoning, ...rest } = response;
-        const displayOnly = {
-          cost: undefined,
-          externalCostUsd: undefined,
-          inputTokens: undefined,
-          outputTokens: undefined,
-          cacheReadTokens: undefined,
-          cacheWriteTokens: undefined,
-        };
-        if (reasoning) {
-          this.appendToHistory({
-            ...rest,
-            ...displayOnly,
-            content: reasoning,
-            toolCalls: undefined,
-            category: 'reasoning',
-          });
-        }
-        if (isThinkingStep) {
-          // content + tool call → the content is interstitial narration, not the final answer.
-          this.appendToHistory({
-            ...rest,
-            ...displayOnly,
-            toolCalls: undefined,
-            category: 'narration',
-          });
-          this.appendToHistory({ ...rest, content: '' });
-        } else {
-          // No tool call → `content` is the final answer (always shown), or this is a bare tool-call
-          // turn with no narration. Either way it carries this turn's usage; append it last.
-          this.appendToHistory(rest);
-        }
-      }
-
-      // Reset retry budgets on any productive (non-empty) response, so the caps mean
-      // "N CONSECUTIVE failures" not "N total per turn".
-      emptyResponseAttempts = 0;
-      malformedAttempts = 0;
-      setupTransportAttempts = 0;
-
-      if (!response.toolCalls?.length) {
-        break;
-      }
-
-      const [toolCalls, systemCalls] = response.toolCalls.reduce<[ChatToolCall[], ChatToolCall[]]>(
-        (acc, tc) => {
-          if (tc.name === REQUEST_CONTINUATION_TOOL) acc[1].push(tc);
-          else acc[0].push(tc);
-          return acc;
-        },
-        [[], []],
-      );
-
-      const executedById = new Map<
-        string,
-        {
-          toolCallId: string;
-          content: string;
-          attachments?: ChatImageAttachment[];
-          subAgentTrace?: ChatMessage[];
-        }
-      >();
-      const unknownToolIds = new Set<string>();
-      // Subset of unknownToolIds that were stale (previously available) rather
-      // than hallucinated — drives the `stale` UI flag back-patched below.
-      const staleToolIds = new Set<string>();
-      let anyRealToolExecuted = false;
-      let hitUnknownToolLimit = false;
-
-      if (toolCalls.length > 0) {
-        // oxlint-disable-next-line no-await-in-loop -- Promise.all is correct parallelism, not sequential loop awaiting
-        await Promise.all(
-          toolCalls.map(async (tc) => {
-            // Check for fold facade
-            const fold = this.getFold(tc.name);
-            if (fold) {
-              this.consecutiveFoldOps += 1;
-              if (this.consecutiveFoldOps > this.maxFoldOperations) {
-                logger.warn(
-                  `ChatDriver: fold operation limit (${this.maxFoldOperations}) reached — injecting guidance`,
-                );
-                executedById.set(tc.id, {
-                  toolCallId: tc.id,
-                  content: `You have opened and closed folds ${this.consecutiveFoldOps} times without calling any tools. Please call a specific tool to make progress, or respond to the user.`,
-                });
-                return;
-              }
-              const content = await this.openFold(tc.name, fold, tc.args, tc.id);
-              executedById.set(tc.id, { toolCallId: tc.id, content });
-              // Fold open/close does NOT count as a real iteration — decrement to compensate
-              iterations -= 1;
-              return;
-            }
-
-            // Check for close-fold tool
-            if (tc.name.startsWith('close_') && this.foldStack.length > 0) {
-              const topFoldName = this.foldStack[this.foldStack.length - 1].foldName;
-              if (tc.name === `close_${topFoldName}`) {
-                this.consecutiveFoldOps += 1;
-                if (this.consecutiveFoldOps > this.maxFoldOperations) {
-                  executedById.set(tc.id, {
-                    toolCallId: tc.id,
-                    content: `You have opened and closed folds ${this.consecutiveFoldOps} times without calling any tools. Please call a specific tool to make progress, or respond to the user.`,
-                  });
-                  return;
-                }
-                const content = this.closeFold();
-                executedById.set(tc.id, { toolCallId: tc.id, content });
-                iterations -= 1;
-                return;
-              }
-            }
-
-            // Regular tool — check if it's inside a fold and guide the model
-            const handler = this.toolHandlers[tc.name];
-            if (!handler) {
-              const containingFold = this.findFoldContaining(tc.name);
-              if (containingFold) {
-                logger.debug(
-                  `ChatDriver: model called folded tool "${tc.name}" — guiding to open "${containingFold}"`,
-                );
-                recordMetaEvent(this.sessionKey, 'tool.unresolved', {
-                  tool: tc.name,
-                  agent: this.activeAgentName,
-                  kind: 'folded',
-                  fold: containingFold,
-                });
-                executedById.set(tc.id, {
-                  toolCallId: tc.id,
-                  content: `"${tc.name}" is not directly available. It is inside the "${containingFold}" fold. Call ${containingFold} first to access it.`,
-                });
-                // Guidance does not count as a real iteration or fold op
-                iterations -= 1;
-                return;
-              }
-
-              // Not in any registered fold. If the tool was advertised earlier
-              // in this agent's lifetime it's *stale* (a stateful agent moved on,
-              // or an exclusive fold is hiding it) rather than hallucinated — a
-              // distinction worth making, because the model should stop retrying
-              // a retired tool rather than treat the failure as a typo. Stale
-              // calls still trip loop protection, but at a higher ceiling than
-              // hallucinated tools (see below) — they are self-correcting, so the
-              // guidance, telemetry, and limit differ.
-              if (this.everSeenToolNames.has(tc.name)) {
-                this.consecutiveUnknownToolCalls += 1;
-                const hidingFold = this.foldHidingTool(tc.name);
-                let content: string;
-                if (hidingFold) {
-                  content = `"${tc.name}" is not available while the "${hidingFold}" fold is open. Call close_${hidingFold} to return to the previous set of tools, then call ${tc.name}.`;
-                  logger.warn(
-                    `ChatDriver: tool "${tc.name}" is hidden behind open fold "${hidingFold}" (${this.consecutiveUnknownToolCalls}/${MAX_STALE_TOOL_CALLS})`,
-                  );
-                } else {
-                  content = `"${tc.name}" was available earlier but is not part of the current step — that step is complete, so do not call it again. Continue with the tools available now: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}.`;
-                  logger.warn(
-                    `ChatDriver: stale tool "${tc.name}" — advertised earlier this activation but retired in the current state (${this.consecutiveUnknownToolCalls}/${MAX_STALE_TOOL_CALLS})`,
-                  );
-                }
-                recordMetaEvent(this.sessionKey, 'tool.unresolved', {
-                  tool: tc.name,
-                  agent: this.activeAgentName,
-                  kind: hidingFold ? 'fold-hidden' : 'stale',
-                  fold: hidingFold ?? undefined,
-                  consecutive: this.consecutiveUnknownToolCalls,
-                  max: MAX_STALE_TOOL_CALLS,
-                });
-                // Fold-hidden tools keep their fold-specific guidance; a plain
-                // stale tool is a step-ordering miss, so offer the agent's
-                // redirect when it supplies one.
-                const staleContent = hidingFold
-                  ? content
-                  : await this.resolveUnresolvedToolContent(tc.name, 'stale', content);
-                executedById.set(tc.id, { toolCallId: tc.id, content: staleContent });
-                unknownToolIds.add(tc.id);
-                staleToolIds.add(tc.id);
-                this.recentUnknownToolNames.add(tc.name);
-                this.recentStaleToolNames.add(tc.name);
-                if (this.consecutiveUnknownToolCalls >= MAX_STALE_TOOL_CALLS) {
-                  hitUnknownToolLimit = true;
-                }
-                return;
-              }
-
-              // Never advertised — a hallucinated tool name.
-              this.consecutiveUnknownToolCalls += 1;
-              logger.warn(
-                `ChatDriver: no handler registered for tool "${tc.name}" (${this.consecutiveUnknownToolCalls}/${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}). Available tools: ${Object.keys(this.toolHandlers).join(', ') || '(none)'}`,
-              );
-              recordMetaEvent(this.sessionKey, 'tool.unresolved', {
-                tool: tc.name,
-                agent: this.activeAgentName,
-                kind: 'unknown',
-                consecutive: this.consecutiveUnknownToolCalls,
-                max: DEFAULT_MAX_UNKNOWN_TOOL_CALLS,
-                availableTools: Object.keys(this.toolHandlers),
-              });
-              const unknownContent = await this.resolveUnresolvedToolContent(
-                tc.name,
-                'unknown',
-                `Unknown tool: ${tc.name}`,
-              );
-              executedById.set(tc.id, { toolCallId: tc.id, content: unknownContent });
-              unknownToolIds.add(tc.id);
-              this.recentUnknownToolNames.add(tc.name);
-              if (this.consecutiveUnknownToolCalls >= DEFAULT_MAX_UNKNOWN_TOOL_CALLS) {
-                hitUnknownToolLimit = true;
-              }
-              return;
-            }
-
-            // Real tool execution.
-            //
-            // The accumulator is declared OUTSIDE the try so the catch can attach it
-            // too: a handler that ran sub-agents and then threw (post-processing their
-            // results failed, say) has already spent real money on children that
-            // completed. Losing their traces on the error path would under-report the
-            // run exactly as the single-slot bug did — and just as silently, since
-            // `sumUsage` and `usageRows` would still agree with each other.
-            const traceCapture: { traces: ChatMessage[][] } = { traces: [] };
-            const capturedTrace = (): ChatMessage[] | undefined =>
-              traceCapture.traces.length ? traceCapture.traces.flat() : undefined;
-            try {
-              const result = await handler(tc.args, this.buildHandlerContext(tc.id, traceCapture));
-              // A handler that returns images gets them carried as real attachments instead of
-              // JSON-stringified into the text — the difference between a model reading
-              // `{"kind":"image","data":"iVBOR…"}` as prose and actually SEEING the render.
-              // The guard is deliberately narrow (every entry must carry `kind: 'image'`) so an
-              // ordinary object return that happens to have an `attachments` key still
-              // stringifies exactly as before.
-              const resultImages = toolResultImages(result);
-              const content = resultImages
-                ? typeof (result as { content?: unknown }).content === 'string'
-                  ? (result as { content: string }).content
-                  : JSON.stringify({ ...(result as object), attachments: undefined })
-                : typeof result === 'string'
-                  ? result
-                  : JSON.stringify(result);
-              executedById.set(tc.id, {
-                toolCallId: tc.id,
-                content,
-                ...(resultImages ? { attachments: resultImages } : {}),
-                // Concatenated when a handler invoked several children, so none is lost.
-                // Stays `undefined` when nothing was captured — readers key off presence,
-                // and an empty array is a different claim from "no sub-agent ran".
-                subAgentTrace: capturedTrace(),
-              });
-              anyRealToolExecuted = true;
-            } catch (e) {
-              logger.error(`ChatDriver tool "${tc.name}" failed:`, e);
-              recordMetaEvent(this.sessionKey, 'tool.failed', {
-                tool: tc.name,
-                agent: this.activeAgentName,
-                message: e instanceof Error ? e.message : String(e),
-              });
-              executedById.set(tc.id, {
-                toolCallId: tc.id,
-                // Structured recovery hint so the model retries or routes around a tool
-                // failure instead of apologising and giving up.
-                content: `Tool error: ${(e as Error).message}\nRECOVERY: this tool failed once — you may retry it, or take a different valid action to make progress. Do NOT abandon the task, ask the user to rephrase, or claim you cannot make changes. If a planning tool failed, retry it or proceed with the information you already have.`,
-                // Children that completed before the throw were still billed — keep
-                // their traces so the run's cost stays whole.
-                subAgentTrace: capturedTrace(),
-              });
-              anyRealToolExecuted = true; // treat errors as real work for fold op counting
-            }
-          }),
-        );
-      }
-
-      // Reset counters whenever a real tool executes
-      if (anyRealToolExecuted) {
-        this.consecutiveFoldOps = 0;
-        this.consecutiveUnknownToolCalls = 0;
-        this.recentUnknownToolNames.clear();
-        this.recentStaleToolNames.clear();
-      }
-
-      // Tag tool calls with fold UI metadata before appending results
-      const foldPath = this.foldStack.map((f) => f.foldName);
-
-      for (const tc of response.toolCalls) {
-        if (tc.name === REQUEST_CONTINUATION_TOOL) {
-          this.appendToHistory({
-            role: 'tool',
-            content: '',
-            toolResult: { toolCallId: tc.id, content: HANDOFF_TOOL_RESULT_PLACEHOLDER },
-          });
-        } else {
-          const r = executedById.get(tc.id);
-          if (r) {
-            // Persist only `toolCallId`/`content` on the tool result — the sub-agent
-            // trace lives on the tool *call* (back-patched below from `executedById`),
-            // which is what the UI's trace panel and `sumCosts` read. Appending the
-            // trace here too would duplicate the entire child conversation in history
-            // (and the exported debug log) for no reader.
-            this.appendToHistory({
-              role: 'tool',
-              content: '',
-              toolResult: {
-                toolCallId: r.toolCallId,
-                content: r.content,
-                // Images DO persist, unlike the sub-agent trace above: they are the payload
-                // the model must see on every replay of this turn, not a one-off UI artefact.
-                // `condenseWhen` is what sheds them once they are spent — see condense-history.
-                ...(r.attachments ? { attachments: r.attachments } : {}),
-              },
-            });
-          }
-        }
-      }
-
-      // Back-patch foldEvent and foldPath onto the tool call message we just appended.
-      // The response was appended before execution — find it and annotate.
-      let tcMsgIdx = -1;
-      for (let i = this.history.length - 1; i >= 0; i -= 1) {
-        if (this.history[i].role === 'assistant' && this.history[i].toolCalls?.length) {
-          tcMsgIdx = i;
-          break;
-        }
-      }
-      if (tcMsgIdx !== -1) {
-        const tcMsg = this.history[tcMsgIdx];
-        const availableToolNames = Object.keys(this.toolHandlers);
-        const annotatedCalls = tcMsg.toolCalls!.map((tc) => {
-          const isFoldOpen =
-            !!this.getFold(tc.name) ||
-            // Was a fold facade at time of the call (now the tool set has changed)
-            // — detect by checking if the result message indicated a fold open
-            executedById.get(tc.id)?.content?.startsWith('Fold opened:');
-          const isFoldClose = executedById.get(tc.id)?.content?.startsWith('Fold closed:');
-          const isUnknown = unknownToolIds.has(tc.id);
-          return {
-            ...tc,
-            foldEvent: isFoldOpen
-              ? ('open' as const)
-              : isFoldClose
-                ? ('close' as const)
-                : undefined,
-            // Use the fold path that was active at the START of this iteration (before any opens/closes)
-            foldPath: !isFoldOpen && !isFoldClose && foldPath.length > 0 ? foldPath : undefined,
-            unknown: isUnknown || undefined,
-            availableTools: isUnknown ? availableToolNames : undefined,
-            // Distinguish a retired tool from a hallucinated one so the UI can
-            // say "no longer available here" rather than "does not exist".
-            stale: staleToolIds.has(tc.id) || undefined,
-            subAgentTrace: executedById.get(tc.id)?.subAgentTrace,
-          };
-        });
-        this.history[tcMsgIdx] = { ...tcMsg, toolCalls: annotatedCalls };
-        this.dispatchEvent(
-          new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
-            detail: this.history,
-          }),
-        );
-      }
-
-      if (hitUnknownToolLimit) {
-        logger.error(
-          `ChatDriver: unknown-tool limit (${DEFAULT_MAX_UNKNOWN_TOOL_CALLS}) reached — stopping`,
-        );
-        const unknownTools = [
-          ...new Set([
-            ...this.recentUnknownToolNames,
-            ...(response.toolCalls ?? [])
-              .filter((tc) => unknownToolIds.has(tc.id))
-              .map((tc) => tc.name),
-          ]),
-        ];
-        // Stale tools were real earlier this activation; hallucinated tools
-        // never existed. The hard stop counts both the same way, but the split
-        // tells a triager whether the cause is a state/prompt-design problem
-        // (stale) or a model inventing tool names (hallucinated).
-        const staleTools = [
-          ...new Set([
-            ...this.recentStaleToolNames,
-            ...(response.toolCalls ?? [])
-              .filter((tc) => staleToolIds.has(tc.id))
-              .map((tc) => tc.name),
-          ]),
-        ];
-        const hallucinatedTools = unknownTools.filter((t) => !staleTools.includes(t));
-        recordTurnError(this.sessionKey, 'unknown-tool-limit', {
-          agent: this.activeAgentName,
-          provider: this.lastResolvedProviderName,
-          unknownTools,
-          staleTools,
-          hallucinatedTools,
-          availableTools: Object.keys(this.toolHandlers),
-          isSubAgent: this.isSubAgent,
-        });
-        if (this.isSubAgent) {
-          this.failSubAgent('unknown_tool_limit');
-        } else {
-          this.appendToHistory({
-            role: 'assistant',
-            content:
-              "I'm sorry, I repeatedly tried to use tools that aren't available to me, so I couldn't complete that. If a 'Download agent log' option appears in the Settings (cog) menu, you can download the log and share it with whoever set up this assistant to help fix the issue.",
-          });
-        }
-        return this.turnDone('unknown-tool-limit');
-      }
-
-      const firstContinuation = systemCalls[0];
-      if (firstContinuation) {
-        const { summary, remaining_task: remainingTask } = firstContinuation.args as {
-          summary: string;
-          remaining_task: string;
-        };
-        return { reason: 'agent-handoff', summary, remainingTask };
-      }
-
-      // Sub-agent early exit — checked here so the exit point mirrors the
-      // system-call pattern above. Set by completeSubAgent() in a tool handler.
-      if (this.subAgentCompletion) {
-        return this.turnDone();
-      }
-    }
-
-    // The loop fell through: either it hit the iteration cap (a failure) or it
-    // broke on a clean final answer (success). Only the former carries a reason.
-    let failureReason: TurnFailureReason | undefined;
-    if (iterations >= this.maxToolIterations) {
-      logger.warn('ChatDriver: reached max tool iterations, stopping');
-      recordTurnError(this.sessionKey, 'max-iterations', {
-        agent: this.activeAgentName,
-        provider: this.lastResolvedProviderName,
-        iterations,
-        limit: this.maxToolIterations,
-        isSubAgent: this.isSubAgent,
-      });
-      if (this.isSubAgent) {
-        this.failSubAgent('max_iterations');
-      } else {
-        this.appendToHistory({
-          role: 'assistant',
-          content:
-            "I've reached my limit for this response. You can ask me to continue and I'll pick up where I left off.",
-        });
-      }
-      failureReason = 'max-iterations';
-    }
-
-    return this.turnDone(failureReason);
-  }
-
-  private appendToHistory(message: ChatMessage): void {
-    const tagged: ChatMessage = {
-      ...message,
-      // Stamp on first append; preserve any caller-supplied timestamp.
-      timestamp: message.timestamp ?? new Date().toISOString(),
-      ...(this.activeAgentName
-        ? {
-            agentName: this.activeAgentName,
-            // Display-only — falls back to agentName in renderers when unset.
-            agentLabel: this.activeAgentLabel,
-          }
-        : {}),
-    };
-    this.history = [...this.history, tagged];
-    this.dispatchEvent(
-      new CustomEvent<ReadonlyArray<ChatMessage>>('history-updated', {
-        detail: this.history,
-      }),
-    );
-  }
-}