@genesislcap/foundation-ai 15.14.1 → 15.14.2

package/dist/esm/transports/provider-refused.js

@@ -0,0 +1,312 @@
+/**
+ * The PROVIDER wall (GENC-1506) — the upstream vendor refusing this account, as opposed to the
+ * ai-service proxy refusing this user's own spend budget (`budget-exhausted-error.ts`, GENC-1464).
+ *
+ * The two are constantly confused, so state the difference once: a
+ * {@link BudgetExhaustedError} means *we* declined to spend more on the caller's behalf and an
+ * administrator can raise the cap; a {@link ProviderRefusedError} means *Anthropic or Google*
+ * declined to serve the request at all, and no amount of budget-raising in our own system changes
+ * that. Both are terminal, neither is retryable, and they need different people to fix them.
+ *
+ * Lives in its own module for the same reason its sibling does: it is raised from
+ * `post-with-retry.ts`, which both transports import, so homing it in a transport would close an
+ * import cycle the repo's `circular` check rejects.
+ *
+ * ## Scope: Anthropic only, deliberately
+ *
+ * Gemini is **not** classified here yet (GENC-1506, Matt's call 2026-08-18). It is not an oversight
+ * and it is not because Gemini cannot fail this way — it is because Gemini's failure shapes are
+ * genuinely different and only partly observed:
+ *
+ * - Google's paid tiers refuse a spend cap with `429 RESOURCE_EXHAUSTED`, which is **the same status
+ *   and the same message text** as an ordinary rate limit, and `429` is in
+ *   `GeminiTransport.RETRYABLE_STATUSES`. A prose probe there would classify routine rate limiting as
+ *   terminal and break the retry ladder — the exact inverse of the Anthropic situation below.
+ * - The discriminator that *would* work is structural — `details[].QuotaFailure.violations[].quotaId`
+ *   names the limit's scope (`…PerMinute…` is retryable, per-day or spend-scoped is not) — but only
+ *   the per-minute free-tier value has been observed. Guessing the others is what this module's
+ *   history says not to do.
+ * - Google's Prepay balance hitting $0 stops every key on the billing account at once, and its error
+ *   shape is neither documented nor observed.
+ *
+ * So {@link providerRefusalOf} dispatches on vendor and answers `undefined` for anything that is not
+ * Anthropic. Adding Gemini later is a new branch, not a rewrite — which is why the vendor is a
+ * parameter rather than an assumption.
+ *
+ * @packageDocumentation
+ */
+import { VENDOR_LABELS } from './budget-exhausted-error';
+/**
+ * The proxy's machine-readable code for "the upstream vendor refused this account".
+ *
+ * Deliberately distinct from `BUDGET_EXCEEDED`: the ai-service proxy stamps this when it relays a
+ * provider refusal, so the client can tell a relayed upstream fault from the proxy's own budget
+ * verdict without inspecting the body at all.
+ *
+ * Exported from the package index — unlike its `BUDGET_EXCEEDED_CODE` sibling, which is internal —
+ * because the SERVER side of the contract lives in another repo (genesis-create's ai-service stamps
+ * this code onto its proxy responses). A hand-copied string literal there would drift on the first
+ * rename, and the drift would be silent: the client would simply stop classifying.
+ *
+ * @beta
+ */
+export const PROVIDER_REFUSED_CODE = 'PROVIDER_REFUSED';
+/**
+ * The single sentence shown to a user whose provider has refused — the transcript bubble the chat
+ * driver appends, and the string ai-service reuses for its own generation surfaces.
+ *
+ * **It names no cause, and that is the whole design.** Three constraints shaped it, and a rewrite
+ * has to clear all three:
+ *
+ * 1. **It must not sound like a cap.** The user can often see their remaining AI spend in the same
+ *    UI, so *allowance / limit / quota / budget / usage / credit / balance* risk a visible
+ *    self-contradiction: a message saying there is nothing left, next to a figure showing there is.
+ *    "isn't related to your account **or your usage**" goes further than avoiding the words — it
+ *    pre-empts the user checking that figure and concluding the message is wrong.
+ * 2. **It must not imply we cannot pay our bills.** *Billing / payment / funds / top up* all read as
+ *    an unpaid invoice. Naming no cause means there is nothing to be embarrassed by and nothing for
+ *    the user to contradict.
+ * 3. **It must not promise self-healing.** Clearing this needs a human to act out of band, so
+ *    "currently" rather than "temporarily", and "so it can be restored" positively signals that
+ *    someone must do something.
+ *
+ * It is also true of **both** {@link ProviderRefusalKind}s unchanged, which is what makes one
+ * sentence for two kinds honest rather than a fudge: for an expired key the provider *is* refusing,
+ * it *is* unrelated to the user's own account and usage, they *can* do nothing, and support *can*
+ * restore it.
+ *
+ * Vendor-neutral and deployment-neutral on purpose — the same bundle ships to white-labelled
+ * deployments where naming a vendor, or naming Genesis, would be wrong. A host that wants different
+ * wording sets `ChatDriverConfig.providerRefusedMessage`.
+ *
+ * @beta
+ */
+export const 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 — please contact your support team so it can be restored.';
+/**
+ * Thrown when the upstream provider refuses the request because of the state of the **account**
+ * rather than anything about the request — see {@link ProviderRefusalKind}.
+ *
+ * Terminal and non-transient, in the same family as `ResponseTruncatedError` and
+ * `BudgetExhaustedError`: retrying cannot clear it, because nothing about the request is wrong. So
+ * both the transport retry ladder and the driver's transient-retry catch step aside for it and the
+ * failure surfaces immediately as the `'provider-refused'` `TurnFailureReason`.
+ *
+ * @beta
+ */
+export class ProviderRefusedError extends Error {
+    constructor(
+    /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+    vendorLabel, 
+    /** Which kind of refusal — drives the log and the operator's fix, never the user's message. */
+    kind, 
+    /**
+     * The provider's own HTTP status, when known.
+     *
+     * Diagnostic only, and deliberately not part of the classification contract: the observed spend
+     * refusals arrive as `400` (not the `402 billing_error` the docs describe), so a consumer that
+     * branched on this would be encoding one snapshot of provider behaviour.
+     */
+    upstreamStatus, 
+    /** The provider's own `error.type` (e.g. `'invalid_request_error'`, `'authentication_error'`). */
+    upstreamType, 
+    /** The provider's human-readable message, verbatim, for the log. Never shown to the user. */
+    detail) {
+        super(`${vendorLabel} refused the request (${kind})` +
+            (upstreamStatus != null ? ` — HTTP ${upstreamStatus}` : '') +
+            (upstreamType ? ` ${upstreamType}` : '') +
+            (detail ? `: ${detail}` : '') +
+            '. Retrying will not clear this — the provider account must be fixed.');
+        this.vendorLabel = vendorLabel;
+        this.kind = kind;
+        this.upstreamStatus = upstreamStatus;
+        this.upstreamType = upstreamType;
+        this.detail = detail;
+        this.name = 'ProviderRefusedError';
+    }
+}
+/**
+ * Phrases that identify a spend refusal hiding inside Anthropic's **generic**
+ * `invalid_request_error` bucket.
+ *
+ * Prose matching is not a shortcut here, it is the only handle available, and that is a measured
+ * fact rather than an assumption. Both refusals we have captured arrive as `400` +
+ * `invalid_request_error` with **no distinct type, no dedicated header and nothing else structural**:
+ *
+ * | Captured 2026-08-18 | Message |
+ * | --- | --- |
+ * | Credit balance at zero | `Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.` |
+ * | Workspace usage cap | `You have reached your specified workspace API usage limits. You will regain access on 2026-09-01 at 00:00 UTC.` |
+ *
+ * A classifier keyed only on the documented `402 billing_error` signal would have matched **neither**
+ * and shipped a non-fix. That is why this list exists.
+ *
+ * **Independent signals, not whole sentences.** A sentence list would need a new entry every time a
+ * member is reworded, and would silently stop matching in the meantime. `credit balance` and
+ * `usage limit` are each confirmed against a capture above; `spend limit` and the `insufficient …`
+ * form are unobserved and included as cheap tolerance for the same family.
+ *
+ * **False positives are near-impossible**, for a reason that is easy to miss: on a refused account
+ * the spend check runs *before* request validation (verified — a deliberately malformed request on a
+ * dry key still returned the credit message), so a genuine schema `400` is only observable on a
+ * healthy account, where its message quotes field paths and matches nothing here.
+ *
+ * Deletable the day Anthropic gives this family its own `error.type`.
+ */
+const ANTHROPIC_SPEND_PHRASES = Object.freeze([
+    /credit balance/i,
+    /usage limit/i,
+    /spend limit/i,
+    /insufficient (credit|funds|balance)/i,
+]);
+/** Anthropic `error.type` values that are an auth refusal, straight from the documented table. */
+const ANTHROPIC_AUTH_TYPES = Object.freeze([
+    'authentication_error',
+    'permission_error',
+]);
+/**
+ * The inner `{ type, message }` of an Anthropic error envelope, from wherever it is on the wire.
+ *
+ * Two positions, both load-bearing, because the same refusal reaches us in two shapes:
+ * - **direct API and legacy JSON proxy** — the envelope IS the body:
+ *   `{ type: 'error', error: { type, message } }`;
+ * - **NDJSON framed proxy** — the envelope is nested under the err frame's `details`, while the
+ *   frame's own top-level `error` is a *string* (the proxy's summary).
+ *
+ * So reading only the top level would classify nothing on the browser path, and reading only
+ * `details` would classify nothing on the server path. Mirrors how `budgetExhaustedFrom` reads both.
+ */
+function anthropicErrorBody(payload) {
+    var _a;
+    const outer = typeof payload === 'object' && payload !== null ? payload : {};
+    // Framed: `details` holds the upstream envelope. Legacy/direct: the body itself does.
+    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 : undefined,
+                message: typeof message === 'string' ? message : undefined,
+            };
+        }
+    }
+    return undefined;
+}
+/**
+ * A `kind` the caller stated explicitly, from either wire position, or `undefined`.
+ *
+ * Both positions are read for the same reason `anthropicErrorBody` reads two: a JSON body carries its
+ * fields at the top level, while an NDJSON err frame nests everything but `error` under `details`.
+ */
+function statedKind(payload) {
+    const outer = (typeof payload === 'object' && payload !== null ? payload : {});
+    const nested = (typeof outer.details === 'object' && outer.details !== null ? outer.details : {});
+    for (const candidate of [outer.kind, nested.kind]) {
+        if (candidate === 'auth' || candidate === 'spend')
+            return candidate;
+    }
+    return undefined;
+}
+/**
+ * The kind implied by the provider envelope's `type` alone — no prose, no status.
+ *
+ * Vendor-agnostic on purpose, so the explicit-code path can reuse it: by the time the proxy has
+ * stamped `PROVIDER_REFUSED` it has already decided this is a refusal, and all that is left is which
+ * kind — a question the relayed envelope answers without any vendor dispatch.
+ */
+function kindFromEnvelopeType(payload) {
+    const body = anthropicErrorBody(payload);
+    if (!(body === null || body === void 0 ? void 0 : body.type))
+        return undefined;
+    if (ANTHROPIC_AUTH_TYPES.includes(body.type))
+        return 'auth';
+    // The documented billing signal. Unobserved by us — every real spend refusal we captured came
+    // through the generic bucket — but it is in the errors table, so honour it.
+    if (body.type === 'billing_error')
+        return 'spend';
+    return undefined;
+}
+/**
+ * Classify a rejection as a provider refusal, or `undefined` for anything else.
+ *
+ * **Every trigger is a POSITIVE signal — status alone never classifies.** That is what keeps this
+ * from stealing the proxy's own `402 BUDGET_EXCEEDED`: a bare `402` with no provider envelope
+ * carries nothing this function recognises, so it falls through to the budget classification exactly
+ * as it did before this module existed. A `402` that *does* carry an Anthropic envelope is a relayed
+ * upstream fault and is claimed here — which is the collision GENC-1506 set out to close, closed by
+ * ordering and positive detection rather than by loosening the budget predicate.
+ *
+ * @param vendor - which vendor's transport was refused. Anything but `'anthropic'` returns
+ *   `undefined` today; see this module's header for why Gemini is deliberately absent.
+ * @param code - the proxy's machine-readable code, when there is one (`err` frame or JSON body).
+ * @param payload - the parsed rejection body, or the parsed `err` frame.
+ */
+export function providerRefusalOf(vendor, code, payload) {
+    var _a, _b;
+    // The proxy's explicit signal wins over any body inspection, in any status. It is the one route
+    // that needs no vendor knowledge at all — the proxy has already done the classifying.
+    //
+    // The KIND, though, still has to be worked out rather than assumed. Three sources, in descending
+    // authority, because a caller that troubled to state the kind knows more than we can infer:
+    //
+    //   1. a stated `kind`, in EITHER wire position — top level on a JSON body, under `details` on an
+    //      err frame, since the framed protocol carries rejection metadata there (the same split
+    //      `anthropicErrorBody` and `budgetExhaustedFrom` already straddle);
+    //   2. the provider envelope's own type, which the proxy relays in `details` whether or not it
+    //      states a kind — this is what our own ai-service proxy actually sends today;
+    //   3. `spend`, as the last resort.
+    //
+    // Reading only position 1 and defaulting the rest was a real mis-attribution rather than a
+    // hypothetical: our proxy stamps this code with the Anthropic envelope in `details` and no
+    // top-level `kind`, so an `authentication_error` was being reported as `spend` — sending an
+    // operator to top up an account when the actual fix is to rotate a credential. The user-facing
+    // copy is identical either way, which is exactly why nothing on screen would have caught it.
+    if (code === PROVIDER_REFUSED_CODE) {
+        return (_b = (_a = statedKind(payload)) !== null && _a !== void 0 ? _a : kindFromEnvelopeType(payload)) !== null && _b !== void 0 ? _b : 'spend';
+    }
+    if (vendor !== 'anthropic')
+        return undefined;
+    // Structural first: documented types, no prose, and cheaper than the phrase scan. `401`/`403` are
+    // absent from every RETRYABLE_STATUSES, so claiming them changes what the user is told and what the
+    // log records — never the retry behaviour.
+    const structural = kindFromEnvelopeType(payload);
+    if (structural)
+        return structural;
+    // The generic bucket, gated on the phrase list. Deliberately NOT gated on status as well: the
+    // captures were all `400`, and pinning that would encode one snapshot of provider behaviour when
+    // the type plus the phrase is already specific enough.
+    const body = anthropicErrorBody(payload);
+    if ((body === null || body === void 0 ? void 0 : body.type) === 'invalid_request_error' && body.message) {
+        const message = body.message;
+        if (ANTHROPIC_SPEND_PHRASES.some((phrase) => phrase.test(message)))
+            return 'spend';
+    }
+    return undefined;
+}
+/**
+ * Build a {@link ProviderRefusedError} from a classified rejection, pulling the provider's own
+ * status/type/message across for the log.
+ *
+ * `upstreamStatus` is passed in rather than read from the payload because the two wire modes carry it
+ * differently (HTTP status vs the err frame's `status`), and the caller is the only one that knows
+ * which it is looking at.
+ */
+export 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);
+}
+/**
+ * The {@link AIProviderType} a vendor label belongs to, for the classification call above.
+ *
+ * A thin wrapper over the label map rather than a reuse of `vendorTypeOfLabel`: this one is called
+ * with the transport's OWN label, which is always a literal from {@link VENDOR_LABELS}, so an exact
+ * match is correct and the case-insensitive, whitespace-tolerant lookup that the wire-borne label
+ * needs would be misleading precision here.
+ */
+export function vendorOfTransportLabel(vendorLabel) {
+    const entry = Object.entries(VENDOR_LABELS).find(([, label]) => label === vendorLabel);
+    return entry === null || entry === void 0 ? void 0 : entry[0];
+}

