@genesislcap/foundation-ai 15.14.0 → 15.14.2

package/dist/foundation-ai.api.json

@@ -4021,7 +4021,7 @@
             },
             {
               "kind": "Content",
-              "text": ";\n        otherVendorAvailable?: boolean;\n    };\n} | {\n    reason: 'agent-handoff';\n    summary: string;\n    remainingTask: string;\n}"
+              "text": ";\n        otherVendorAvailable?: boolean;\n    };\n    providerRefused?: {\n        vendorLabel: string;\n        kind: 'spend' | 'auth';\n        upstreamStatus?: number;\n        upstreamType?: string;\n    };\n} | {\n    reason: 'agent-handoff';\n    summary: string;\n    remainingTask: string;\n}"
             },
             {
               "kind": "Content",
@@ -7493,6 +7493,29 @@
             "endIndex": 0
           }
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-ai!DEFAULT_PROVIDER_REFUSED_MESSAGE:var",
+          "docComment": "/**\n * 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.\n *\n * **It names no cause, and that is the whole design.** Three constraints shaped it, and a rewrite has to clear all three:\n *\n * 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.\n *\n * 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.\n *\n * 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`.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "DEFAULT_PROVIDER_REFUSED_MESSAGE: "
+            },
+            {
+              "kind": "Content",
+              "text": "string"
+            }
+          ],
+          "fileUrlPath": "src/transports/provider-refused.ts",
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "DEFAULT_PROVIDER_REFUSED_MESSAGE",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!FieldLike:type",
@@ -10217,6 +10240,339 @@
             }
           ]
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/foundation-ai!PROVIDER_REFUSED_CODE:var",
+          "docComment": "/**\n * The proxy's machine-readable code for \"the upstream vendor refused this account\".\n *\n * 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.\n *\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "PROVIDER_REFUSED_CODE = "
+            },
+            {
+              "kind": "Content",
+              "text": "\"PROVIDER_REFUSED\""
+            }
+          ],
+          "fileUrlPath": "src/transports/provider-refused.ts",
+          "initializerTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "PROVIDER_REFUSED_CODE",
+          "variableTypeTokenRange": {
+            "startIndex": 0,
+            "endIndex": 0
+          }
+        },
+        {
+          "kind": "TypeAlias",
+          "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusalKind:type",
+          "docComment": "/**\n * Which kind of refusal it was. **One error type, two kinds** — because the user-facing outcome is identical (one sentence, see {@link DEFAULT_PROVIDER_REFUSED_MESSAGE}) while the operator's fix is completely different.\n *\n * - `spend` — the account cannot spend: credit balance at zero, a workspace/organisation usage cap reached, or a billing/payment-information problem. Someone has to pay or raise a cap. - `auth` — the credential cannot be used: revoked, expired or malformed key (`401`), or a key without access to the requested model (`403`). Someone has to rotate a key or grant access.\n *\n * The alternative designs were both worse. A single type named for spend would *lie* about an expired key, and a debug timeline reading `provider-spend-refused` for an auth fault misleads the next engineer — which is precisely the trap the first draft of this feature fell into by naming itself `ProviderCreditExhaustedError` before a usage cap turned out to be in the same family. Two separate error types would duplicate a branch, a message and a wire code to express one outcome.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export type ProviderRefusalKind = "
+            },
+            {
+              "kind": "Content",
+              "text": "'spend' | 'auth'"
+            },
+            {
+              "kind": "Content",
+              "text": ";"
+            }
+          ],
+          "fileUrlPath": "src/transports/provider-refused.ts",
+          "releaseTag": "Beta",
+          "name": "ProviderRefusalKind",
+          "typeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
+        {
+          "kind": "Class",
+          "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError:class",
+          "docComment": "/**\n * Thrown when the upstream provider refuses the request because of the state of the **account** rather than anything about the request — see {@link ProviderRefusalKind}.\n *\n * 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`.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export declare class ProviderRefusedError extends "
+            },
+            {
+              "kind": "Reference",
+              "text": "Error",
+              "canonicalReference": "!Error:interface"
+            },
+            {
+              "kind": "Content",
+              "text": " "
+            }
+          ],
+          "fileUrlPath": "src/transports/provider-refused.ts",
+          "releaseTag": "Beta",
+          "isAbstract": false,
+          "name": "ProviderRefusedError",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "Constructor",
+              "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError:constructor(1)",
+              "docComment": "/**\n * Constructs a new instance of the `ProviderRefusedError` class\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "constructor(\n    vendorLabel: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    kind: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ProviderRefusalKind",
+                  "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusalKind:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    upstreamStatus?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    upstreamType?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", \n    detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "vendorLabel",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "kind",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "upstreamStatus",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 5,
+                    "endIndex": 6
+                  },
+                  "isOptional": true
+                },
+                {
+                  "parameterName": "upstreamType",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 7,
+                    "endIndex": 8
+                  },
+                  "isOptional": true
+                },
+                {
+                  "parameterName": "detail",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 9,
+                    "endIndex": 10
+                  },
+                  "isOptional": true
+                }
+              ]
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError#detail:member",
+              "docComment": "/**\n * The provider's human-readable message, verbatim, for the log. Never shown to the user.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly detail?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "detail",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError#kind:member",
+              "docComment": "/**\n * Which kind of refusal — drives the log and the operator's fix, never the user's message.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly kind: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "ProviderRefusalKind",
+                  "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusalKind:type"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "kind",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError#upstreamStatus:member",
+              "docComment": "/**\n * The provider's own HTTP status, when known.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly upstreamStatus?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "upstreamStatus",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError#upstreamType:member",
+              "docComment": "/**\n * The provider's own `error.type` (e.g. `'invalid_request_error'`, `'authentication_error'`).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly upstreamType?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "upstreamType",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/foundation-ai!ProviderRefusedError#vendorLabel:member",
+              "docComment": "/**\n * Vendor label of the transport that was refused (e.g. `'Anthropic'`).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly vendorLabel: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "vendorLabel",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            }
+          ],
+          "extendsTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          },
+          "implementsTokenRanges": []
+        },
         {
           "kind": "Function",
           "canonicalReference": "@genesislcap/foundation-ai!registerAIProviderRegistry:function(1)",
@@ -10944,7 +11300,7 @@
             },
             {
               "kind": "Content",
-              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'"
+              "text": "'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'\n/**\n * The upstream vendor refused the account (GENC-1506). **Terminal for the PARENT turn too**, on the\n * same reasoning as `budget_exhausted`: the parent cannot recover by calling the model again,\n * because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N\n * doomed children AND a doomed parent call.\n */\n | 'provider_refused'"
             },
             {
               "kind": "Content",
@@ -11483,7 +11839,7 @@
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/foundation-ai!TurnFailureReason:type",
-          "docComment": "/**\n * Why a driver turn ended in failure — the typed taxonomy the tool loop already records onto its debug-log timeline (`turn.error` / `turn.retry` details), surfaced here so callers of a turn can read the outcome structurally instead of scraping prose. Distinct from {@link SubAgentFailureReason} (underscored, its own `timeout` member) because the two enums serialise into different log surfaces and READMEs; a transport request timeout on the main turn is recorded as `exception`.\n *\n * - `exception` — an uncaught error escaped the tool loop (catch-all, includes a transport request timeout). - `malformed-function-call` — the provider returned an unparseable tool call. - `empty-response` — the model returned no content and no tool calls. - `unknown-tool-limit` — the model repeatedly called tools it couldn't dispatch, whether hallucinated or stale (real earlier, retired now). - `max-iterations` — the tool loop hit its iteration cap. - `response-truncated` — a turn stopped at the provider's output-token cap with an incomplete tool call; deterministic, so it bails without retry. - `refusal` — a safety-classifier decline (e.g. Fable 5 `stop_reason: 'refusal'`), which returns empty content; deterministic, so it is not retried. - `budget-exhausted` — the AI-spend budget is used up and the proxy refused the request (`BudgetExhaustedError`, HTTP 402). Terminal, not retried: the budget must be raised out-of-band before any call can succeed.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Why a driver turn ended in failure — the typed taxonomy the tool loop already records onto its debug-log timeline (`turn.error` / `turn.retry` details), surfaced here so callers of a turn can read the outcome structurally instead of scraping prose. Distinct from {@link SubAgentFailureReason} (underscored, its own `timeout` member) because the two enums serialise into different log surfaces and READMEs; a transport request timeout on the main turn is recorded as `exception`.\n *\n * - `exception` — an uncaught error escaped the tool loop (catch-all, includes a transport request timeout). - `malformed-function-call` — the provider returned an unparseable tool call. - `empty-response` — the model returned no content and no tool calls. - `unknown-tool-limit` — the model repeatedly called tools it couldn't dispatch, whether hallucinated or stale (real earlier, retired now). - `max-iterations` — the tool loop hit its iteration cap. - `response-truncated` — a turn stopped at the provider's output-token cap with an incomplete tool call; deterministic, so it bails without retry. - `refusal` — a safety-classifier decline (e.g. Fable 5 `stop_reason: 'refusal'`), which returns empty content; deterministic, so it is not retried. - `budget-exhausted` — the AI-spend budget is used up and the proxy refused the request (`BudgetExhaustedError`, HTTP 402). Terminal, not retried: the budget must be raised out-of-band before any call can succeed. - `provider-refused` — the upstream VENDOR refused this account, not this request (`ProviderRefusedError`): its credit is gone, a usage cap is reached, or the credential is dead. Terminal and not retried. Distinct from `budget-exhausted` because the fix belongs to a different person — ours is \"raise the cap\", this is \"fix the provider account\".\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -11491,7 +11847,7 @@
             },
             {
               "kind": "Content",
-              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted'"
+              "text": "'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused'"
             },
             {
               "kind": "Content",

package/dist/foundation-ai.d.ts

@@ -949,6 +949,30 @@ export declare type ChatDriverResult = {
          */
         otherVendorAvailable?: boolean;
     };
+    /**
+     * What the provider's refusal reported, present **only** when
+     * `failureReason === 'provider-refused'` (GENC-1506).
+     *
+     * Carried for the caller's LOG, not for its UI. The user-facing sentence is deliberately
+     * cause-free (see `DEFAULT_PROVIDER_REFUSED_MESSAGE`), which makes this the only place a
+     * consumer can tell "the account cannot spend" from "the credential is dead" — and those need
+     * different people to fix them. genesis-create's ai-service is the consumer this exists for:
+     * its generation surfaces re-throw across a WebSocket, so without this the kind would be lost
+     * at the driver boundary and the server's own Sentry alert could not say which fault it was.
+     *
+     * Omitted entirely (not set to `undefined`) on every other outcome, so a clean turn's shape
+     * stays byte-identical to the historical `{ reason: 'done' }`.
+     */
+    providerRefused?: {
+        /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+        vendorLabel: string;
+        /** `'spend'` (account cannot pay) or `'auth'` (credential cannot be used). */
+        kind: 'spend' | 'auth';
+        /** The provider's own HTTP status, when known. Diagnostic only — never branch on it. */
+        upstreamStatus?: number;
+        /** The provider's own `error.type`, when it sent one. */
+        upstreamType?: string;
+    };
 } | {
     reason: 'agent-handoff';
     summary: string;
@@ -2015,6 +2039,38 @@ export declare interface CriteriaInterpretContext {
  */
 export declare const DEFAULT_BUDGET_EXHAUSTED_MESSAGE = "You've reached your AI usage limit. Contact your administrator to raise it.";
 
+/**
+ * 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 declare const DEFAULT_PROVIDER_REFUSED_MESSAGE: string;
+
 /**
  * A field descriptor accepted by criteria interpretation utilities.
  * Can be a plain string name or an object with common field metadata properties.
@@ -2586,6 +2642,89 @@ export declare interface ObservableAIProviderRegistry extends AIProviderRegistry
     subscribe(listener: () => void): () => void;
 }
 
+/**
+ * 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 declare const PROVIDER_REFUSED_CODE = "PROVIDER_REFUSED";
+
+/**
+ * Which kind of refusal it was. **One error type, two kinds** — because the user-facing outcome is
+ * identical (one sentence, see {@link DEFAULT_PROVIDER_REFUSED_MESSAGE}) while the operator's fix is
+ * completely different.
+ *
+ * - `spend` — the account cannot spend: credit balance at zero, a workspace/organisation usage cap
+ *   reached, or a billing/payment-information problem. Someone has to pay or raise a cap.
+ * - `auth` — the credential cannot be used: revoked, expired or malformed key (`401`), or a key
+ *   without access to the requested model (`403`). Someone has to rotate a key or grant access.
+ *
+ * The alternative designs were both worse. A single type named for spend would *lie* about an
+ * expired key, and a debug timeline reading `provider-spend-refused` for an auth fault misleads the
+ * next engineer — which is precisely the trap the first draft of this feature fell into by naming
+ * itself `ProviderCreditExhaustedError` before a usage cap turned out to be in the same family. Two
+ * separate error types would duplicate a branch, a message and a wire code to express one outcome.
+ *
+ * @beta
+ */
+export declare type ProviderRefusalKind = 'spend' | 'auth';
+
+/**
+ * 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 declare class ProviderRefusedError extends Error {
+    /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+    readonly vendorLabel: string;
+    /** Which kind of refusal — drives the log and the operator's fix, never the user's message. */
+    readonly kind: ProviderRefusalKind;
+    /**
+     * 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.
+     */
+    readonly upstreamStatus?: number;
+    /** The provider's own `error.type` (e.g. `'invalid_request_error'`, `'authentication_error'`). */
+    readonly upstreamType?: string;
+    /** The provider's human-readable message, verbatim, for the log. Never shown to the user. */
+    readonly detail?: string;
+    constructor(
+    /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+    vendorLabel: string, 
+    /** Which kind of refusal — drives the log and the operator's fix, never the user's message. */
+    kind: ProviderRefusalKind, 
+    /**
+     * 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?: number, 
+    /** The provider's own `error.type` (e.g. `'invalid_request_error'`, `'authentication_error'`). */
+    upstreamType?: string, 
+    /** The provider's human-readable message, verbatim, for the log. Never shown to the user. */
+    detail?: string);
+}
+
 /**
  * Registers a host-supplied {@link (AIProviderRegistry:interface)} instance on
  * the DI container under the {@link (AIProviderRegistry:variable)} token.
@@ -2801,7 +2940,14 @@ declare interface StructuredPromptOptions {
  *
  * @beta
  */
-export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted';
+export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted'
+/**
+* The upstream vendor refused the account (GENC-1506). **Terminal for the PARENT turn too**, on the
+* same reasoning as `budget_exhausted`: the parent cannot recover by calling the model again,
+* because the very next call hits the same wall. N batched sub-agent calls would otherwise cost N
+* doomed children AND a doomed parent call.
+*/
+| 'provider_refused';
 
 /**
  * Options passed to `requestSubAgent` at call time.
@@ -2925,10 +3071,15 @@ export declare interface TokenRates {
  * - `budget-exhausted`       — the AI-spend budget is used up and the proxy refused the request
  *                               (`BudgetExhaustedError`, HTTP 402). Terminal, not retried: the
  *                               budget must be raised out-of-band before any call can succeed.
+ * - `provider-refused`        — the upstream VENDOR refused this account, not this request
+ *                               (`ProviderRefusedError`): its credit is gone, a usage cap is reached,
+ *                               or the credential is dead. Terminal and not retried. Distinct from
+ *                               `budget-exhausted` because the fix belongs to a different person —
+ *                               ours is "raise the cap", this is "fix the provider account".
  *
  * @beta
  */
-export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted';
+export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted' | 'provider-refused';
 
 /**
  * Display name for each concrete AI vendor: the **single source** every

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-ai",
   "description": "Genesis Foundation AI - Provider-agnostic AI configuration and shared utilities",
-  "version": "15.14.0",
+  "version": "15.14.2",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -52,17 +52,17 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "15.14.0",
-    "@genesislcap/genx": "15.14.0",
-    "@genesislcap/rollup-builder": "15.14.0",
-    "@genesislcap/ts-builder": "15.14.0",
-    "@genesislcap/uvu-playwright-builder": "15.14.0",
-    "@genesislcap/vite-builder": "15.14.0",
-    "@genesislcap/webpack-builder": "15.14.0"
+    "@genesislcap/foundation-testing": "15.14.2",
+    "@genesislcap/genx": "15.14.2",
+    "@genesislcap/rollup-builder": "15.14.2",
+    "@genesislcap/ts-builder": "15.14.2",
+    "@genesislcap/uvu-playwright-builder": "15.14.2",
+    "@genesislcap/vite-builder": "15.14.2",
+    "@genesislcap/webpack-builder": "15.14.2"
   },
   "dependencies": {
-    "@genesislcap/foundation-logger": "15.14.0",
-    "@genesislcap/foundation-utils": "15.14.0",
+    "@genesislcap/foundation-logger": "15.14.2",
+    "@genesislcap/foundation-utils": "15.14.2",
     "@microsoft/fast-foundation": "2.50.0"
   },
   "repository": {
@@ -73,5 +73,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d84656a0872b2274be6f6b20a87a28504b48ed2a"
+  "gitHead": "bd1cb4a789548d9c7c6777f8adb7bce3f43c3317"
 }