@genesislcap/foundation-ai 15.6.2 → 15.7.1

package/dist/esm/transports/budget-exhausted-error.js

@@ -0,0 +1,277 @@
+/**
+ * The AI-spend budget wall (GENC-1464 workstream C/D).
+ *
+ * Lives in its own module rather than beside `ResponseTruncatedError` in
+ * `anthropic-transport.ts` because it is raised from `post-with-retry.ts`, which
+ * both transports import — homing it in a transport would close an import cycle
+ * (transport → post-with-retry → transport) that the repo's `circular` check
+ * rejects.
+ */
+/** The proxy's machine-readable rejection code for an exhausted AI budget. */
+export const BUDGET_EXCEEDED_CODE = 'BUDGET_EXCEEDED';
+/**
+ * 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 const VENDOR_LABELS = Object.freeze({
+    anthropic: 'Anthropic',
+    gemini: 'Gemini',
+    openai: 'OpenAI',
+    chrome: 'Chrome',
+});
+/**
+ * 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 const BUDGETED_VENDORS = Object.freeze([
+    'anthropic',
+    'gemini',
+]);
+/**
+ * Whether this vendor's spend is metered by the proxy — see
+ * {@link BUDGETED_VENDORS}.
+ *
+ * A HOST-FACING helper with, deliberately, no internal caller: the library's
+ * own consumers iterate {@link BUDGETED_VENDORS} directly (structural, cannot
+ * drift), while a host writing its own budget pre-flight or status surface
+ * needs the membership test in predicate form. Kept exported for that use —
+ * genesis-create's pre-flight is the shape of consumer it exists for.
+ *
+ * @beta
+ */
+export const isBudgetedVendor = (vendor) => vendor != null && BUDGETED_VENDORS.includes(vendor);
+/** Reverse index of {@link VENDOR_LABELS}, lower-cased, built once. */
+const VENDOR_TYPE_BY_LABEL = new Map(Object.entries(VENDOR_LABELS).map(([type, label]) => [
+    label.toLowerCase(),
+    type,
+]));
+/**
+ * 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 function vendorTypeOfLabel(label) {
+    if (typeof label !== 'string')
+        return undefined;
+    return VENDOR_TYPE_BY_LABEL.get(label.trim().toLowerCase());
+}
+/**
+ * HTTP status the ai-service proxy rejects an over-budget request with, in both
+ * the legacy JSON mode (the response status) and the NDJSON framed mode (the
+ * `status` on the terminal `err` frame).
+ *
+ * Deliberately **absent** from every transport's `RETRYABLE_STATUSES`: the budget
+ * does not refill on a backoff ladder, so retrying only delays the inevitable
+ * five times over.
+ */
+export const BUDGET_EXCEEDED_STATUS = 402;
+/**
+ * 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 const DEFAULT_BUDGET_EXHAUSTED_MESSAGE = "You've reached your AI usage limit. Contact your administrator to raise it.";
+/**
+ * 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 class BudgetExhaustedError extends Error {
+    constructor(
+    /** Vendor label of the transport that was refused (e.g. `'Anthropic'`). */
+    vendorLabel, 
+    /** The configured spend cap in USD, when the proxy reported one. */
+    budgetUsd, 
+    /** Spend already booked against that cap in USD, when the proxy reported it. */
+    spentUsd, 
+    /** The proxy's human-readable rejection message, when present. */
+    detail, 
+    /**
+     * 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) {
+        super(`${vendorLabel} request refused: the AI usage budget is exhausted` +
+            (budgetUsd != null
+                ? ` (spent ${spentUsd != null ? `$${spentUsd}` : 'an unknown amount'} of a $${budgetUsd} budget)`
+                : '') +
+            (detail ? `: ${detail}` : '') +
+            '. Retrying will not clear this — the budget must be raised.');
+        this.vendorLabel = vendorLabel;
+        this.budgetUsd = budgetUsd;
+        this.spentUsd = spentUsd;
+        this.detail = detail;
+        this.name = 'BudgetExhaustedError';
+        this.otherVendorAvailable = extra === null || extra === void 0 ? void 0 : extra.otherVendorAvailable;
+        this.serverVendor = extra === null || extra === void 0 ? void 0 : extra.serverVendor;
+    }
+}
+/**
+ * True for a budget rejection in either wire mode: the contracted `402`, or the
+ * `BUDGET_EXCEEDED` code under **any** status.
+ *
+ * Both keys are load-bearing, and they are not redundant:
+ *
+ * - `status` is the key the workstream-C contract guarantees ("402 always"), and
+ *   the only one a plain-text or unparseable rejection carries.
+ * - `code` is the cheap defence against that contract drifting. Nothing stops a
+ *   proxy from mapping the refusal onto `403` or `429` — and `429` is in *both*
+ *   transports' `RETRYABLE_STATUSES`, so a status-only check would hand the user
+ *   the exact bug GENC-1464 exists to fix: five doomed requests and ~31s of backoff
+ *   before an opaque failure. A well-formed `{ t: 'err', status: 429, code:
+ *   'BUDGET_EXCEEDED' }` frame is accepted by `readFramedBody` (it only rejects a
+ *   non-numeric status), so this is a reachable shape, not a hypothetical one.
+ *
+ * The false-positive cost is a proxy sending `code: 'BUDGET_EXCEEDED'` on a
+ * genuinely retryable failure — a shape the contract does not permit.
+ *
+ * Internal to the transports (unlike `BudgetExhaustedError`, which hosts branch
+ * on): deliberately **not** re-exported from the package index.
+ *
+ * @internal
+ */
+export const isBudgetRejection = (status, code) => status === BUDGET_EXCEEDED_STATUS || code === BUDGET_EXCEEDED_CODE;
+/**
+ * Best-effort JSON parse of an error body — `undefined` rather than a throw.
+ * Shared by every caller that has to classify a rejection body before it knows
+ * whether the body is JSON at all.
+ *
+ * @internal
+ */
+export const parseJsonOrUndefined = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch (_a) {
+        return undefined;
+    }
+};
+/**
+ * Read the `code` field off an already-parsed rejection body, ignoring anything
+ * that is not a string. Pairs with {@link isBudgetRejection} at the legacy call
+ * sites, which have a parsed body rather than a typed frame.
+ *
+ * @internal
+ */
+export const codeOf = (payload) => {
+    const code = payload === null || payload === void 0 ? void 0 : payload.code;
+    return typeof code === 'string' ? code : undefined;
+};
+/** Narrow an unknown JSON value to a number, ignoring anything else. */
+const numberOrUndefined = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+/** Narrow an unknown JSON value to a boolean, ignoring anything else. */
+const booleanOrUndefined = (value) => typeof value === 'boolean' ? value : undefined;
+/** Narrow an unknown JSON value to a non-empty string, ignoring anything else. */
+const stringOrUndefined = (value) => typeof value === 'string' && value.trim() !== '' ? value : undefined;
+/**
+ * Build a {@link BudgetExhaustedError} from a rejection payload of either shape:
+ * the legacy body `{ error, code, budgetUsd, spentUsd, vendor,
+ * otherVendorAvailable }` or the framed err frame's `details` (the same fields
+ * minus `error`) plus its top-level `error`.
+ *
+ * The fields read off the wire, and why each is here:
+ *
+ * | field                  | used for                                              |
+ * | ---------------------- | ----------------------------------------------------- |
+ * | `budgetUsd`            | the cap in the banner's figures                        |
+ * | `spentUsd`             | the spend in the banner's figures                      |
+ * | `error`                | the proxy's human-readable detail                      |
+ * | `vendor`               | attribution when the transport's own label is unclaimed |
+ * | `otherVendorAvailable` | whether "switch vendor" is honest advice at all        |
+ *
+ * Tolerant by design — a `402` classifies even when the payload is missing,
+ * unparseable, or carries none of these. Each field is narrowed independently,
+ * so a proxy that sends `null` for a figure it does not know (which the
+ * ai-service side now does, in preference to a misleading `0`) still yields the
+ * vendor and the availability verdict.
+ */
+export function budgetExhaustedFrom(vendorLabel, payload, fallbackDetail) {
+    var _a, _b, _c, _d;
+    const body = (typeof payload === 'object' && payload !== null ? payload : {});
+    // The framed shape nests everything but `error` under `details`; the legacy
+    // body has it all at the top level. Read both so one helper serves both call
+    // sites.
+    const details = (typeof body.details === 'object' && body.details !== null ? body.details : {});
+    const detail = typeof body.error === 'string' ? body.error : fallbackDetail;
+    return new BudgetExhaustedError(vendorLabel, (_a = numberOrUndefined(body.budgetUsd)) !== null && _a !== void 0 ? _a : numberOrUndefined(details.budgetUsd), (_b = numberOrUndefined(body.spentUsd)) !== null && _b !== void 0 ? _b : numberOrUndefined(details.spentUsd), detail, {
+        otherVendorAvailable: (_c = booleanOrUndefined(body.otherVendorAvailable)) !== null && _c !== void 0 ? _c : booleanOrUndefined(details.otherVendorAvailable),
+        serverVendor: (_d = stringOrUndefined(body.vendor)) !== null && _d !== void 0 ? _d : stringOrUndefined(details.vendor),
+    });
+}