package/dist/esm/transports/retry-hints.js

@@ -0,0 +1,168 @@
+/**
+ * Server-supplied retry hints for the shared `postWithRetry` ladder (GENC-1506).
+ *
+ * ## Why this exists
+ *
+ * The ladder was `base * 2^attempt` — 1s, 2s, 4s, 8s, 16s, **31s in total** — and it read neither the
+ * HTTP `Retry-After` header nor Google's in-body `RetryInfo`. Measured against a real rate-limited
+ * Gemini key (2026-08-18), the provider asked for **53s**:
+ *
+ * ```jsonc
+ * {"error":{"code":429,"status":"RESOURCE_EXHAUSTED",
+ *   "message":"… Please retry in 53.59713199s.",
+ *   "details":[{"@type":"type.googleapis.com/google.rpc.RetryInfo","retryDelay":"53s"}]}}
+ * ```
+ *
+ * So a **legitimate** rate limit burned all five retries inside the window the provider had told us to
+ * wait, then failed opaquely — every attempt after the first guaranteed to fail, and the user waiting
+ * 31s to be told nothing useful. Honouring the hint turns five doomed requests into one that works.
+ *
+ * ## Scope note
+ *
+ * This is deliberately vendor-neutral and applies to **healthy traffic**, not just refusals. It is the
+ * one part of GENC-1506 that changes timing on a path that is working: some failures that used to give
+ * up after 31s will now wait longer before succeeding or failing. That is the correct behaviour and it
+ * is what the server asked for, but it is why the ladder keeps its own tests and its own line in the
+ * release notes rather than riding along silently inside a fix about error messages.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Ceiling on a server-requested wait, per attempt.
+ *
+ * A hint is *advice from a remote party*, so it needs a bound: without one, a mistaken or hostile
+ * `Retry-After: 86400` parks a turn for a day with no way out but a caller abort. 60s sits comfortably
+ * above the largest value observed (53s) while keeping the worst case survivable.
+ *
+ * This caps each wait, and it is the ONLY per-attempt bound — the earlier claim that the exponential
+ * ladder bounds a pathological sequence was simply wrong, because `resolveBackoffMs` takes the LARGER
+ * of the two and the ladder tops out at `baseMs * 2 ** 4` (16s at the 1s base every transport uses). A
+ * 60s hint therefore wins on every attempt and the ladder never contributes. That is what
+ * {@link MAX_TOTAL_SERVER_REQUESTED_BACKOFF_MS} is for.
+ */
+export const MAX_SERVER_REQUESTED_BACKOFF_MS = 60000;
+/**
+ * Ceiling on the server-requested wait across a WHOLE retry sequence.
+ *
+ * Without it the per-attempt cap is no real bound: five capped waits is five minutes, and nothing is
+ * watching during them — the attempt's own timeout is cleared before each backoff, so a provider (or a
+ * proxy in front of one) answering `Retry-After: 3600` five times parks the turn for the full five
+ * minutes with a caller abort as the only way out.
+ *
+ * 120s is chosen so the case this module was written for still works untouched: the measured Gemini
+ * hint was 53s, and two of those fit inside the budget with headroom. Past it we stop honouring hints
+ * and fall back to the ladder, so a sequence of maximal 60s hints now totals ~151s (120s of honoured
+ * excess plus the ladder's own 31s) rather than 300s.
+ *
+ * What it budgets is the EXCESS over the wait the ladder would have taken anyway — see
+ * {@link serverBackoffSpentMs}. Budgeting the raw hint instead would let the ladder's own growth eat
+ * the allowance late in a sequence, declining hints on the grounds of time we were always going to
+ * spend.
+ */
+export const MAX_TOTAL_SERVER_REQUESTED_BACKOFF_MS = 120000;
+/** Anthropic's explicit retry verdict, which its own SDK honours. */
+const SHOULD_RETRY_HEADER = 'x-should-retry';
+/** Both hint formats are expressed in seconds; every internal wait is in ms. */
+const MS_PER_SECOND = 1000;
+/**
+ * `true` only when the server has **explicitly** said not to retry.
+ *
+ * Absent means "no opinion" and must never be read as `true` — that asymmetry is measured, not
+ * cautious: the captured Anthropic `401` carries no `x-should-retry` at all, while the captured
+ * spend-refusal `400` carries `false`. Treating absence as a refusal to retry would silently disable
+ * the ladder for every provider that does not send the header, Google included.
+ */
+export 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';
+}
+/**
+ * The `Retry-After` header in ms, or `undefined`.
+ *
+ * Both documented forms are accepted — delta-seconds (`Retry-After: 53`) and an HTTP-date
+ * (`Retry-After: Wed, 21 Oct 2026 07:28:00 GMT`) — because a proxy or CDN in front of the provider may
+ * rewrite one into the other, and a silently unparsed hint is indistinguishable from no hint at all.
+ * A date already in the past clamps to 0 rather than going negative.
+ */
+export 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 undefined;
+    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 undefined;
+    return Math.max(0, at - Date.now());
+}
+/**
+ * Google's `google.rpc.RetryInfo.retryDelay` in ms, or `undefined`.
+ *
+ * Read from **two positions**, for the same reason the refusal classifier reads two: on the direct API
+ * the body is Google's own (`{ error: { details: [...] } }`), while through the NDJSON framed proxy that
+ * body is nested under the err frame's `details`. Reading one position only would honour the hint on
+ * exactly one of the two paths.
+ *
+ * Matched on an `@type` **suffix** rather than the full URL: the type prefix is a Google-owned constant
+ * that has no reason to change, but suffix-matching costs nothing and survives it if it does.
+ */
+export function retryInfoMs(payload) {
+    const outer = typeof payload === 'object' && payload !== null ? payload : {};
+    const framed = typeof outer.details === 'object' && outer.details !== null
+        ? outer.details
+        : undefined;
+    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 === null || entry === void 0 ? void 0 : entry.retryDelay;
+            // Protobuf Duration as JSON: a decimal number of seconds with an `s` suffix ("53s", "1.5s").
+            if (typeof delay !== 'string')
+                continue;
+            const seconds = Number(delay.replace(/s$/, ''));
+            if (Number.isFinite(seconds) && seconds >= 0)
+                return seconds * MS_PER_SECOND;
+        }
+    }
+    return undefined;
+}
+/**
+ * How long to wait before the next attempt: never less than our own ladder, never less than the
+ * server asked, never more than the ceiling.
+ *
+ * `max` rather than "prefer the server's value" is the point — a server asking for *less* than our
+ * backoff must not be able to talk us into hammering it, which a naive "honour the hint" would do on
+ * `Retry-After: 0`.
+ *
+ * @param attempt - zero-based attempt index, as the ladder counts them.
+ * @param baseMs - the transport's backoff base; the ladder is `baseMs * 2^attempt`.
+ * @param serverMs - the server's requested delay, when it supplied one.
+ */
+export function resolveBackoffMs(attempt, baseMs, serverMs, serverAllowanceMs = Number.POSITIVE_INFINITY) {
+    const ladder = baseMs * Math.pow(2, attempt);
+    if (serverMs == null || !Number.isFinite(serverMs))
+        return ladder;
+    // Three ceilings, all of which have to hold: what the server asked, the per-attempt cap, and
+    // whatever is left of the sequence budget. An exhausted allowance clamps to 0, so the `max` below
+    // returns the bare ladder and the sequence degrades to its pre-GENC-1506 behaviour rather than
+    // stopping — a hint we decline to honour is not a reason to stop retrying.
+    const honoured = Math.min(serverMs, MAX_SERVER_REQUESTED_BACKOFF_MS, Math.max(0, serverAllowanceMs));
+    return Math.max(ladder, honoured);
+}
+/**
+ * How much of the sequence budget a resolved wait consumed.
+ *
+ * Only the part attributable to the server counts: a wait the ladder would have taken anyway is not
+ * the server's doing, so it must not eat the allowance — otherwise a long ladder late in a sequence
+ * would exhaust the budget without a single hint having been honoured.
+ */
+export function serverBackoffSpentMs(resolvedMs, ladderMs) {
+    return Math.max(0, resolvedMs - ladderMs);
+}

