@genesislcap/ai-assistant 15.6.2 → 15.7.1

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

@@ -21,9 +21,12 @@ import type {
   TurnFailureReason,
 } from '@genesislcap/foundation-ai';
 import {
+  BudgetExhaustedError,
+  DEFAULT_BUDGET_EXHAUSTED_MESSAGE,
   isObservableAIProviderRegistry,
   MalformedFunctionCallError,
   ResponseTruncatedError,
+  vendorTypeOfLabel,
 } from '@genesislcap/foundation-ai';
 import { type ActivityBus, NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
 import type {
@@ -69,6 +72,53 @@ import { 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']>;
+
+/**
+ * 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.
+ */
+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.
@@ -238,6 +288,22 @@ export interface ChatDriverConfig {
    * 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).
+   * Defaults to `DEFAULT_BUDGET_EXHAUSTED_MESSAGE`.
+   *
+   * 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;
 }
 
 /**
@@ -430,8 +496,12 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * 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 } | undefined;
+  private subAgentFailure: { reason: SubAgentFailureReason; budget?: BudgetDetail } | 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
@@ -582,6 +652,39 @@ export class ChatDriver extends EventTarget implements AiDriver {
   private readonly sessionKey: string;
   /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
   private readonly activityBus: ActivityBus;
+  /** Transcript copy for a budget wall — see `ChatDriverConfig.budgetExhaustedMessage`. */
+  private readonly budgetExhaustedMessage: string;
+  /**
+   * 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,
@@ -599,11 +702,13 @@ export class ChatDriver extends EventTarget implements AiDriver {
       maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS,
       sessionKey = '',
       activityBus = NOOP_ACTIVITY_BUS,
+      budgetExhaustedMessage = DEFAULT_BUDGET_EXHAUSTED_MESSAGE,
     } = config;
     this.maxToolIterations = maxToolIterations;
     this.condenseBatchCalls = condenseBatchCalls;
     this.sessionKey = sessionKey;
     this.activityBus = activityBus;
+    this.budgetExhaustedMessage = budgetExhaustedMessage;
     if (typeof toolHandlers === 'function') {
       this.toolHandlersFactory = toolHandlers;
       this.toolHandlers = {};
@@ -732,8 +837,65 @@ 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): ChatDriverResult {
-    return failureReason ? { reason: 'done', failureReason } : { reason: 'done' };
+  private turnDone(failureReason?: TurnFailureReason, budget?: BudgetDetail): 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 };
+  }
+
+  /**
+   * 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
+   */
+  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.budgetExhaustedMessage });
+    return this.turnDone('budget-exhausted', budgetDetailOf(e));
   }
 
   /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
@@ -745,12 +907,48 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * 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.
-   */
-  private static loopEndDetail(
-    result: ChatDriverResult,
-  ): { failureReason: TurnFailureReason } | undefined {
+   *
+   * 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);
-    return failureReason ? { failureReason } : undefined;
+    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 } : {}),
+    };
   }
 
   /**
@@ -969,7 +1167,7 @@ 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 } | undefined {
+  getSubAgentFailure(): { reason: SubAgentFailureReason; budget?: BudgetDetail } | undefined {
     return this.subAgentFailure;
   }
 
@@ -981,9 +1179,11 @@ 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): void {
+  private failSubAgent(reason: SubAgentFailureReason, budget?: BudgetDetail): void {
     if (!this.isSubAgent || this.subAgentFailure) return;
-    this.subAgentFailure = { reason };
+    // Omitted rather than set to `undefined` so a non-budget failure's shape is
+    // unchanged for a structural comparison, matching `turnDone`.
+    this.subAgentFailure = budget ? { reason, budget } : { reason };
   }
 
   /**
@@ -1623,6 +1823,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.subAgentCompletion = undefined;
     this.subAgentFailure = undefined;
     this.agentReleaseRequested = false;
+    this.budgetExhaustedThisTurn = false;
+    this.budgetWallDetail = undefined;
+    this.budgetWallViaSubAgent = false;
     this.appendToHistory({ role: 'user', content: userInput, attachments });
     this.turnStartedAt = Date.now();
     recordMetaEvent(this.sessionKey, 'turn.start', {
@@ -1659,7 +1862,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
+      this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
     }
   }
 
@@ -1974,12 +2177,35 @@ export class ChatDriver extends EventTarget implements AiDriver {
     // 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 reason = child.getSubAgentFailure()?.reason ?? 'max_iterations';
+    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;
+    }
     return { outcome: { ok: false, reason }, trace };
   }
 
@@ -1994,6 +2220,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
     this.beginTurn();
     this.subAgentCompletion = undefined;
     this.subAgentFailure = undefined;
+    this.budgetExhaustedThisTurn = false;
+    this.budgetWallDetail = undefined;
+    this.budgetWallViaSubAgent = false;
     this.turnStartedAt = Date.now();
     recordMetaEvent(this.sessionKey, 'turn.start', {
       phase: 'continueFromHistory',
@@ -2028,7 +2257,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
       });
       this.busy = false;
       this.endTurn();
-      this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
+      this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
     }
   }
 
@@ -2245,6 +2474,46 @@ export class ChatDriver extends EventTarget implements AiDriver {
         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.
+      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 {
+          this.appendToHistory({ role: 'assistant', content: this.budgetExhaustedMessage });
+        }
+        // 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,
@@ -2511,6 +2780,47 @@ export class ChatDriver extends EventTarget implements AiDriver {
           }
           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`).
+        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: