@genesislcap/foundation-ai 15.3.2 → 15.3.3-alpha-4899ddd.0

package/dist/foundation-ai.d.ts

@@ -378,6 +378,102 @@ declare interface AnthropicTransportConfig {
     maxTokens?: number;
 }
 
+/**
+ * The vendors whose spend the ai-service proxy meters — i.e. the only vendors
+ * that can raise a {@link BudgetExhaustedError}, and therefore the only ones a
+ * 402's `otherVendorAvailable: false` is a statement about.
+ *
+ * Deliberately narrower than the keys of {@link VENDOR_LABELS}, and it must stay
+ * exactly the proxy's own list — `VENDORS` in ai-service's `utils/aiVendor.js`.
+ * A vendor listed here that the proxy does not meter gets walled by the
+ * `otherVendorAvailable: false` sweep on a verdict that says nothing about it,
+ * and if it is reachable, `blocked` then derives true and locks a composer with
+ * headroom left.
+ *
+ * Two vendors are excluded for that reason:
+ * - `chrome` runs on-device — no pot to exhaust, and free.
+ * - `openai` is **not budgeted by the proxy**. ai-service rejects it up front
+ *   with `400 UNSUPPORTED_PROVIDER` (`SUPPORTED_PROVIDERS` in `aiVendor.js`), no
+ *   `MODEL_PRICING` row names it, and `otherVendorAvailable` is computed over
+ *   Anthropic and Gemini alone. So it can never raise a 402, and a 402 is never
+ *   a statement about it.
+ *
+ * @beta
+ */
+export declare const BUDGETED_VENDORS: readonly AIProviderType[];
+
+/**
+ * Thrown when the AI-spend budget for the caller (user, tenant, or project) is
+ * exhausted and the ai-service proxy refuses the request outright — HTTP `402`
+ * with `code: 'BUDGET_EXCEEDED'`, in either the legacy JSON or the NDJSON framed
+ * mode.
+ *
+ * This is a **terminal, non-transient** condition, in the same family as
+ * `ResponseTruncatedError`: no amount of retrying clears it, because nothing
+ * about the request is wrong. The budget has to be raised out-of-band before any
+ * further call can succeed, so both the transport retry ladder and the driver's
+ * transient-retry catch step aside for it and the failure surfaces immediately
+ * as the `'budget-exhausted'` `TurnFailureReason`.
+ *
+ * `budgetUsd`/`spentUsd` are populated from the rejection body when the proxy
+ * supplies them (the workstream-C contract does); they are optional because a
+ * plain-text or truncated 402 from an older proxy still has to classify.
+ *
+ * @beta
+ */
+export declare class BudgetExhaustedError extends Error {
+    /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+    readonly vendorLabel: string;
+    /** The configured spend cap in USD, when the proxy reported one. */
+    readonly budgetUsd?: number;
+    /** Spend already booked against that cap in USD, when the proxy reported it. */
+    readonly spentUsd?: number;
+    /** The proxy's human-readable rejection message, when present. */
+    readonly detail?: string;
+    /**
+     * The proxy's own verdict on whether **any other** vendor it meters still has
+     * headroom, from the 402's `otherVendorAvailable`.
+     *
+     * The one field on this error a client cannot re-derive. A client can only
+     * infer "another vendor is free" from registry membership — which knows
+     * nothing about that vendor's remaining spend — so a `false` here is the only
+     * thing standing between the user and "Switch to Gemini to keep going" for a
+     * Gemini pot that is already empty. `undefined` means the proxy did not say
+     * (an older build), and the client is back to inferring.
+     */
+    readonly otherVendorAvailable?: boolean;
+    /**
+     * The vendor the **proxy** says it refused, verbatim from the 402's `vendor`.
+     *
+     * A second opinion, not the first: {@link BudgetExhaustedError.vendorLabel}
+     * comes from the transport that was actually called and wins wherever it
+     * resolves. This one rescues attribution when the transport's label does not —
+     * a white-labelled or multiplexing gateway whose single transport fronts more
+     * than one upstream stamps one static label for all of them, and only the
+     * proxy knows which pot the request was actually booked against.
+     */
+    readonly serverVendor?: string;
+    constructor(
+    /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+    vendorLabel: string, 
+    /** The configured spend cap in USD, when the proxy reported one. */
+    budgetUsd?: number, 
+    /** Spend already booked against that cap in USD, when the proxy reported it. */
+    spentUsd?: number, 
+    /** The proxy's human-readable rejection message, when present. */
+    detail?: string, 
+    /**
+     * The fields the proxy reports about the wider budget picture. An object
+     * rather than two more positional arguments: the four above are already the
+     * limit of what reads at a call site, and these two are set together or not
+     * at all.
+     */
+    extra?: {
+        otherVendorAvailable?: boolean;
+        serverVendor?: string;
+    });
+}
+
 /**
  * Prompt-cache policy for a chat request, resolved per turn. **Provider-neutral intent,
  * provider-specific effect** — read this carefully, the two providers differ sharply:
@@ -573,6 +669,65 @@ export declare type ChatDriverResult = {
      * successful turn, a user cancel, and a driver dispose (none are failures).
      */
     failureReason?: TurnFailureReason;
