@genesislcap/ai-assistant 15.6.2 → 15.7.0-ts7.1

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

@@ -1,5 +1,5 @@
 import { __awaiter, __rest } from "tslib";
-import { isObservableAIProviderRegistry, MalformedFunctionCallError, ResponseTruncatedError, } from '@genesislcap/foundation-ai';
+import { BudgetExhaustedError, DEFAULT_BUDGET_EXHAUSTED_MESSAGE, isObservableAIProviderRegistry, MalformedFunctionCallError, ResponseTruncatedError, vendorTypeOfLabel, } from '@genesislcap/foundation-ai';
 import { NOOP_ACTIVITY_BUS } from '../../channel/ai-activity-bus';
 import { resolveChatProvider } from '../../config/validate-providers';
 import { clearSession, getMetaEvents, mergeMetaEvents, recordMetaEvent, recordTurnError, recordTurnRetry, } from '../../state/debug-event-log';
@@ -9,6 +9,40 @@ import { applyHistoryCap, buildCompactionSummaryPrompt, findCompactionCut, norma
 import { logger } from '../../utils/logger';
 import { sumUsage } from '../../utils/sum-usage';
 import { TOOL_FOLD_SYMBOL } from '../../utils/tool-fold';
+/**
+ * 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) => {
+    var _a;
+    // 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 = (_a = vendorTypeOfLabel(e.vendorLabel)) !== null && _a !== void 0 ? _a : vendorTypeOfLabel(e.serverVendor);
+    if (e.budgetUsd == null && e.spentUsd == null && !vendor)
+        return undefined;
+    return Object.assign(Object.assign({ budgetUsd: e.budgetUsd, spentUsd: e.spentUsd, vendorLabel: e.vendorLabel }, (vendor ? { vendor } : {})), (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.
@@ -230,11 +264,28 @@ export class ChatDriver extends EventTarget {
          * picked up on the next turn.
          */
         this.resolvedStatusCache = new Map();
-        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, } = config;
+        /**
+         * 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.
+         */
+        this.budgetExhaustedThisTurn = false;
+        /**
+         * 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`.
+         */
+        this.budgetWallViaSubAgent = false;
+        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 = 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 = {};
@@ -364,8 +415,61 @@ export class ChatDriver extends EventTarget {
      * (rather than set to `undefined`) so a happy-path result stays byte-identical to
      * the historical `{ reason: 'done' }`.
      */
-    turnDone(failureReason) {
-        return failureReason ? { reason: 'done', failureReason } : { reason: 'done' };
+    turnDone(failureReason, budget) {
+        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, pendingUserMessage) {
+        var _a, _b;
+        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: (_b = (_a = vendorTypeOfLabel(e.vendorLabel)) !== null && _a !== void 0 ? _a : vendorTypeOfLabel(e.serverVendor)) !== null && _b !== void 0 ? _b : 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. */
     static failureReasonOf(result) {
@@ -375,10 +479,39 @@ export class ChatDriver extends EventTarget {
      * 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.
      */
-    static loopEndDetail(result) {
+    loopEndDetail(result) {
+        var _a;
         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 = (_a = budget === null || budget === void 0 ? void 0 : budget.vendor) !== null && _a !== void 0 ? _a : (this.budgetWallViaSubAgent ? undefined : this.lastResolvedProvider);
+        return Object.assign(Object.assign({ failureReason }, (vendor ? { vendor } : {})), (budget ? { budget } : {}));
     }
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
@@ -546,7 +679,7 @@ export class ChatDriver extends EventTarget {
                 return this.resolvedStatusCache.get(name);
             let status = {};
             try {
-                const resolved = yield ((_a = provider.getStatus) === null || _a === void 0 ? void 0 : _a.call(provider));
+                const resolved = yield (_a = provider.getStatus) === null || _a === void 0 ? void 0 : _a.call(provider);
                 if (resolved) {
                     status = { model: resolved.model, provider: resolved.provider };
                 }
@@ -603,10 +736,12 @@ export class ChatDriver extends EventTarget {
      * under a separate session key, so recording here would orphan the event off
      * the user-visible debug-log timeline.)
      */
-    failSubAgent(reason) {
+    failSubAgent(reason, budget) {
         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 };
     }
     /**
      * Returns true if `releaseAgent` was called during the most recent turn.
@@ -790,13 +925,10 @@ export class ChatDriver extends EventTarget {
             }
             else {
                 const conversationContext = history
-                    .filter((m) => {
-                    var _a, _b;
-                    return (m.role === 'user' || m.role === 'assistant') &&
-                        !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) &&
-                        !m.thinking &&
-                        !!((_b = m.content) === null || _b === void 0 ? void 0 : _b.trim());
-                })
+                    .filter((m) => { var _a, _b; return (m.role === 'user' || m.role === 'assistant') &&
+                    !((_a = m.toolCalls) === null || _a === void 0 ? void 0 : _a.length) &&
+                    !m.thinking &&
+                    !!((_b = m.content) === null || _b === void 0 ? void 0 : _b.trim()); })
                     .slice(-SUGGESTIONS_HISTORY_WINDOW)
                     .map((m) => `${m.role === 'user' ? 'User' : 'Assistant'}: ${m.content}`)
                     .join('\n');
@@ -851,7 +983,8 @@ export class ChatDriver extends EventTarget {
      */
     compact() {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f;
+            var _a, _b, _c, _d;
+            var _e, _f;
             if (this.busy)
                 return null;
             const defaultProvider = this.providerRegistry.default();
@@ -874,7 +1007,7 @@ export class ChatDriver extends EventTarget {
             const failMessage = "Sorry, I couldn't compact the conversation just now. Nothing was changed — please try again.";
             let summaryText;
             try {
-                summaryText = (_b = (_a = (yield defaultProvider.prompt(userMessage, { systemPrompt }))) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+                summaryText = (_e = (_a = (yield defaultProvider.prompt(userMessage, { systemPrompt }))) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _e !== void 0 ? _e : '';
             }
             catch (e) {
                 logger.warn(`ChatDriver: compaction summary failed: ${e instanceof Error ? e.message : e}`);
@@ -893,7 +1026,7 @@ export class ChatDriver extends EventTarget {
                     break;
                 }
             }
-            const status = yield ((_c = defaultProvider.getStatus) === null || _c === void 0 ? void 0 : _c.call(defaultProvider));
+            const status = yield (_b = defaultProvider.getStatus) === null || _b === void 0 ? void 0 : _b.call(defaultProvider);
             const createdAt = new Date().toISOString();
             const summaryMessage = {
                 role: 'compacted-summary',
@@ -902,10 +1035,10 @@ export class ChatDriver extends EventTarget {
                 // 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: (_e = (_d = toCompact[0]) === null || _d === void 0 ? void 0 : _d.timestamp) !== null && _e !== void 0 ? _e : createdAt,
+                timestamp: (_f = (_c = toCompact[0]) === null || _c === void 0 ? void 0 : _c.timestamp) !== null && _f !== void 0 ? _f : createdAt,
                 compaction: {
                     compactedCount: toCompact.length,
-                    coveredThroughTimestamp: (_f = toCompact[toCompact.length - 1]) === null || _f === void 0 ? void 0 : _f.timestamp,
+                    coveredThroughTimestamp: (_d = toCompact[toCompact.length - 1]) === null || _d === void 0 ? void 0 : _d.timestamp,
                     tokensBefore,
                     model: status === null || status === void 0 ? void 0 : status.model,
                     createdAt,
@@ -1016,7 +1149,8 @@ export class ChatDriver extends EventTarget {
      * Marks the interaction message as resolved so it renders read-only on re-render.
      */
     resolveInteraction(interactionId, result) {
-        var _a, _b;
+        var _a;
+        var _b;
         const interaction = this.pendingInteractions.get(interactionId);
         if (interaction) {
             // Clear the timeout so a user resolution doesn't later fire a stale
@@ -1109,7 +1243,7 @@ export class ChatDriver extends EventTarget {
                     ? result.costUsd
                     : undefined;
                 this.history[idx] = Object.assign(Object.assign(Object.assign({}, this.history[idx]), { interaction: Object.assign(Object.assign({}, this.history[idx].interaction), { resolved: result }) }), (costUsd != null
-                    ? { externalCostUsd: ((_a = this.history[idx].externalCostUsd) !== null && _a !== void 0 ? _a : 0) + costUsd }
+                    ? { externalCostUsd: ((_b = this.history[idx].externalCostUsd) !== null && _b !== void 0 ? _b : 0) + costUsd }
                     : {}));
                 this.dispatchEvent(new CustomEvent('history-updated', {
                     detail: this.history,
@@ -1137,7 +1271,7 @@ export class ChatDriver extends EventTarget {
             this.pendingInteractions.delete(interactionId);
             // Tear down the live context on RESOLVE (not on element unmount) — this closes
             // any sockets/timers the widget parked on it via `onDispose`. (GENC-1390)
-            (_b = this.interactionContexts.get(interactionId)) === null || _b === void 0 ? void 0 : _b.dispose();
+            (_a = this.interactionContexts.get(interactionId)) === null || _a === void 0 ? void 0 : _a.dispose();
             this.interactionContexts.delete(interactionId);
         }
         else {
@@ -1191,6 +1325,9 @@ export class ChatDriver extends EventTarget {
             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', {
@@ -1228,7 +1365,7 @@ export class ChatDriver extends EventTarget {
                 });
                 this.busy = false;
                 this.endTurn();
-                this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
+                this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
             }
         });
     }
@@ -1322,7 +1459,8 @@ export class ChatDriver extends EventTarget {
      */
     invokeSubAgent(name, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a;
+            var _b, _c, _d, _e;
             const subConfig = this.subAgentsMap.get(name);
             if (!subConfig) {
                 const available = [...this.subAgentsMap.keys()].join(', ') || '(none)';
@@ -1491,12 +1629,35 @@ export class ChatDriver extends EventTarget {
             // 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 = (_e = (_d = child.getSubAgentFailure()) === null || _d === void 0 ? void 0 : _d.reason) !== null && _e !== void 0 ? _e : 'max_iterations';
+            const failure = child.getSubAgentFailure();
+            const reason = (_d = failure === null || failure === void 0 ? void 0 : failure.reason) !== null && _d !== void 0 ? _d : '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;
+                (_e = this.budgetWallDetail) !== null && _e !== void 0 ? _e : (this.budgetWallDetail = failure === null || failure === void 0 ? void 0 : failure.budget);
+            }
             return { outcome: { ok: false, reason }, trace };
         });
     }
@@ -1512,6 +1673,9 @@ export class ChatDriver extends EventTarget {
             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',
@@ -1548,7 +1712,7 @@ export class ChatDriver extends EventTarget {
                 });
                 this.busy = false;
                 this.endTurn();
-                this.activityBus.publish('tool-loop-end', ChatDriver.loopEndDetail(result));
+                this.activityBus.publish('tool-loop-end', this.loopEndDetail(result));
             }
         });
     }
@@ -1702,7 +1866,8 @@ export class ChatDriver extends EventTarget {
     // oxlint-disable-next-line complexity
     runToolLoop(userInput, attachments, transientPrimer) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+            var _a, _b, _c, _d, _e, _f, _g;
+            var _h, _j, _k, _l, _m, _o;
             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.');
             }
@@ -1732,8 +1897,48 @@ export class ChatDriver extends EventTarget {
                 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.
+                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: (_a = this.budgetWallDetail) === null || _a === void 0 ? void 0 : _a.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 = {
-                    agentName: (_a = this.activeAgentName) !== null && _a !== void 0 ? _a : '',
+                    agentName: (_h = this.activeAgentName) !== null && _h !== void 0 ? _h : '',
                     history: this.history,
                     turnIndex: iterations - 1,
                     signal: this.turnController.signal,
@@ -1806,7 +2011,7 @@ export class ChatDriver extends EventTarget {
                 // loses all summarized context. `normalizeForProvider` only touches
                 // `compacted-summary`, so it's a safe pass-through for everything else.
                 const primer = normalizeForProvider([
-                    ...((_b = this.primerHistory) !== null && _b !== void 0 ? _b : []),
+                    ...((_j = this.primerHistory) !== null && _j !== void 0 ? _j : []),
                     ...(transientPrimer !== null && transientPrimer !== void 0 ? transientPrimer : []),
                 ]);
                 const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
@@ -1972,6 +2177,44 @@ export class ChatDriver extends EventTarget {
                         }
                         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: (_l = (_k = vendorTypeOfLabel(e.vendorLabel)) !== null && _k !== void 0 ? _k : vendorTypeOfLabel(e.serverVendor)) !== null && _l !== void 0 ? _l : 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:
@@ -2037,15 +2280,15 @@ export class ChatDriver extends EventTarget {
                 if (this.lastResolvedProviderName !== undefined) {
                     response.providerName = this.lastResolvedProviderName;
                 }
-                const isThinkingStep = response.content && ((_c = response.toolCalls) === null || _c === void 0 ? void 0 : _c.length);
-                const isEmptyResponse = !((_d = response.content) === null || _d === void 0 ? void 0 : _d.trim()) && !((_e = response.toolCalls) === null || _e === void 0 ? void 0 : _e.length);
+                const isThinkingStep = response.content && ((_b = response.toolCalls) === null || _b === void 0 ? void 0 : _b.length);
+                const isEmptyResponse = !((_c = response.content) === null || _c === void 0 ? void 0 : _c.trim()) && !((_d = response.toolCalls) === null || _d === void 0 ? void 0 : _d.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 = ((_f = response.responseMeta) === null || _f === void 0 ? void 0 : _f.finishReason) === 'refusal';
+                const isRefusal = ((_e = response.responseMeta) === null || _e === void 0 ? void 0 : _e.finishReason) === 'refusal';
                 if (isEmptyResponse) {
                     emptyResponseAttempts += 1;
                     if (!isRefusal && emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
@@ -2104,7 +2347,7 @@ export class ChatDriver extends EventTarget {
                 emptyResponseAttempts = 0;
                 malformedAttempts = 0;
                 setupTransportAttempts = 0;
-                if (!((_g = response.toolCalls) === null || _g === void 0 ? void 0 : _g.length)) {
+                if (!((_f = response.toolCalls) === null || _f === void 0 ? void 0 : _f.length)) {
                     break;
                 }
                 const [toolCalls, systemCalls] = response.toolCalls.reduce((acc, tc) => {
@@ -2310,7 +2553,7 @@ export class ChatDriver extends EventTarget {
                 // 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' && ((_h = this.history[i].toolCalls) === null || _h === void 0 ? void 0 : _h.length)) {
+                    if (this.history[i].role === 'assistant' && ((_g = this.history[i].toolCalls) === null || _g === void 0 ? void 0 : _g.length)) {
                         tcMsgIdx = i;
                         break;
                     }
@@ -2348,7 +2591,7 @@ export class ChatDriver extends EventTarget {
                     const unknownTools = [
                         ...new Set([
                             ...this.recentUnknownToolNames,
-                            ...((_j = response.toolCalls) !== null && _j !== void 0 ? _j : [])
+                            ...((_m = response.toolCalls) !== null && _m !== void 0 ? _m : [])
                                 .filter((tc) => unknownToolIds.has(tc.id))
                                 .map((tc) => tc.name),
                         ]),
@@ -2360,7 +2603,7 @@ export class ChatDriver extends EventTarget {
                     const staleTools = [
                         ...new Set([
                             ...this.recentStaleToolNames,
-                            ...((_k = response.toolCalls) !== null && _k !== void 0 ? _k : [])
+                            ...((_o = response.toolCalls) !== null && _o !== void 0 ? _o : [])
                                 .filter((tc) => staleToolIds.has(tc.id))
                                 .map((tc) => tc.name),
                         ]),