package/dist/esm/transports/gemini-transport.js

@@ -3,6 +3,7 @@ import { SUPPORTED_GEMINI_MODEL_IDS, } from '../types';
 import { logger } from '../utils/logger';
 import { scaleTemperature } from '../utils/temperature';
 import { ResponseTruncatedError } from './anthropic-transport';
+import { VENDOR_LABELS } from './budget-exhausted-error';
 import { repairMalformedFunctionCall } from './gemini-malformed-call';
 import { postWithRetry } from './post-with-retry';
 const GEMINI_DIRECT_URL = (model) => `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent`;
@@ -604,7 +605,7 @@ export class GeminiTransport {
                 headers,
                 body: payload,
                 credentials,
-                vendorLabel: 'Gemini',
+                vendorLabel: VENDOR_LABELS.gemini,
                 retryableStatuses: GeminiTransport.RETRYABLE_STATUSES,
                 timeout: this.timeout,
                 stallTimeout: this.stallTimeout,

package/dist/esm/transports/post-with-retry.js

@@ -3,6 +3,7 @@ import { authoritativeAbortReason } from '../utils/abort-reason';
 import { abortableDelay } from '../utils/abortable-delay';
 import { combineSignals } from '../utils/combine-signals';
 import { logger } from '../utils/logger';
+import { budgetExhaustedFrom, codeOf, isBudgetRejection, parseJsonOrUndefined, } from './budget-exhausted-error';
 import { readFramedBody } from './ndjson-frames';
 const MAX_RETRIES = 5;
 /**
@@ -56,15 +57,44 @@ export function postWithRetry(options) {
                     signal: combinedSignal,
                     credentials,
                 });
-                if (retryableStatuses.includes(response.status) && attempt < MAX_RETRIES) {
-                    logger.warn(`${vendorLabel}Transport: retryable status ${response.status}, retrying (attempt ${attempt + 1}/${MAX_RETRIES})`);
-                    clearTimeout(timeoutId); // this attempt is over — don't let its timer tick through the backoff
-                    yield backoff(attempt);
-                    continue;
-                }
                 if (!response.ok) {
-                    const err = yield response.text();
-                    throw new Error(`${vendorLabel} request error ${response.status}: ${err}`);
+                    // One read of the error body per failing attempt — it feeds BOTH the
+                    // budget classification and the thrown message, and the response is
+                    // discarded either way. Note this means a retryable attempt now reads
+                    // the (small, proxy-authored) error body before backing off. That is the
+                    // price of the classification winning over the ladder in this branch as
+                    // well as the framed one; the attempt's wall-clock timer is still armed
+                    // and the read runs on the fetch's combined signal, so a pathological
+                    // non-terminating body times out rather than hanging.
+                    //
+                    // That timeout is a real behaviour change for a RETRYABLE status, and the
+                    // accepted cost of the symmetry: a 503 used to reach the ladder without
+                    // the body being touched, so a non-terminating one still backed off and
+                    // retried. Now the abort propagates out of `postWithRetry` instead.
+                    // Acceptable because these bodies are proxy-authored and small — if that
+                    // ever stops being true, read the body only when the status is
+                    // non-retryable or already budget-shaped.
+                    const errText = yield response.text();
+                    const parsed = parseJsonOrUndefined(errText);
+                    // The budget wall (GENC-1464) wins over ANY status-based retry — the same
+                    // rule the framed branch below applies, now symmetric. It must be
+                    // classified BEFORE the ladder, not after it: 402 is absent from every
+                    // RETRYABLE_STATUSES today, but a proxy that maps the refusal onto a
+                    // retryable status (or a future set that includes 402) would otherwise
+                    // cost five doomed requests and ~31s of backoff before an opaque error —
+                    // exactly the bug this classification exists to remove. Parsing is
+                    // best-effort: an unparseable or plain-text 402 still classifies, just
+                    // without the budget/spent figures.
+                    if (isBudgetRejection(response.status, codeOf(parsed))) {
+                        throw budgetExhaustedFrom(vendorLabel, parsed, errText || undefined);
+                    }
+                    if (retryableStatuses.includes(response.status) && attempt < MAX_RETRIES) {
+                        logger.warn(`${vendorLabel}Transport: retryable status ${response.status}, retrying (attempt ${attempt + 1}/${MAX_RETRIES})`);
+                        clearTimeout(timeoutId); // this attempt is over — don't let its timer tick through the backoff
+                        yield backoff(attempt);
+                        continue;
+                    }
+                    throw new Error(`${vendorLabel} request error ${response.status}: ${errText}`);
                 }
                 // The proxy streams NDJSON heartbeat frames when it supports them; an old
                 // proxy ignores our Accept header and returns plain JSON, so branch on
@@ -83,6 +113,15 @@ export function postWithRetry(options) {
                         // local stall, so the driver's TimeoutError branch handles both.
                         throw new DOMException(`${vendorLabel} request stalled: ${(_c = frame.error) !== null && _c !== void 0 ? _c : 'no upstream data'}`, 'TimeoutError');
                     }
+                    // The budget wall, framed (GENC-1464) — the in-band twin of the 402 above,
+                    // through the same predicate, keyed on status OR code. Classified before
+                    // the retryable ladder for the same reason UPSTREAM_STALLED is: the
+                    // classification must win over any status-based retry. That ordering is
+                    // no longer unique to this branch — the legacy branch above now applies
+                    // the identical rule, so the two read as one policy rather than two.
+                    if (isBudgetRejection(frame.status, frame.code)) {
+                        throw budgetExhaustedFrom(vendorLabel, frame);
+                    }
                     // An in-band retryable status joins the same attempt/backoff ladder as
                     // its HTTP-status equivalent (shared attempt counter).
                     if (retryableStatuses.includes(frame.status) && attempt < MAX_RETRIES) {

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

@@ -1,4 +1,5 @@
 import { __awaiter } from "tslib";
+import { budgetExhaustedFrom, codeOf, isBudgetRejection, parseJsonOrUndefined, VENDOR_LABELS, } from './budget-exhausted-error';
 const AI_SERVER_PATH = '/gwf/ai-service/chat-completions';
 const DEFAULT_MODEL = 'gpt-4o-mini';
 const DEFAULT_TIMEOUT = 30000;
@@ -56,6 +57,24 @@ export class ServerOpenAITransport {
             clearTimeout(timeoutId);
             if (!response.ok) {
                 const err = yield response.text();
+                const parsed = parseJsonOrUndefined(err);
+                // This transport does its own bare `fetch` rather than going through
+                // `postWithRetry` (it has no retry ladder, no stall timer and no framed
+                // mode), so it would otherwise be the one proxy call where a 402 stays an
+                // opaque `AI proxy error 402`. Classify it through the same shared
+                // predicate the envelope uses, so the typed error is uniform across
+                // transports even though the envelope is not.
+                //
+                // Scope, stated plainly: this transport serves only `sendStructuredPrompt`
+                // — it has no `chat()` — and its single caller
+                // (`OpenAIProvider.interpretCriteria`) catches everything and returns
+                // null. So a 402 here degrades smart-search silently and can never latch
+                // 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".
+                if (isBudgetRejection(response.status, codeOf(parsed))) {
+                    throw budgetExhaustedFrom(VENDOR_LABELS.openai, parsed, err || undefined);
+                }
                 throw new Error(`AI proxy error ${response.status}: ${err}`);
             }
             const data = (yield response.json());