@genesislcap/ai-assistant 15.14.0 → 15.14.2

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

@@ -1,5 +1,5 @@
 import { __awaiter, __rest } from "tslib";
-import { BudgetExhaustedError, DEFAULT_BUDGET_EXHAUSTED_MESSAGE, isObservableAIProviderRegistry, MalformedFunctionCallError, ResponseTruncatedError, vendorTypeOfLabel, } from '@genesislcap/foundation-ai';
+import { BudgetExhaustedError, DEFAULT_BUDGET_EXHAUSTED_MESSAGE, DEFAULT_PROVIDER_REFUSED_MESSAGE, ProviderRefusedError, 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';
@@ -28,6 +28,15 @@ import { TOOL_FOLD_SYMBOL } from '../../utils/tool-fold';
  * `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) => (Object.assign(Object.assign({ vendorLabel: e.vendorLabel, kind: e.kind }, (e.upstreamStatus != null ? { upstreamStatus: e.upstreamStatus } : {})), (e.upstreamType ? { upstreamType: e.upstreamType } : {})));
 const budgetDetailOf = (e) => {
     var _a;
     // The typed vendor is derived from the LABEL, not from `lastResolvedProvider`:
@@ -264,6 +273,16 @@ export class ChatDriver extends EventTarget {
          * picked up on the next turn.
          */
         this.resolvedStatusCache = new Map();
+        /**
+         * 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.
+         */
+        this.providerRefusedThisTurn = false;
         /**
          * 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
@@ -280,12 +299,13 @@ export class ChatDriver extends EventTarget {
          * 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, } = config;
+        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 = {};
@@ -415,12 +435,12 @@ 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, budget) {
+    turnDone(failureReason, budget, providerRefused) {
         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 Object.assign(Object.assign({ reason: 'done', failureReason }, (budget ? { budget } : {})), (providerRefused ? { providerRefused } : {}));
     }
     /**
      * Terminal budget outcome for a wall hit **outside** the tool loop — today,
@@ -495,6 +515,44 @@ export class ChatDriver extends EventTarget {
         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.
+     */
+    providerRefusedBubble() {
+        var _a;
+        return (_a = this.providerRefusedMessageOverride) !== null && _a !== void 0 ? _a : 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.
+     */
+    reportProviderRefused(e) {
+        var _a;
+        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: (_a = vendorTypeOfLabel(e.vendorLabel)) !== null && _a !== void 0 ? _a : 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. */
     static failureReasonOf(result) {
         return result.reason === 'done' ? result.failureReason : undefined;
@@ -768,12 +826,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, budget) {
+    failSubAgent(reason, budget, providerRefused) {
         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 = Object.assign(Object.assign({ reason }, (budget ? { budget } : {})), (providerRefused ? { providerRefused } : {}));
     }
     /**
      * Returns true if `releaseAgent` was called during the most recent turn.
@@ -1367,6 +1425,8 @@ export class ChatDriver extends EventTarget {
             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', {
@@ -1512,7 +1572,7 @@ export class ChatDriver extends EventTarget {
      */
     invokeSubAgent(name, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            var _a, _b, _c, _d, _e;
+            var _a, _b, _c, _d, _e, _f;
             const subConfig = this.subAgentsMap.get(name);
             if (!subConfig) {
                 const available = [...this.subAgentsMap.keys()].join(', ') || '(none)';
@@ -1710,6 +1770,20 @@ export class ChatDriver extends EventTarget {
                 this.budgetWallViaSubAgent = true;
                 (_e = this.budgetWallDetail) !== null && _e !== void 0 ? _e : (this.budgetWallDetail = failure === null || failure === void 0 ? void 0 : 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;
+                (_f = this.providerRefusedDetail) !== null && _f !== void 0 ? _f : (this.providerRefusedDetail = failure === null || failure === void 0 ? void 0 : failure.providerRefused);
+            }
             return { outcome: { ok: false, reason }, trace };
         });
     }
@@ -1728,6 +1802,8 @@ export class ChatDriver extends EventTarget {
             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',
@@ -1918,7 +1994,7 @@ 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, _l, _m, _o;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q;
             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.');
             }
@@ -1971,6 +2047,31 @@ export class ChatDriver extends EventTarget {
                 // 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: (_a = this.providerRefusedDetail) === null || _a === void 0 ? void 0 : _a.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', {
@@ -1985,7 +2086,7 @@ export class ChatDriver extends EventTarget {
                         // 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,
+                        vendor: (_b = this.budgetWallDetail) === null || _b === void 0 ? void 0 : _b.vendor,
                         via: 'sub-agent',
                         isSubAgent: this.isSubAgent,
                     });
@@ -2008,7 +2109,7 @@ export class ChatDriver extends EventTarget {
                     return this.turnDone('budget-exhausted', this.budgetWallDetail);
                 }
                 const promptCtx = {
-                    agentName: (_b = this.activeAgentName) !== null && _b !== void 0 ? _b : '',
+                    agentName: (_c = this.activeAgentName) !== null && _c !== void 0 ? _c : '',
                     history: this.history,
                     turnIndex: iterations - 1,
                     signal: this.turnController.signal,
@@ -2081,7 +2182,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([
-                    ...((_c = this.primerHistory) !== null && _c !== void 0 ? _c : []),
+                    ...((_d = this.primerHistory) !== null && _d !== void 0 ? _d : []),
                     ...(transientPrimer !== null && transientPrimer !== void 0 ? transientPrimer : []),
                 ]);
                 const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
@@ -2283,6 +2384,37 @@ export class ChatDriver extends EventTarget {
                     // 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: (_e = vendorTypeOfLabel(e.vendorLabel)) !== null && _e !== void 0 ? _e : 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
@@ -2301,7 +2433,7 @@ export class ChatDriver extends EventTarget {
                             recordTurnError(this.sessionKey, 'budget-exhausted', {
                                 agent: this.activeAgentName,
                                 provider: this.lastResolvedProviderName,
-                                vendor: (_e = (_d = vendorTypeOfLabel(e.vendorLabel)) !== null && _d !== void 0 ? _d : vendorTypeOfLabel(e.serverVendor)) !== null && _e !== void 0 ? _e : this.lastResolvedProvider,
+                                vendor: (_g = (_f = vendorTypeOfLabel(e.vendorLabel)) !== null && _f !== void 0 ? _f : vendorTypeOfLabel(e.serverVendor)) !== null && _g !== void 0 ? _g : this.lastResolvedProvider,
                                 budgetUsd: e.budgetUsd,
                                 spentUsd: e.spentUsd,
                                 isSubAgent: true,
@@ -2399,15 +2531,15 @@ export class ChatDriver extends EventTarget {
                 // 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 && ((_f = response.toolCalls) === null || _f === void 0 ? void 0 : _f.length);
-                const isEmptyResponse = !((_g = response.content) === null || _g === void 0 ? void 0 : _g.trim()) && !((_h = response.toolCalls) === null || _h === void 0 ? void 0 : _h.length);
+                const isThinkingStep = response.content && ((_h = response.toolCalls) === null || _h === void 0 ? void 0 : _h.length);
+                const isEmptyResponse = !((_j = response.content) === null || _j === void 0 ? void 0 : _j.trim()) && !((_k = response.toolCalls) === null || _k === void 0 ? void 0 : _k.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 = ((_j = response.responseMeta) === null || _j === void 0 ? void 0 : _j.finishReason) === 'refusal';
+                const isRefusal = ((_l = response.responseMeta) === null || _l === void 0 ? void 0 : _l.finishReason) === 'refusal';
                 if (isEmptyResponse) {
                     emptyResponseAttempts += 1;
                     if (!isRefusal && emptyResponseAttempts < MAX_EMPTY_RESPONSE_RETRIES) {
@@ -2481,7 +2613,7 @@ export class ChatDriver extends EventTarget {
                 emptyResponseAttempts = 0;
                 malformedAttempts = 0;
                 setupTransportAttempts = 0;
-                if (!((_k = response.toolCalls) === null || _k === void 0 ? void 0 : _k.length)) {
+                if (!((_m = response.toolCalls) === null || _m === void 0 ? void 0 : _m.length)) {
                     break;
                 }
                 const [toolCalls, systemCalls] = response.toolCalls.reduce((acc, tc) => {
@@ -2701,7 +2833,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' && ((_l = this.history[i].toolCalls) === null || _l === void 0 ? void 0 : _l.length)) {
+                    if (this.history[i].role === 'assistant' && ((_o = this.history[i].toolCalls) === null || _o === void 0 ? void 0 : _o.length)) {
                         tcMsgIdx = i;
                         break;
                     }
@@ -2739,7 +2871,7 @@ export class ChatDriver extends EventTarget {
                     const unknownTools = [
                         ...new Set([
                             ...this.recentUnknownToolNames,
-                            ...((_m = response.toolCalls) !== null && _m !== void 0 ? _m : [])
+                            ...((_p = response.toolCalls) !== null && _p !== void 0 ? _p : [])
                                 .filter((tc) => unknownToolIds.has(tc.id))
                                 .map((tc) => tc.name),
                         ]),
@@ -2751,7 +2883,7 @@ export class ChatDriver extends EventTarget {
                     const staleTools = [
                         ...new Set([
                             ...this.recentStaleToolNames,
-                            ...((_o = response.toolCalls) !== null && _o !== void 0 ? _o : [])
+                            ...((_q = response.toolCalls) !== null && _q !== void 0 ? _q : [])
                                 .filter((tc) => staleToolIds.has(tc.id))
                                 .map((tc) => tc.name),
                         ]),

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

@@ -1,5 +1,5 @@
 import { __awaiter } from "tslib";
-import { BudgetExhaustedError, DEFAULT_BUDGET_EXHAUSTED_MESSAGE, isChatToolCallUnknown, MalformedFunctionCallError, ResponseTruncatedError, } from '@genesislcap/foundation-ai';
+import { BudgetExhaustedError, DEFAULT_PROVIDER_REFUSED_MESSAGE, ProviderRefusedError, DEFAULT_BUDGET_EXHAUSTED_MESSAGE, isChatToolCallUnknown, MalformedFunctionCallError, ResponseTruncatedError, } from '@genesislcap/foundation-ai';
 import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
 import { AgenticActivityBus } from '../../channel/ai-activity-bus';
 import { clearMetaEventRegistry, getMetaEvents } from '../../state/debug-event-log';
@@ -1860,6 +1860,16 @@ const budgetExhaustedProvider = () => ({
         throw new BudgetExhaustedError('Anthropic', 25, 25.4, 'AI budget exhausted');
     }),
 });
+/** A provider the vendor refused outright (GENC-1506 — terminal, must not retry). */
+const providerRefusedProvider = (kind = 'spend') => ({
+    chat: () => __awaiter(void 0, void 0, void 0, function* () {
+        // Both fixtures are the real captured shapes (2026-08-18), matched to their kind — an `auth`
+        // fixture carrying a credit-balance message would read as a classification bug to the next person.
+        throw kind === 'auth'
+            ? new ProviderRefusedError('Anthropic', 'auth', 401, 'authentication_error', 'API key is invalid.')
+            : new ProviderRefusedError('Anthropic', 'spend', 400, 'invalid_request_error', 'Your credit balance is too low to access the Anthropic API.');
+    }),
+});
 /** A provider that throws a generic error (the sendMessage catch-all → 'exception'). */
 const throwingProvider = () => ({
     chat: () => __awaiter(void 0, void 0, void 0, function* () {
@@ -1950,6 +1960,89 @@ outcome('a clean turn leaves the legacy shape byte-unchanged (no failureReason)'
     cap.stop();
 }));
 // ── Budget exhaustion (GENC-1464) ──────────────────────────────────────────────
+outcome('provider-refused surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
+    yield assertSurfacesReason('provider-refused', providerRefusedProvider(), 'provider-refused');
+}));
+outcome('a provider refusal is terminal — no retry, cause-free copy, kind in the log', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    // GENC-1506. The measured bug this pins: the refusal used to arrive as an untyped transport error,
+    // get re-issued MAX_SETUP_TRANSPORT_RETRIES times against a wall that cannot move, and then surface
+    // as "something went wrong on my end" — wrong twice over, since nothing went wrong on our end and
+    // trying again cannot help.
+    clearMetaEventRegistry();
+    let calls = 0;
+    const provider = {
+        chat: () => __awaiter(void 0, void 0, void 0, function* () {
+            calls += 1;
+            throw new ProviderRefusedError('Anthropic', 'spend', 400, 'invalid_request_error', 'credit too low');
+        }),
+        getStatus: () => __awaiter(void 0, void 0, void 0, function* () { return ({ provider: 'anthropic', model: 'test-model' }); }),
+    };
+    const config = agent({
+        name: 'Static',
+        toolDefinitions: [def('noop')],
+        toolHandlers: { noop: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const driver = makeDriver(config, provider, 'outcome-provider-refused', outcomeBus);
+    const result = yield driver.sendMessage('go');
+    assert.is(calls, 1, 'a provider refusal is not retried — exactly one model call');
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused', 'the turn ends with the provider-refused failure reason');
+    // The kind reaches the CALLER, which is what lets ai-service's Sentry alert say whether an operator
+    // must top up an account or rotate a key. It is the only place that distinction survives, because
+    // the user-facing sentence is deliberately cause-free.
+    const refused = result.reason === 'done' ? result.providerRefused : undefined;
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.kind, 'spend');
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.vendorLabel, 'Anthropic');
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.upstreamStatus, 400);
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.upstreamType, 'invalid_request_error');
+    const last = driver.getHistory().at(-1);
+    assert.ok((last === null || last === void 0 ? void 0 : last.role) === 'assistant', 'turn ends with an assistant message');
+    // Identity, not a substring: the sentence is provisional copy shared with ai-service via one
+    // exported const, and this is what stops a second copy drifting in.
+    assert.is(last.content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+    assert.not.ok(last.content.includes('something went wrong'), 'must not fall through to the generic apology');
+    // The copy must not leak the cause, whatever the kind — a user who can see remaining spend must not
+    // be told about a limit, and we must not imply the bill went unpaid.
+    for (const banned of ['credit', 'billing', 'balance', 'quota', 'limit']) {
+        assert.not.ok(last.content.toLowerCase().includes(banned), `copy must not mention "${banned}"`);
+    }
+    const err = getMetaEvents('outcome-provider-refused').find((e) => e.type === 'turn.error');
+    assert.is((_a = err === null || err === void 0 ? void 0 : err.detail) === null || _a === void 0 ? void 0 : _a.reason, 'provider-refused');
+    assert.is((_b = err === null || err === void 0 ? void 0 : err.detail) === null || _b === void 0 ? void 0 : _b.kind, 'spend');
+}));
+outcome('an auth refusal shows the SAME sentence but logs a different kind', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    // The whole justification for one type with two kinds: identical user experience, distinct
+    // diagnostics. If these ever diverge in the transcript, the copy decision has been undone.
+    clearMetaEventRegistry();
+    const config = agent({
+        name: 'Static',
+        toolDefinitions: [def('noop')],
+        toolHandlers: { noop: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const driver = makeDriver(config, providerRefusedProvider('auth'), 'outcome-refused-auth', outcomeBus);
+    const result = yield driver.sendMessage('go');
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused');
+    assert.is(result.reason === 'done' ? (_a = result.providerRefused) === null || _a === void 0 ? void 0 : _a.kind : undefined, 'auth');
+    assert.is(driver.getHistory().at(-1).content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+}));
+outcome('a host override replaces the provider-refusal sentence verbatim', () => __awaiter(void 0, void 0, void 0, function* () {
+    const config = agent({
+        name: 'Static',
+        toolDefinitions: [def('noop')],
+        toolHandlers: { noop: () => __awaiter(void 0, void 0, void 0, function* () { return 'ok'; }) },
+    });
+    const driver = new ChatDriver(makeRegistry(providerRefusedProvider()), {
+        maxToolIterations: 50,
+        maxFoldOperations: 5,
+        sessionKey: 'outcome-refused-override',
+        providerRefusedMessage: 'Bespoke wording for a white-labelled host.',
+    });
+    driver.applyAgent(config);
+    yield driver.sendMessage('go');
+    assert.is(driver.getHistory().at(-1).content, 'Bespoke wording for a white-labelled host.');
+    driver.dispose();
+}));
 outcome('budget-exhausted surfaces at both seams', () => __awaiter(void 0, void 0, void 0, function* () {
     yield assertSurfacesReason('budget', budgetExhaustedProvider(), 'budget-exhausted');
 }));
@@ -2247,6 +2340,122 @@ const walledWorker = () => agent({
     toolDefinitions: [def('finish')],
     toolHandlers: { finish: () => __awaiter(void 0, void 0, void 0, function* () { return 'x'; }) },
 });
+/**
+ * The child-refused / parent-fine provider, mirroring `parentOkChildWalled` — the parent's turn call
+ * succeeds and delegates, and only the child's provider refuses.
+ */
+const parentOkChildRefused = (kind = 'spend') => {
+    let parentCalls = 0;
+    return {
+        parentCalls: () => parentCalls,
+        provider: {
+            chat: (_h, _u, options) => __awaiter(void 0, void 0, void 0, function* () {
+                var _a;
+                const names = ((_a = options === null || options === void 0 ? void 0 : options.tools) !== null && _a !== void 0 ? _a : []).map((t) => t.name);
+                if (names.includes('delegate')) {
+                    parentCalls += 1;
+                    return callsTool('delegate', `d${parentCalls}`);
+                }
+                throw kind === 'auth'
+                    ? new ProviderRefusedError('Anthropic', 'auth', 401, 'authentication_error', 'API key is invalid.')
+                    : new ProviderRefusedError('Anthropic', 'spend', 400, 'invalid_request_error', 'credit too low');
+            }),
+        },
+    };
+};
+outcome('a sub-agent provider refusal ends the parent turn without another model call', () => __awaiter(void 0, void 0, void 0, function* () {
+    /*
+     * The seam a review caught, and it is genuinely counter-intuitive: the child is a SEPARATE driver
+     * instance, so the flag it sets on itself is invisible to the parent. The refusal reaches the parent
+     * only as a tool result, and without an `invokeSubAgent` branch that result was ordinary — so the
+     * parent issued another model call straight into the same wall, and if that call had happened to
+     * succeed the turn could have finished with no `failureReason` at all, reporting a clean turn over a
+     * dead account. `parentCalls() === 1` is the assertion that pins it.
+     */
+    clearMetaEventRegistry();
+    const { parentCalls, provider } = parentOkChildRefused();
+    const parent = delegatingParent(walledWorker(), () => undefined);
+    const driver = makeDriver(parent, provider, 'outcome-subagent-refused', outcomeBus);
+    const result = yield driver.sendMessage('go');
+    assert.is(parentCalls(), 1, 'the parent never calls the model again after the refusal');
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused');
+    assert.is(driver.getHistory().at(-1).content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+}));
+outcome("a sub-agent refusal carries the CHILD's kind and vendor to the parent", () => __awaiter(void 0, void 0, void 0, function* () {
+    // The other half of the same finding. The parent can only report what the child bubbled, so without a
+    // payload on the failure the `providerRefused` diagnostic promised on `ChatDriverResult` would be
+    // absent — and with cause-free user copy that payload is the ONLY place an operator learns whether to
+    // top up an account or rotate a credential.
+    clearMetaEventRegistry();
+    const { provider } = parentOkChildRefused('auth');
+    const parent = delegatingParent(walledWorker(), () => undefined);
+    const driver = makeDriver(parent, provider, 'outcome-subagent-refused-kind', outcomeBus);
+    const result = yield driver.sendMessage('go');
+    const refused = result.reason === 'done' ? result.providerRefused : undefined;
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.kind, 'auth', "the child's kind survives the hop");
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.vendorLabel, 'Anthropic');
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.upstreamStatus, 401);
+}));
+outcome("a GRANDCHILD's refusal keeps its kind and vendor across two hops", () => __awaiter(void 0, void 0, void 0, function* () {
+    /*
+     * The third finding, and the one a single-hop test cannot reach. An INTERMEDIATE sub-agent latches its
+     * grandchild's payload correctly via `invokeSubAgent`, but then has to hand it on through
+     * `failSubAgent` — and passing only the reason there still stopped the top-level turn (the reason
+     * travels) while arriving with no vendor and no kind. The turn looked handled and the diagnostics were
+     * gone, which is the failure mode this payload exists to prevent.
+     *
+     * Three tiers: boss -> middle -> worker. Only the worker's turn is refused; every other model call
+     * succeeds, so nothing but the forwarding can carry the detail to the top.
+     */
+    clearMetaEventRegistry();
+    const worker = agent({
+        name: 'worker',
+        toolDefinitions: [def('finish')],
+        toolHandlers: { finish: () => __awaiter(void 0, void 0, void 0, function* () { return 'x'; }) },
+    });
+    const middle = agent({
+        name: 'middle',
+        subAgents: [worker],
+        toolDefinitions: [def('sub_delegate')],
+        toolHandlers: {
+            sub_delegate: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                const o = yield ctx.requestSubAgent('worker', { task: 'deeper' });
+                return o.ok ? 'ok' : `failed: ${o.reason}`;
+            }),
+        },
+    });
+    const boss = agent({
+        name: 'boss',
+        subAgents: [middle],
+        toolDefinitions: [def('delegate')],
+        toolHandlers: {
+            delegate: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                const o = yield ctx.requestSubAgent('middle', { task: 'do it' });
+                return o.ok ? 'ok' : `failed: ${o.reason}`;
+            }),
+        },
+    });
+    // Routed by the tool surface each tier is given, so only the deepest turn throws.
+    const provider = {
+        chat: (_h, _u, options) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            const names = ((_a = options === null || options === void 0 ? void 0 : options.tools) !== null && _a !== void 0 ? _a : []).map((t) => t.name);
+            if (names.includes('delegate'))
+                return callsTool('delegate', 'd1');
+            if (names.includes('sub_delegate'))
+                return callsTool('sub_delegate', 's1');
+            throw new ProviderRefusedError('Anthropic', 'auth', 401, 'authentication_error', 'API key is invalid.');
+        }),
+    };
+    const driver = makeDriver(boss, provider, 'outcome-refused-grandchild', outcomeBus);
+    const result = yield driver.sendMessage('go');
+    assert.is(result.reason === 'done' ? result.failureReason : undefined, 'provider-refused');
+    const refused = result.reason === 'done' ? result.providerRefused : undefined;
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.kind, 'auth', "the grandchild's kind survives BOTH hops");
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.vendorLabel, 'Anthropic');
+    assert.is(refused === null || refused === void 0 ? void 0 : refused.upstreamStatus, 401);
+    assert.is(driver.getHistory().at(-1).content, DEFAULT_PROVIDER_REFUSED_MESSAGE);
+}));
 outcome('a sub-agent budget wall ends the parent turn without another model call', () => __awaiter(void 0, void 0, void 0, function* () {
     clearMetaEventRegistry();
     const { parentCalls, provider } = parentOkChildWalled();

package/dist/esm/state/debug-event-log.js

@@ -210,7 +210,7 @@ export const DEBUG_LOG_README = [
     "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.',

package/dist/esm/state/debug-event-log.test.js

@@ -84,6 +84,7 @@ const ALL_TURN_FAILURE_REASONS = Object.keys({
     'response-truncated': true,
     refusal: true,
     'budget-exhausted': true,
+    'provider-refused': true,
 });
 const ALL_SUB_AGENT_FAILURE_REASONS = Object.keys({
     max_iterations: true,
@@ -94,6 +95,7 @@ const ALL_SUB_AGENT_FAILURE_REASONS = Object.keys({
     response_truncated: true,
     refusal: true,
     budget_exhausted: true,
+    provider_refused: true,
 });
 const README_TEXT = DEBUG_LOG_README.join('\n');
 suite('DEBUG_LOG_README enumerates every TurnFailureReason', () => {