@genesislcap/ai-assistant 15.14.0 → 15.14.2

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

@@ -25,6 +25,8 @@ import type {
 import {
   BudgetExhaustedError,
   DEFAULT_BUDGET_EXHAUSTED_MESSAGE,
+  DEFAULT_PROVIDER_REFUSED_MESSAGE,
+  ProviderRefusedError,
   isObservableAIProviderRegistry,
   MalformedFunctionCallError,
   ResponseTruncatedError,
@@ -80,6 +82,10 @@ import type { AiDriver, AllAgentSummary } from '../ai-driver/ai-driver';
  * 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`
@@ -100,6 +106,21 @@ type BudgetDetail = NonNullable<Extract<ChatDriverResult, { reason: 'done' }>['b
  * `formatBlockedReason`, which returns `undefined` for a figure-less budget so a
  * host-set explanation survives the latch.
  */
+/**
+ * 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
@@ -352,6 +373,20 @@ export interface ChatDriverConfig {
    * 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;
 }
 
 /**
@@ -549,7 +584,21 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * the child's ATTRIBUTION, not just the fact of a wall — see
    * `budgetWallDetail`.
    */
-  private subAgentFailure: { reason: SubAgentFailureReason; budget?: BudgetDetail } | undefined;
+  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
@@ -712,6 +761,27 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * 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
@@ -761,12 +831,14 @@ export class ChatDriver extends EventTarget implements AiDriver {
       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 = {};
@@ -895,11 +967,20 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * (rather than set to `undefined`) so a happy-path result stays byte-identical to
    * the historical `{ reason: 'done' }`.
    */
-  private turnDone(failureReason?: TurnFailureReason, budget?: BudgetDetail): ChatDriverResult {
+  private turnDone(
+    failureReason?: TurnFailureReason,
+    budget?: BudgetDetail,
+    providerRefused?: ProviderRefusedDetail,
+  ): ChatDriverResult {
     if (!failureReason) return { reason: 'done' };
-    // `budget` is likewise omitted rather than set to `undefined`, so a non-budget
-    // failure's shape is unchanged for a consumer that structurally compares it.
-    return budget ? { reason: 'done', failureReason, budget } : { reason: 'done', failureReason };
+    // 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 } : {}),
+    };
   }
 
   /**
@@ -982,6 +1063,44 @@ export class ChatDriver extends EventTarget implements AiDriver {
     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;
@@ -1259,7 +1378,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * `completeSubAgent`, if any. Called by a parent `ChatDriver` after running
    * this instance as a sub-agent.
    */
-  getSubAgentFailure(): { reason: SubAgentFailureReason; budget?: BudgetDetail } | undefined {
+  getSubAgentFailure():
+    | {
+        reason: SubAgentFailureReason;
+        budget?: BudgetDetail;
+        providerRefused?: ProviderRefusedDetail;
+      }
+    | undefined {
     return this.subAgentFailure;
   }
 
@@ -1271,11 +1396,19 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * 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): void {
+  private failSubAgent(
+    reason: SubAgentFailureReason,
+    budget?: BudgetDetail,
+    providerRefused?: ProviderRefusedDetail,
+  ): void {
     if (!this.isSubAgent || this.subAgentFailure) return;
-    // Omitted rather than set to `undefined` so a non-budget failure's shape is
+    // 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 = budget ? { reason, budget } : { reason };
+    this.subAgentFailure = {
+      reason,
+      ...(budget ? { budget } : {}),
+      ...(providerRefused ? { providerRefused } : {}),
+    };
   }
 
   /**
@@ -1924,6 +2057,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
     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', {
@@ -2321,6 +2456,20 @@ export class ChatDriver extends EventTarget implements AiDriver {
       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 };
   }
 
@@ -2338,6 +2487,8 @@ export class ChatDriver extends EventTarget implements AiDriver {
     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',
@@ -2612,6 +2763,30 @@ export class ChatDriver extends EventTarget implements AiDriver {
       // 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', {
@@ -2959,6 +3134,37 @@ export class ChatDriver extends EventTarget implements AiDriver {
         // 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

package/src/state/debug-event-log.test.ts

@@ -109,6 +109,7 @@ const ALL_TURN_FAILURE_REASONS = Object.keys({
   'response-truncated': true,
   refusal: true,
   'budget-exhausted': true,
+  'provider-refused': true,
 } satisfies Record<TurnFailureReason, true>) as TurnFailureReason[];
 
 const ALL_SUB_AGENT_FAILURE_REASONS = Object.keys({
@@ -120,6 +121,7 @@ const ALL_SUB_AGENT_FAILURE_REASONS = Object.keys({
   response_truncated: true,
   refusal: true,
   budget_exhausted: true,
+  provider_refused: true,
 } satisfies Record<SubAgentFailureReason, true>) as SubAgentFailureReason[];
 
 const README_TEXT = DEBUG_LOG_README.join('\n');

package/src/state/debug-event-log.ts

@@ -328,7 +328,7 @@ export const DEBUG_LOG_README: readonly string[] = [
   "kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.",
   "kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.",
   "Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.",
-  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted; budget_exhausted is terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted/provider-refused, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted/provider_refused; budget_exhausted and provider_refused are both terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
   'Sub-agent meta events: a sub-agent\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `"<parent> › <sub-agent>"` breadcrumb that composes when nested (e.g. `"UI Builder › Planner › Grounding"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\'s span.',
   "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
   'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',