package/dist/esm/transports/server-openai-transport.js

@@ -1,5 +1,6 @@
 import { __awaiter } from "tslib";
 import { budgetExhaustedFrom, codeOf, isBudgetRejection, parseJsonOrUndefined, VENDOR_LABELS, } from './budget-exhausted-error';
+import { providerRefusalOf, providerRefusedFrom } from './provider-refused';
 const AI_SERVER_PATH = '/gwf/ai-service/chat-completions';
 const DEFAULT_MODEL = 'gpt-4o-mini';
 const DEFAULT_TIMEOUT = 30000;
@@ -72,6 +73,15 @@ export class ServerOpenAITransport {
                 // the assistant's `blocked` state, before or after this change. The typed
                 // throw improves the log line and any host that catches it directly. See
                 // `docs/migration-GENC-1464.md` §"Transport coverage".
+                // The provider wall (GENC-1506), classified before the budget wall for the same
+                // ordering reason `postWithRetry` has: a relayed upstream `402` must not be
+                // reported as the caller's own spend cap. Same honest caveat as the budget
+                // classification below — this transport's only caller catches everything and
+                // returns null, so the typed throw improves the log line and nothing else.
+                const refusal = providerRefusalOf('openai', codeOf(parsed), parsed);
+                if (refusal) {
+                    throw providerRefusedFrom(VENDOR_LABELS.openai, refusal, response.status, parsed, err || undefined);
+                }
                 if (isBudgetRejection(response.status, codeOf(parsed))) {
                     throw budgetExhaustedFrom(VENDOR_LABELS.openai, parsed, err || undefined);
                 }