@genesislcap/ai-assistant 15.13.0 → 15.13.1-GENC-1506.1

package/dist/ai-assistant.api.json

@@ -5923,6 +5923,33 @@
                 "endIndex": 3
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriverConfig#providerRefusedMessage:member",
+              "docComment": "/**\n * Overrides the transcript sentence shown when the upstream PROVIDER refuses the account (GENC-1506) — see `DEFAULT_PROVIDER_REFUSED_MESSAGE`.\n *\n * Separate from `budgetExhaustedMessage` because the two conditions are separate: ours is a spend cap a host administrator can raise, this is the vendor declining to serve us at all. A host that white-labels one will usually want to white-label both, but conflating them into one field would force identical copy on two situations with different remedies.\n *\n * Rarely needed: unlike the budget default, the shipped sentence names no vendor and no Genesis, so it is already safe for a white-labelled deployment.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "providerRefusedMessage?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "providerRefusedMessage",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriverConfig#sessionKey:member",

package/dist/ai-assistant.d.ts

@@ -1524,6 +1524,24 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * and the bubble is composed per wall by {@link ChatDriver.budgetExhaustedBubble}.
      */
     private readonly budgetExhaustedMessageOverride?;
+    /**
+     * Host override for the provider-refusal sentence, from
+     * `ChatDriverConfig.providerRefusedMessage`. `undefined` means no override, so the shipped default
+     * is used verbatim.
+     */
+    private readonly providerRefusedMessageOverride?;
+    /**
+     * A provider refusal was observed this turn, so the tool loop must not call the model again
+     * (GENC-1506).
+     *
+     * Exists for the SUB-AGENT path only, exactly like `budgetExhaustedThisTurn`: this driver's own
+     * refusal returns straight out of the catch, whereas a child's refusal reaches the parent as a tool
+     * result, and without this flag the loop would issue another call into the same wall — N batched
+     * children costing N doomed calls plus a doomed parent one.
+     */
+    private providerRefusedThisTurn;
+    /** The refusal detail latched off a sub-agent's failure, for the parent's own result. */
+    private providerRefusedDetail?;
     /**
      * Set the moment a budget wall is observed anywhere in this turn — this
      * driver's own 402, or a sub-agent's (which surfaces here only as a
@@ -1629,6 +1647,24 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      */
     private budgetExhaustedBubble;
     reportBudgetExhausted(e: BudgetExhaustedError, pendingUserMessage?: ChatMessage): ChatDriverResult;
+    /**
+     * The sentence shown when the upstream provider refuses (GENC-1506).
+     *
+     * Deliberately far simpler than `budgetExhaustedBubble`: no vendor name, no figures, no
+     * switch-provider advice, and no branching on `kind`. The copy is cause-free by design — a user who
+     * can see their own remaining spend must not be told about a limit, and we must not imply the bill
+     * has gone unpaid — so there is nothing here to compose. A host override wins verbatim.
+     */
+    private providerRefusedBubble;
+    /**
+     * Terminal provider-refusal outcome. Mirrors `reportBudgetExhausted` so the two walls behave
+     * identically from the caller's side, while keeping their diagnostics distinct.
+     *
+     * `kind` reaches the debug log and the result but never the transcript: it is what lets an operator
+     * tell "top up the account" from "rotate the key", and with cause-free user copy this is the only
+     * place that distinction survives.
+     */
+    private reportProviderRefused;
     /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
     private static failureReasonOf;
     /**
@@ -1980,6 +2016,19 @@ export declare interface ChatDriverConfig {
      * reversible change.
      */
     budgetExhaustedMessage?: string;
+    /**
+     * Overrides the transcript sentence shown when the upstream PROVIDER refuses the account
+     * (GENC-1506) — see `DEFAULT_PROVIDER_REFUSED_MESSAGE`.
+     *
+     * Separate from `budgetExhaustedMessage` because the two conditions are separate: ours is a spend
+     * cap a host administrator can raise, this is the vendor declining to serve us at all. A host that
+     * white-labels one will usually want to white-label both, but conflating them into one field would
+     * force identical copy on two situations with different remedies.
+     *
+     * Rarely needed: unlike the budget default, the shipped sentence names no vendor and no Genesis, so
+     * it is already safe for a white-labelled deployment.
+     */
+    providerRefusedMessage?: string;
 }
 
 export { ChatFallback }