+    /**
+     * Budget figures reported by the proxy, present **only** when
+     * `failureReason === 'budget-exhausted'` and the rejection carried them.
+     * Lifted off `BudgetExhaustedError` so a host can render the real numbers
+     * ("$25.40 of $25") without catching the transport error itself — before
+     * this the figures reached the debug log but not the caller, so the
+     * assistant's blocked banner could only ever show generic copy.
+     *
+     * Present whenever the wall carried anything worth reporting — figures, or
+     * an attributable vendor. Omitted entirely (not set to `undefined`) when
+     * it carried neither, and absent from every non-budget result — a clean
+     * turn's shape stays byte-identical to the historical `{ reason: 'done' }`.
+     */
+    budget?: {
+        /** The configured spend cap in USD, when the proxy reported one. */
+        budgetUsd?: number;
+        /** Spend already booked against that cap in USD, when reported. */
+        spentUsd?: number;
+        /**
+         * Vendor label of the transport that was refused (e.g. `'Anthropic'`).
+         * Always present when `budget` is: it is the one field that keeps a
+         * per-vendor budget model open without a breaking change later.
+         */
+        vendorLabel: string;
+        /**
+         * The refusing vendor as a typed {@link AIProviderType}: the normalised
+         * key of `vendorLabel` where that label is one a vendor claims, otherwise
+         * the normalised key of the proxy's own `vendor` field on the 402.
+         *
+         * So it is **not** always a normalisation of `vendorLabel`, and the two
+         * fields can legitimately disagree — a white-labelled or multiplexing
+         * gateway stamps one static transport label in front of several upstreams,
+         * and only the proxy can say which of them refused. The fallback is
+         * deliberate: it is what keeps attribution working for those deployments
+         * instead of degrading them all to "unattributable".
+         *
+         * Optional because a label no vendor claims and a 402 that names no vendor
+         * must degrade to "unattributable" rather than to a wrong attribution.
+         * Derived from the label first, rather than from the driver's
+         * last-resolved provider, **on purpose**: the label originates at the
+         * transport that was actually refused, whereas the last-resolved provider
+         * is stale on the classification seam (an orchestrated turn classifies
+         * against the registry default, which the chat driver may never have
+         * resolved).
+         */
+        vendor?: AIProviderType;
+        /**
+         * The proxy's verdict on whether any OTHER vendor it meters still has
+         * headroom (the 402's `otherVendorAvailable`).
+         *
+         * The only field here a client cannot re-derive, and the reason it is
+         * carried: a client can infer "another vendor exists" from registry
+         * membership, but never "another vendor has budget left". A `false` is
+         * therefore server-known truth that must beat that inference —
+         * `FoundationAiAssistant` uses it to stop advising a switch to a vendor
+         * whose pot is already empty. `undefined` means the proxy did not say.
+         */
+        otherVendorAvailable?: boolean;
+    };
 } | {
     reason: 'agent-handoff';
     summary: string;
@@ -1466,6 +1621,21 @@ export declare interface CriteriaInterpretContext {
     fields?: FieldLike[];
 }
 
+/**
+ * The single copy shown to a user whose AI budget is gone — the transcript bubble
+ * the chat driver appends, and the default text of the assistant's blocked banner.
+ *
+ * Deliberately **vendor-neutral**: the same bundle ships to white-labelled
+ * deployments where "contact Genesis" is simply wrong. A host that wants
+ * branded wording overrides both surfaces — the banner via
+ * `FoundationAiAssistant.setBlocked(true, reason)`, the transcript bubble via
+ * `ChatDriverConfig.budgetExhaustedMessage` — so neither is stuck with this
+ * default while the other is customised.
+ *
+ * @beta
+ */
+export declare const DEFAULT_BUDGET_EXHAUSTED_MESSAGE = "You've reached your AI usage limit. Contact your administrator to raise it.";
+
 /**
  * A field descriptor accepted by criteria interpretation utilities.
  * Can be a plain string name or an object with common field metadata properties.
@@ -1753,6 +1923,14 @@ export declare type InteractionResult<T = unknown> = {
 /** Returns true when AI features (beta) are enabled via ?feature.ai URL param or GENX_ENABLE_AI=true env var. */
 export declare const isAIFeatureEnabled: () => boolean;
 
+/**
+ * Whether this vendor's spend is metered by the proxy — see
+ * {@link BUDGETED_VENDORS}.
+ *
+ * @beta
+ */
+export declare const isBudgetedVendor: (vendor: AIProviderType | undefined) => boolean;
+
 /**
  * Type guard that narrows a `ChatToolCall` to `ChatToolCallUnknown`.
  *
@@ -2112,10 +2290,20 @@ declare interface StructuredPromptOptions {
  *   an incomplete tool call; deterministic, so it is not retried.
  * - `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 (HTTP 402). **Terminal for the parent too, and enforced**: the parent
+ *   driver ends its own turn as soon as this outcome comes back, instead of
+ *   appending it as a tool result and calling the model again into the same wall.
+ *   So a handler that receives it will not be called a second time this turn, and
+ *   the parent turn reports `'budget-exhausted'` in its own right.
+ *
+ * Recovery guidance differs sharply by reason — see `docs/sub_agent.md`. Only
+ * `budget_exhausted` and `refusal` are terminal; retrying either just reproduces
+ * it. The rest are worth a retry or a question to the user.
  *
  * @beta
  */
-export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal';
+export declare type SubAgentFailureReason = 'max_iterations' | 'malformed_tool_call' | 'empty_response' | 'unknown_tool_limit' | 'timeout' | 'response_truncated' | 'refusal' | 'budget_exhausted';
 
 /**
  * Options passed to `requestSubAgent` at call time.
@@ -2173,9 +2361,60 @@ export declare const SUPPORTED_GEMINI_MODEL_IDS: readonly GeminiModelId[];
  *                               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.
+ *
+ * @beta
+ */
+export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal' | 'budget-exhausted';
+
+/**
+ * Display name for each concrete AI vendor: the **single source** every
+ * transport's `vendorLabel` is read from, and the only place a vendor's name is
+ * spelled for a user.
+ *
+ * This map is the hinge of the per-vendor budget model (GENC-1464). A wall is
+ * attributed to a vendor by reverse-looking-up the label the refused transport
+ * stamped on its {@link BudgetExhaustedError} — so a label that drifts from this
+ * map (a literal typo, a casing change, a new vendor added with a hardcoded
+ * string) silently degrades every wall from that transport to "unattributable"
+ * and re-locks the whole session instead of just that vendor. It fails safe, but
+ * the feature quietly stops working, which is why the transports read their label
+ * from here rather than restating it.
+ *
+ * The map has **two kinds of entry**, and the difference matters:
+ *
+ * - The {@link BUDGETED_VENDORS} — `anthropic` and `gemini` — reach the model
+ *   through the ai-service proxy, are metered by it, and stamp their label on a
+ *   {@link BudgetExhaustedError}. For these the label is both an attribution key
+ *   and display copy.
+ * - `chrome` and `openai` are **display-only**. `ChromeProvider` talks to the
+ *   on-device Prompt API and the proxy refuses `openai` outright, so neither can
+ *   be refused for budget or stamp a label — but both report a `provider` from
+ *   `getStatus()`, which puts them in the assistant's reachable set, which is
+ *   what the blocked banner names when it tells a walled user where they can
+ *   still go ("Switch to Chrome to keep going."). Dropping either entry would
+ *   print the raw type there.
+ *
+ * `'none'` is excluded deliberately: it is the "no provider configured" sentinel,
+ * not a vendor, and nothing can be refused by it — nor switched to.
+ *
+ * @beta
+ */
+export declare const VENDOR_LABELS: Readonly<Record<Exclude<AIProviderType, 'none'>, string>>;
+
+/**
+ * The {@link AIProviderType} behind a vendor label, or `undefined` for a label
+ * no vendor claims.
+ *
+ * Case-insensitive and whitespace-tolerant, because the label travels as free
+ * text on the wire (the driver contract carries `vendorLabel`, not the type) and
+ * an unrecognised label must degrade to "unattributable" rather than to a wrong
+ * attribution — blocking the wrong vendor is worse than blocking none.
  *
  * @beta
  */
-export declare type TurnFailureReason = 'exception' | 'malformed-function-call' | 'empty-response' | 'unknown-tool-limit' | 'max-iterations' | 'response-truncated' | 'refusal';
+export declare function vendorTypeOfLabel(label?: string): AIProviderType | undefined;
 
 export { }

package/package.json

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