@@ -2314,9 +2363,9 @@ export declare interface FallbackAgentConfig extends BaseAgentConfig {
  *
  * @internal
  */
-export declare function formatBlockedReason(budget?: Extract<ChatDriverResult, {
+export declare function formatBlockedReason(budget?: Partial<Extract<ChatDriverResult, {
     reason: 'done';
-}>['budget'], vendor?: AIProviderType): string | undefined;
+}>['budget']>, vendor?: AIProviderType): string | undefined;
 
 /**
  * Foundation AI Assistant component.
@@ -2778,11 +2827,18 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     private get relevantBlockedVendors();
     /**
-     * Whether the blocked banner has anything to say — a vendor-agnostic block, OR
-     * at least one walled vendor the registry can still reach. Broader than
-     * {@link FoundationAiAssistant.blocked} on purpose: partial exhaustion leaves
-     * the composer live but still needs to be announced, because the next turn may
-     * route to the walled vendor and fail.
+     * Whether the blocked banner has anything to say — a vendor-agnostic block, or
+     * a partial wall that the NEXT send would actually hit.
+     *
+     * Partial exhaustion is announced only while the ACTIVE vendor (the registry
+     * default the next send resolves to) is among the walled ones. A user who has
+     * switched to a vendor with headroom has already acted on the advice —
+     * keeping the banner up past that point nagged about a vendor they just left
+     * (GENC-1464 tester feedback), while switching BACK to the walled vendor
+     * brings the banner straight back. Two conservative fallbacks keep it
+     * fail-informative: while the statuses are still loading the active vendor is
+     * unknowable, so any reachable-and-walled vendor still announces; and a
+     * vendor-agnostic block announces always, exactly as before.
      *
      * Reads the reachability-filtered list for the same reason the copy does — a
      * host that has swapped its registry away from the walled vendor has nothing
@@ -2809,6 +2865,15 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * @internal
      */
     get suggestionsBlocked(): boolean;
+    /**
+     * The vendor the NEXT send resolves to — the registry default's provider, as
+     * reported through `providerStatuses`. `undefined` while the statuses are
+     * still loading (or when the default reports the `'none'` sentinel), which
+     * every consumer treats conservatively.
+     *
+     * @internal
+     */
+    private get activeVendor();
     /**
      * Explanation shown in the blocked banner, or `null` for the element's default
      * copy. Only meaningful while {@link FoundationAiAssistant.blocked} is true;
@@ -2957,12 +3022,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * vendors watched all of it vanish the moment a second one walled — replaced by
      * generic copy, at the exact moment the situation got worse.
      *
-     * The compact "AI usage limits are reached for A and B." list is kept for the
-     * case it was written for: NO walled vendor carries copy, so a statement per
-     * vendor would just repeat one boilerplate sentence per name. As soon as any of
-     * them does carry copy, the branch lists one statement per vendor instead —
-     * falling back to that same boilerplate for the ones that have none, so the
-     * sentence set stays complete rather than silently naming a subset.
+     * The compact list is the DEFAULT shape for several walls, now carrying each
+     * vendor's figures: "AI usage limits are reached for Gemini ($62.34 of $50.00)
+     * and Anthropic ($31.10 of $30.00)." A driver latch stores no copy of its own
+     * (it stores the figures, which this composes from), so that shape is what the
+     * real budget flow produces. As soon as any walled vendor carries HOST copy,
+     * which cannot be folded into a list item, the branch lists one statement per
+     * vendor instead — falling back to composed copy for the ones that have none, so
+     * the sentence set stays complete rather than silently naming a subset.
      *
      * @internal
      */

package/dist/chat-driver.cjs

@@ -26,6 +26,7 @@ __export(chat_driver_node_exports, {
   AnthropicProvider: () => AnthropicProvider,
   AnthropicTransport: () => AnthropicTransport,
   ChatDriver: () => ChatDriver,
+  DEFAULT_PROVIDER_REFUSED_MESSAGE: () => DEFAULT_PROVIDER_REFUSED_MESSAGE,
   GEMINI_CACHED_INPUT_MULTIPLIER: () => GEMINI_CACHED_INPUT_MULTIPLIER,
   GEMINI_LONG_CONTEXT_THRESHOLD: () => GEMINI_LONG_CONTEXT_THRESHOLD,
   GeminiProvider: () => GeminiProvider,
@@ -33,6 +34,8 @@ __export(chat_driver_node_exports, {
   MutableAIProviderRegistry: () => MutableAIProviderRegistry,
   NOOP_ACTIVITY_BUS: () => NOOP_ACTIVITY_BUS,
   OrchestratingDriver: () => OrchestratingDriver,
+  PROVIDER_REFUSED_CODE: () => PROVIDER_REFUSED_CODE,
+  ProviderRefusedError: () => ProviderRefusedError,
   REQUEST_CONTINUATION_TOOL: () => REQUEST_CONTINUATION_TOOL,
   SUPPORTED_ANTHROPIC_MODEL_IDS: () => SUPPORTED_ANTHROPIC_MODEL_IDS,
   SUPPORTED_GEMINI_MODEL_IDS: () => SUPPORTED_GEMINI_MODEL_IDS,
@@ -1105,6 +1108,78 @@ function budgetExhaustedFrom(vendorLabel, payload, fallbackDetail) {
   });
 }
 
+// ../../foundation-ai/dist/esm/transports/provider-refused.js
+var PROVIDER_REFUSED_CODE = "PROVIDER_REFUSED";
+var DEFAULT_PROVIDER_REFUSED_MESSAGE = "AI requests are currently being refused by the provider. This isn't related to your account or your usage and needs no action from you \u2014 please contact your support team so it can be restored.";
+var ProviderRefusedError = class extends Error {
+  constructor(vendorLabel, kind, upstreamStatus, upstreamType, detail) {
+    super(`${vendorLabel} refused the request (${kind})` + (upstreamStatus != null ? ` \u2014 HTTP ${upstreamStatus}` : "") + (upstreamType ? ` ${upstreamType}` : "") + (detail ? `: ${detail}` : "") + ". Retrying will not clear this \u2014 the provider account must be fixed.");
+    this.vendorLabel = vendorLabel;
+    this.kind = kind;
+    this.upstreamStatus = upstreamStatus;
+    this.upstreamType = upstreamType;
+    this.detail = detail;
+    this.name = "ProviderRefusedError";
+  }
+};
+var ANTHROPIC_SPEND_PHRASES = Object.freeze([
+  /credit balance/i,
+  /usage limit/i,
+  /spend limit/i,
+  /insufficient (credit|funds|balance)/i
+]);
+var ANTHROPIC_AUTH_TYPES = Object.freeze([
+  "authentication_error",
+  "permission_error"
+]);
+function anthropicErrorBody(payload) {
+  var _a;
+  const outer = typeof payload === "object" && payload !== null ? payload : {};
+  for (const candidate of [
+    outer.error,
+    (_a = outer.details) === null || _a === void 0 ? void 0 : _a.error
+  ]) {
+    if (typeof candidate === "object" && candidate !== null) {
+      const { type, message } = candidate;
+      return {
+        type: typeof type === "string" ? type : void 0,
+        message: typeof message === "string" ? message : void 0
+      };
+    }
+  }
+  return void 0;
+}
+function providerRefusalOf(vendor, code, payload) {
+  if (code === PROVIDER_REFUSED_CODE) {
+    const kind = payload === null || payload === void 0 ? void 0 : payload.kind;
+    return kind === "auth" ? "auth" : "spend";
+  }
+  if (vendor !== "anthropic")
+    return void 0;
+  const body = anthropicErrorBody(payload);
+  if (!(body === null || body === void 0 ? void 0 : body.type))
+    return void 0;
+  if (ANTHROPIC_AUTH_TYPES.includes(body.type))
+    return "auth";
+  if (body.type === "billing_error")
+    return "spend";
+  if (body.type === "invalid_request_error" && body.message) {
+    const message = body.message;
+    if (ANTHROPIC_SPEND_PHRASES.some((phrase) => phrase.test(message)))
+      return "spend";
+  }
+  return void 0;
+}
+function providerRefusedFrom(vendorLabel, kind, upstreamStatus, payload, fallbackDetail) {
+  var _a;
+  const body = anthropicErrorBody(payload);
+  return new ProviderRefusedError(vendorLabel, kind, upstreamStatus, body === null || body === void 0 ? void 0 : body.type, (_a = body === null || body === void 0 ? void 0 : body.message) !== null && _a !== void 0 ? _a : fallbackDetail);
+}
+function vendorOfTransportLabel(vendorLabel) {
+  const entry = Object.entries(VENDOR_LABELS).find(([, label]) => label === vendorLabel);
+  return entry === null || entry === void 0 ? void 0 : entry[0];
+}
+
 // ../../foundation-ai/dist/esm/types/config.types.js
 var SUPPORTED_GEMINI_MODEL_IDS = [
   "gemini-2.5-pro",
@@ -1523,13 +1598,70 @@ function readFramedBody(stream, onChunk, vendorLabel, stallTimeout) {
   });
 }
 
+// ../../foundation-ai/dist/esm/transports/retry-hints.js
+var MAX_SERVER_REQUESTED_BACKOFF_MS = 6e4;
+var SHOULD_RETRY_HEADER = "x-should-retry";
+var MS_PER_SECOND = 1e3;
+function shouldNotRetry(headers) {
+  var _a;
+  const value = (_a = headers === null || headers === void 0 ? void 0 : headers.get) === null || _a === void 0 ? void 0 : _a.call(headers, SHOULD_RETRY_HEADER);
+  return typeof value === "string" && value.trim().toLowerCase() === "false";
+}
+function retryAfterMs(headers) {
+  var _a;
+  const raw = (_a = headers === null || headers === void 0 ? void 0 : headers.get) === null || _a === void 0 ? void 0 : _a.call(headers, "retry-after");
+  if (typeof raw !== "string" || raw.trim() === "")
+    return void 0;
+  const seconds = Number(raw.trim());
+  if (Number.isFinite(seconds))
+    return Math.max(0, seconds * MS_PER_SECOND);
+  const at = Date.parse(raw);
+  if (Number.isNaN(at))
+    return void 0;
+  return Math.max(0, at - Date.now());
+}
+function retryInfoMs(payload) {
+  const outer = typeof payload === "object" && payload !== null ? payload : {};
+  const framed = typeof outer.details === "object" && outer.details !== null ? outer.details : void 0;
+  for (const holder of [outer.error, framed === null || framed === void 0 ? void 0 : framed.error]) {
+    const details = holder === null || holder === void 0 ? void 0 : holder.details;
+    if (!Array.isArray(details))
+      continue;
+    for (const entry of details) {
+      const type = entry === null || entry === void 0 ? void 0 : entry["@type"];
+      if (typeof type !== "string" || !type.endsWith("google.rpc.RetryInfo"))
+        continue;
+      const delay = entry.retryDelay;
+      if (typeof delay !== "string")
+        continue;
+      const seconds = Number(delay.replace(/s$/, ""));
+      if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds * MS_PER_SECOND;
+    }
+  }
+  return void 0;
+}
+function resolveBackoffMs(attempt, baseMs, serverMs) {
+  const ladder = baseMs * Math.pow(2, attempt);
+  if (serverMs == null || !Number.isFinite(serverMs))
+    return ladder;
+  return Math.max(ladder, Math.min(serverMs, MAX_SERVER_REQUESTED_BACKOFF_MS));
+}
+
 // ../../foundation-ai/dist/esm/transports/post-with-retry.js
 var MAX_RETRIES = 5;
 function postWithRetry(options) {
   return __awaiter(this, void 0, void 0, function* () {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     const { url, headers, body, credentials, vendorLabel, retryableStatuses, timeout, stallTimeout, backoffBaseMs, signal } = options;
-    const backoff = (attempt) => abortableDelay(backoffBaseMs * (1 << attempt), signal);
+    const vendor = vendorOfTransportLabel(vendorLabel);
+    const backoff = (attempt, serverMs) => {
+      const waitMs = resolveBackoffMs(attempt, backoffBaseMs, serverMs);
+      if (serverMs != null && waitMs > backoffBaseMs * Math.pow(2, attempt)) {
+        logger.warn(`${vendorLabel}Transport: honouring the server's requested retry delay (${Math.round(waitMs)}ms, asked ${Math.round(serverMs)}ms)`);
+      }
+      return abortableDelay(waitMs, signal);
+    };
     for (let attempt = 0; attempt <= MAX_RETRIES; attempt += 1) {
       const timeoutController = new AbortController();
       const startedAt = performance.now();
@@ -1563,24 +1695,33 @@ function postWithRetry(options) {
         if (!response.ok) {
           const errText = yield response.text();
           const parsed = parseJsonOrUndefined(errText);
+          const refusal = providerRefusalOf(vendor, codeOf(parsed), parsed);
+          if (refusal) {
+            throw providerRefusedFrom(vendorLabel, refusal, response.status, parsed, errText || void 0);
+          }
           if (isBudgetRejection(response.status, codeOf(parsed))) {
             throw budgetExhaustedFrom(vendorLabel, parsed, errText || void 0);
           }
-          if (retryableStatuses.includes(response.status) && attempt < MAX_RETRIES) {
+          const refusedRetry = shouldNotRetry(response.headers);
+          if (retryableStatuses.includes(response.status) && !refusedRetry && attempt < MAX_RETRIES) {
             logger.warn(`${vendorLabel}Transport: retryable status ${response.status}, retrying (attempt ${attempt + 1}/${MAX_RETRIES})`);
             clearTimeout(timeoutId);
-            yield backoff(attempt);
+            yield backoff(attempt, (_d = retryAfterMs(response.headers)) !== null && _d !== void 0 ? _d : retryInfoMs(parsed));
             continue;
           }
           throw new Error(`${vendorLabel} request error ${response.status}: ${errText}`);
         }
-        if (((_e = (_d = response.headers) === null || _d === void 0 ? void 0 : _d.get("content-type")) === null || _e === void 0 ? void 0 : _e.toLowerCase().includes("application/x-ndjson")) && response.body) {
+        if (((_f = (_e = response.headers) === null || _e === void 0 ? void 0 : _e.get("content-type")) === null || _f === void 0 ? void 0 : _f.toLowerCase().includes("application/x-ndjson")) && response.body) {
           rearmStallTimer();
           const frame = yield readFramedBody(response.body, rearmStallTimer, vendorLabel, stallTimeout);
           if (frame.t === "ok")
             return frame.body;
           if (frame.code === "UPSTREAM_STALLED") {
-            throw new DOMException(`${vendorLabel} request stalled: ${(_f = frame.error) !== null && _f !== void 0 ? _f : "no upstream data"}`, "TimeoutError");
+            throw new DOMException(`${vendorLabel} request stalled: ${(_g = frame.error) !== null && _g !== void 0 ? _g : "no upstream data"}`, "TimeoutError");
+          }
+          const framedRefusal = providerRefusalOf(vendor, frame.code, frame);
+          if (framedRefusal) {
+            throw providerRefusedFrom(vendorLabel, framedRefusal, frame.status, frame, frame.error);
           }
           if (isBudgetRejection(frame.status, frame.code)) {
             throw budgetExhaustedFrom(vendorLabel, frame);
@@ -1588,10 +1729,10 @@ function postWithRetry(options) {
           if (retryableStatuses.includes(frame.status) && attempt < MAX_RETRIES) {
             logger.warn(`${vendorLabel}Transport: retryable status ${frame.status} (err frame), retrying (attempt ${attempt + 1}/${MAX_RETRIES})`);
             clearTimeout(timeoutId);
-            yield backoff(attempt);
+            yield backoff(attempt, retryInfoMs(frame));
             continue;
           }
-          throw new Error(`${vendorLabel} request error ${frame.status}: ${(_g = frame.error) !== null && _g !== void 0 ? _g : JSON.stringify(frame.details)}`);
+          throw new Error(`${vendorLabel} request error ${frame.status}: ${(_h = frame.error) !== null && _h !== void 0 ? _h : JSON.stringify(frame.details)}`);
         }
         return yield response.json();
       } catch (e) {
@@ -3671,6 +3812,12 @@ function accumulate(messages, into) {
 var TOOL_FOLD_SYMBOL = Symbol("toolFold");
 
 // src/components/chat-driver/chat-driver.ts
+var providerRefusedDetailOf = (e) => ({
+  vendorLabel: e.vendorLabel,
+  kind: e.kind,
+  ...e.upstreamStatus != null ? { upstreamStatus: e.upstreamStatus } : {},
+  ...e.upstreamType ? { upstreamType: e.upstreamType } : {}
+});
 var budgetDetailOf = (e) => {
   const vendor = vendorTypeOfLabel(e.vendorLabel) ?? vendorTypeOfLabel(e.serverVendor);
   if (e.budgetUsd == null && e.spentUsd == null && !vendor) return void 0;
@@ -3866,6 +4013,16 @@ var ChatDriver = class _ChatDriver extends EventTarget {
      * picked up on the next turn.
      */
     this.resolvedStatusCache = /* @__PURE__ */ 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
@@ -3893,13 +4050,15 @@ var ChatDriver = class _ChatDriver extends EventTarget {
       maxTurnSnapshots = DEFAULT_MAX_TURN_SNAPSHOTS,
       sessionKey = "",
       activityBus = NOOP_ACTIVITY_BUS,
-      budgetExhaustedMessage
+      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 = {};
@@ -4006,9 +4165,14 @@ var ChatDriver = 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" };
-    return budget ? { reason: "done", failureReason, budget } : { reason: "done", failureReason };
+    return {
+      reason: "done",
+      failureReason,
+      ...budget ? { budget } : {},
+      ...providerRefused ? { providerRefused } : {}
+    };
   }
   /**
    * Terminal budget outcome for a wall hit **outside** the tool loop — today,
@@ -4063,6 +4227,42 @@ var ChatDriver = 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() {
+    return this.providerRefusedMessageOverride ?? DEFAULT_PROVIDER_REFUSED_MESSAGE;
+  }
+  /**
+   * Terminal provider-refusal outcome. Mirrors `reportBudgetExhausted` so the two walls behave
+   * identically from the caller's side, while keeping their diagnostics distinct.
+   *
+   * `kind` reaches the debug log and the result but never the transcript: it is what lets an operator
+   * tell "top up the account" from "rotate the key", and with cause-free user copy this is the only
+   * place that distinction survives.
+   */
+  reportProviderRefused(e) {
+    const detail = providerRefusedDetailOf(e);
+    this.providerRefusedThisTurn = true;
+    this.providerRefusedDetail = detail;
+    logger2.error("ChatDriver: provider refused the request", e);
+    recordTurnError(this.sessionKey, "provider-refused", {
+      agent: this.activeAgentName,
+      provider: this.lastResolvedProviderName,
+      vendor: vendorTypeOfLabel(e.vendorLabel) ?? this.lastResolvedProvider,
+      kind: e.kind,
+      upstreamStatus: e.upstreamStatus,
+      upstreamType: e.upstreamType,
+      isSubAgent: this.isSubAgent
+    });
+    this.appendToHistory({ role: "assistant", content: this.providerRefusedBubble() });
+    return this.turnDone("provider-refused", void 0, 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 : void 0;
@@ -4747,6 +4947,8 @@ Output format (strict):
     this.budgetExhaustedThisTurn = false;
     this.budgetWallDetail = void 0;
     this.budgetWallViaSubAgent = false;
+    this.providerRefusedThisTurn = false;
+    this.providerRefusedDetail = void 0;
     this.appendToHistory({ role: "user", content: userInput, attachments });
     this.turnStartedAt = Date.now();
     recordMetaEvent(this.sessionKey, "turn.start", {
@@ -5006,6 +5208,8 @@ Output format (strict):
     this.budgetExhaustedThisTurn = false;
     this.budgetWallDetail = void 0;
     this.budgetWallViaSubAgent = false;
+    this.providerRefusedThisTurn = false;
+    this.providerRefusedDetail = void 0;
     this.turnStartedAt = Date.now();
     recordMetaEvent(this.sessionKey, "turn.start", {
       phase: "continueFromHistory",
@@ -5195,6 +5399,22 @@ Output format (strict):
       if (this.turnController.signal.aborted) {
         return this.completeAbortedTurn();
       }
+      if (this.providerRefusedThisTurn) {
+        logger2.error("ChatDriver: ending the turn \u2014 a sub-agent hit the provider wall");
+        recordTurnError(this.sessionKey, "provider-refused", {
+          agent: this.activeAgentName,
+          provider: this.lastResolvedProviderName,
+          kind: this.providerRefusedDetail?.kind,
+          via: "sub-agent",
+          isSubAgent: this.isSubAgent
+        });
+        if (this.isSubAgent) {
+          this.failSubAgent("provider_refused");
+        } else {
+          this.appendToHistory({ role: "assistant", content: this.providerRefusedBubble() });
+        }
+        return this.turnDone("provider-refused", void 0, this.providerRefusedDetail);
+      }
       if (this.budgetExhaustedThisTurn) {
         logger2.error("ChatDriver: ending the turn \u2014 a sub-agent hit the AI budget wall");
         recordTurnError(this.sessionKey, "budget-exhausted", {
@@ -5422,6 +5642,25 @@ ${tailBody}
           }
           return this.turnDone("response-truncated");
         }
+        if (e instanceof ProviderRefusedError) {
+          if (this.isSubAgent) {
+            logger2.error("ChatDriver: provider refused the request", e);
+            recordTurnError(this.sessionKey, "provider-refused", {
+              agent: this.activeAgentName,
+              provider: this.lastResolvedProviderName,
+              vendor: vendorTypeOfLabel(e.vendorLabel) ?? this.lastResolvedProvider,
+              kind: e.kind,
+              upstreamStatus: e.upstreamStatus,
+              upstreamType: e.upstreamType,
+              isSubAgent: true
+            });
+            this.providerRefusedThisTurn = true;
+            this.providerRefusedDetail = providerRefusedDetailOf(e);
+            this.failSubAgent("provider_refused");
+            return this.turnDone("provider-refused", void 0, this.providerRefusedDetail);
+          }
+          return this.reportProviderRefused(e);
+        }
         if (e instanceof BudgetExhaustedError) {
           this.budgetExhaustedThisTurn = true;
           this.budgetWallDetail = budgetDetailOf(e);
@@ -6779,6 +7018,7 @@ function withFreshMetaSnapshot(stored, fresh) {
   AnthropicProvider,
   AnthropicTransport,
   ChatDriver,
+  DEFAULT_PROVIDER_REFUSED_MESSAGE,
   GEMINI_CACHED_INPUT_MULTIPLIER,
   GEMINI_LONG_CONTEXT_THRESHOLD,
   GeminiProvider,
@@ -6786,6 +7026,8 @@ function withFreshMetaSnapshot(stored, fresh) {
   MutableAIProviderRegistry,
   NOOP_ACTIVITY_BUS,
   OrchestratingDriver,
+  PROVIDER_REFUSED_CODE,
+  ProviderRefusedError,
   REQUEST_CONTINUATION_TOOL,
   SUPPORTED_ANTHROPIC_MODEL_IDS,
   SUPPORTED_GEMINI_MODEL_IDS,