@genesislcap/foundation-ai 15.11.0 → 15.12.0

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

@@ -2,6 +2,7 @@ import { __awaiter } from "tslib";
 import { SUPPORTED_GEMINI_MODEL_IDS, } from '../types';
 import { logger } from '../utils/logger';
 import { scaleTemperature } from '../utils/temperature';
+import { geminiTokenCost } from '../utils/token-cost';
 import { toGeminiSchema } from '../utils/tool-schema';
 import { ResponseTruncatedError } from './anthropic-transport';
 import { VENDOR_LABELS } from './budget-exhausted-error';
@@ -44,57 +45,6 @@ function assertSupportedGeminiModel(model) {
         throw new Error(`GeminiTransport: unsupported model "${model}". Use one of: ${SUPPORTED_GEMINI_MODEL_IDS.join(', ')}.`);
     }
 }
-/**
- * Prompt size (tokens) at or below which the standard pricing tier applies.
- * Above it, Gemini's long-context tier kicks in. Google applies a single tier
- * to the whole request based on prompt size — it is not a marginal/blended rate.
- */
-const GEMINI_LONG_CONTEXT_THRESHOLD = 200000;
-/**
- * Cached / context-cache input tokens bill at a flat ~10% of the model's normal input
- * rate — consistent across models (flash $0.30→$0.03, flash-lite $0.10→$0.01,
- * pro $1.25→$0.125). Source: https://ai.google.dev/gemini-api/docs/pricing.
- * (Explicit context caching also has an hourly storage fee; implicit caching — what we
- * rely on — has none, so only this read discount applies.)
- */
-const GEMINI_CACHED_INPUT_MULTIPLIER = 0.1;
-/**
- * Paid Standard tier rates (USD per million tokens) — https://ai.google.dev/gemini-api/docs/pricing
- */
-const GEMINI_PRICING = {
-    'gemini-2.5-flash-lite': {
-        kind: 'flat',
-        rate: { promptPerMillion: 0.1, candidatePerMillion: 0.4 },
-    },
-    'gemini-2.5-flash': { kind: 'flat', rate: { promptPerMillion: 0.3, candidatePerMillion: 2.5 } },
-    'gemini-2.5-pro': {
-        kind: 'tiered',
-        standard: { promptPerMillion: 1.25, candidatePerMillion: 10.0 },
-        longContext: { promptPerMillion: 2.5, candidatePerMillion: 15.0 },
-    },
-    'gemini-3.1-flash-lite': {
-        kind: 'flat',
-        rate: { promptPerMillion: 0.25, candidatePerMillion: 1.5 },
-    },
-    'gemini-3.5-flash': { kind: 'flat', rate: { promptPerMillion: 1.5, candidatePerMillion: 9.0 } },
-    'gemini-3.1-pro-preview': {
-        kind: 'tiered',
-        standard: { promptPerMillion: 2.0, candidatePerMillion: 12.0 },
-        longContext: { promptPerMillion: 4.0, candidatePerMillion: 18.0 },
-    },
-};
-/**
- * Resolves the per-million-token rates for a model given the request's prompt
- * size, selecting the long-context tier for tiered models when the prompt
- * exceeds {@link GEMINI_LONG_CONTEXT_THRESHOLD}.
- */
-function estimatedGeminiPaidRatesUsdPerMillion(model, promptTokens) {
-    const pricing = GEMINI_PRICING[model];
-    if (pricing.kind === 'flat') {
-        return pricing.rate;
-    }
-    return promptTokens > GEMINI_LONG_CONTEXT_THRESHOLD ? pricing.longContext : pricing.standard;
-}
 /**
  * Per-model warnings emitted on construction. flash-lite tiers are the cheap
  * default and warn-free; higher-cost, frontier, and preview models flag their
@@ -106,6 +56,41 @@ const GEMINI_MODEL_WARNINGS = {
     'gemini-3.5-flash': 'GeminiTransport: using gemini-3.5-flash — frontier model, materially higher cost than flash-lite; use for harder reasoning or agent tasks.',
     'gemini-3.1-pro-preview': 'GeminiTransport: using gemini-3.1-pro-preview — PREVIEW model (no stability guarantee, may be withdrawn) with significantly higher, prompt-size-tiered cost; reserve for tasks where flash reliability is insufficient.',
 };
+/**
+ * Gemini's `thinkingConfig` for a turn, given the model and the caller's
+ * {@link ChatThinkingPolicy}.
+ *
+ * `includeThoughts` is about what is **returned**, not what is billed, and stays on for every
+ * posture that thinks — a thinking-only turn would otherwise surface as blank, and the thought
+ * summary is what `logTokenUsage` reconciles its thinking-token accounting against.
+ *
+ * `thinkingBudget` is the posture itself: `0` off, `-1` model-decides. **Omitting it is the third
+ * state** and is what an undefined policy sends — the model's own default, exactly the request
+ * shape this transport issued before the option existed.
+ *
+ * Only the flash tiers can actually be turned off. `gemini-2.5-pro` always thinks (its minimum
+ * budget is 128; `0` is rejected), which is the same constraint Anthropic's Fable 5 has — so a
+ * clamp here is the norm across providers, not a Gemini quirk. The 3.x tiers moved to a
+ * `thinkingLevel` enum and do not take a numeric budget on every tier, so they are deliberately
+ * left on their default rather than sent a value that may not apply: a clamp costs money, but a
+ * guess costs a 400 on a turn the user is waiting for. Wire `thinkingLevel` through when the
+ * per-tier support is confirmed.
+ */
+const GEMINI_THINKING_DISABLEABLE = [
+    'gemini-2.5-flash',
+    'gemini-2.5-flash-lite',
+];
+function geminiThinkingConfig(model, policy) {
+    if (policy === 'off' && GEMINI_THINKING_DISABLEABLE.includes(model)) {
+        // No reasoning to return once there is none to bill for.
+        return { includeThoughts: false, thinkingBudget: 0 };
+    }
+    if (policy === 'auto' && GEMINI_THINKING_DISABLEABLE.includes(model)) {
+        return { includeThoughts: true, thinkingBudget: -1 };
+    }
+    // Undefined policy, or a model whose posture we cannot safely set: the default.
+    return { includeThoughts: true };
+}
 /**
  * Token accepted by the Gemini 3 API in place of a real `thoughtSignature` to
  * skip signature validation. Used when replaying a tool call whose signature
@@ -144,6 +129,25 @@ export class MalformedFunctionCallError extends Error {
  * @beta
  */
 export class GeminiTransport {
+    /**
+     * Warn once when a requested policy is silently clamped. Turning thinking off is a *cost*
+     * decision, so a caller who asked for it and kept paying for reasoning tokens needs to hear
+     * about it — but only once, not per turn.
+     *
+     * Only `'off'` can actually be denied. `'auto'` is already what an omitted budget produces on
+     * every model here — dynamic thinking is the documented default — so warning that it was
+     * "ignored" would be false, and latching on it would spend the one warning the genuinely
+     * unhonourable `'off'` needs.
+     */
+    warnIfThinkingUnclampable(policy) {
+        if (policy !== 'off' ||
+            GEMINI_THINKING_DISABLEABLE.includes(this.model) ||
+            this.warnedThinkingClamped) {
+            return;
+        }
+        this.warnedThinkingClamped = true;
+        logger.warn(`GeminiTransport: thinkingPolicy 'off' ignored — ${this.model} runs its default thinking posture and takes no budget we can safely set. Reasoning tokens are still billed at the candidate rate; use a flash tier if you need them gone.`);
+    }
     constructor(config = {}) {
         var _a, _b, _c;
         /**
@@ -159,6 +163,11 @@ export class GeminiTransport {
          * Surfaced alongside `getLifetimeCost`.
          */
         this.lifetimeSavingsUsd = 0;
+        /**
+         * Whether we have already told the caller their `thinkingPolicy` cannot be honoured on this
+         * model. Latched, because it would otherwise fire on every turn of a tool loop.
+         */
+        this.warnedThinkingClamped = false;
         const model = (_a = config.model) !== null && _a !== void 0 ? _a : DEFAULT_MODEL;
         assertSupportedGeminiModel(model);
         this.model = model;
@@ -248,12 +257,13 @@ export class GeminiTransport {
             // it can confidently parse the call (see `repairMalformedFunctionCall`),
             // falling back to the caller's retry otherwise.
             const toolConfig = tools ? toGeminiToolConfig(options === null || options === void 0 ? void 0 : options.toolChoice) : undefined;
-            // Request thought summaries so the model's official reasoning is returned
-            // (and a thinking-only turn surfaces *something* rather than going silently
-            // blank). Gemini 2.5 Pro always thinks regardless, so this only changes what
-            // is RETURNED, not what is billed — see `logTokenUsage` for the thinking-token
-            // accounting it lets us finally capture.
-            const generationConfig = { thinkingConfig: { includeThoughts: true } };
+            // Thinking posture for this turn. By default (no `thinkingPolicy`) this asks only for thought
+            // summaries, so the model's official reasoning is returned and a thinking-only turn surfaces
+            // *something* rather than going silently blank — see `logTokenUsage` for the thinking-token
+            // accounting it lets us capture. A policy adds an explicit `thinkingBudget` where the model
+            // supports one; Gemini 2.5 Pro always thinks regardless. See `geminiThinkingConfig`.
+            this.warnIfThinkingUnclampable(options === null || options === void 0 ? void 0 : options.thinkingPolicy);
+            const generationConfig = { thinkingConfig: geminiThinkingConfig(this.model, options === null || options === void 0 ? void 0 : options.thinkingPolicy) };
             // Normalized [0,1] temperature → Gemini's native range, anchored so 0.5
             // maps to its default (native 1) and 1 to its ceiling (native 2).
             if ((options === null || options === void 0 ? void 0 : options.temperature) != null) {
@@ -288,34 +298,27 @@ export class GeminiTransport {
      * message.
      */
     logTokenUsage(promptTokens, candidateTokens, thoughtTokens, cachedTokens) {
-        const { promptPerMillion, candidatePerMillion } = estimatedGeminiPaidRatesUsdPerMillion(this.model, promptTokens);
-        const m = GeminiTransport.TOKENS_PER_MILLION;
-        // `promptTokenCount` INCLUDES the cached portion (opposite of Anthropic's `input_tokens`),
-        // so split it: the uncached remainder bills at the full input rate and the cached slice at
-        // ~0.1×. The pricing TIER is still chosen on the full prompt size (above). `cachedTokens`
-        // is 0 when caching wasn't active, so this is a no-op then.
-        const uncachedPromptTokens = Math.max(0, promptTokens - cachedTokens);
-        const promptCost = (uncachedPromptTokens / m) * promptPerMillion;
-        const cacheReadCost = (cachedTokens / m) * promptPerMillion * GEMINI_CACHED_INPUT_MULTIPLIER;
-        // Thinking tokens are billed at the output (candidate) rate. They are
-        // incurred whenever the model thinks (always, on 2.5 Pro) — counting them
-        // here corrects a long-standing undercount, it does not raise the bill.
-        const candidateCost = ((candidateTokens + thoughtTokens) / m) * candidatePerMillion;
-        const totalCost = promptCost + cacheReadCost + candidateCost;
-        this.lifetimeCostUsd += totalCost;
-        // Savings vs no caching: the cached tokens would have cost full input price; we paid ~0.1×.
-        // Implicit caching has no write premium, so this is always ≥ 0.
-        const saved = (cachedTokens / m) * promptPerMillion - cacheReadCost;
-        this.lifetimeSavingsUsd += saved;
+        // The arithmetic, the rate table and the long-context tiering rule live in
+        // `utils/token-cost` so a host pricing its own requests uses the same numbers
+        // instead of a hand-copied table that drifts. This method keeps only what is
+        // instance-scoped: the lifetime accumulators and the log.
+        const { costUsd, savedUsd, breakdown } = geminiTokenCost(this.model, {
+            promptTokens,
+            candidateTokens,
+            thoughtTokens,
+            cachedTokens,
+        });
+        this.lifetimeCostUsd += costUsd;
+        this.lifetimeSavingsUsd += savedUsd;
         const dp = GeminiTransport.COST_DECIMAL_PLACES;
         console.log(`--- Gemini Token Usage (${this.model}) ---`);
-        console.log(`Prompt Tokens:    ${promptTokens} (${cachedTokens} cached) ($${promptCost.toFixed(dp)} + $${cacheReadCost.toFixed(dp)})`);
-        console.log(`Candidate Tokens: ${candidateTokens} (+${thoughtTokens} thinking) ($${candidateCost.toFixed(dp)})`);
-        console.log(`Total Cost:       $${totalCost.toFixed(dp)}`);
-        console.log(`Cache Saved:      $${saved.toFixed(dp)} (lifetime $${this.lifetimeSavingsUsd.toFixed(dp)})`);
+        console.log(`Prompt Tokens:    ${promptTokens} (${cachedTokens} cached) ($${breakdown.promptUsd.toFixed(dp)} + $${breakdown.cacheReadUsd.toFixed(dp)})`);
+        console.log(`Candidate Tokens: ${candidateTokens} (+${thoughtTokens} thinking) ($${breakdown.candidateUsd.toFixed(dp)})`);
+        console.log(`Total Cost:       $${costUsd.toFixed(dp)}`);
+        console.log(`Cache Saved:      $${savedUsd.toFixed(dp)} (lifetime $${this.lifetimeSavingsUsd.toFixed(dp)})`);
         console.log(`Lifetime Cost:    $${this.lifetimeCostUsd.toFixed(dp)}`);
         console.log('--------------------------');
-        return totalCost;
+        return costUsd;
     }
     toGeminiContents(history, userMessage, attachments) {
         var _a, _b, _c;

package/dist/esm/types/config.types.js

@@ -16,3 +16,35 @@ export const SUPPORTED_ANTHROPIC_MODEL_IDS = [
     'claude-sonnet-4-6',
     'claude-haiku-4-5-20251001',
 ];
+/**
+ * Which vendor a model id belongs to, or `undefined` when no supported provider claims it.
+ *
+ * @remarks
+ * Derived from {@link SUPPORTED_ANTHROPIC_MODEL_IDS} and {@link SUPPORTED_GEMINI_MODEL_IDS},
+ * so it cannot drift from them the way a hand-maintained map does — adding a model to an
+ * allowlist is enough to teach this too.
+ *
+ * Exists because callers hold a **model id**, not a vendor. A usage ledger reads a message's
+ * `model` and then has to pick the matching pricing function — `anthropicTokenCost` vs
+ * `geminiTokenCost` — whose usage records are deliberately not interchangeable, because the
+ * two providers disagree about whether the prompt figure includes the cached part. Without
+ * this, every such caller writes its own model→vendor map, which is the same duplication that
+ * exporting the pricing removes.
+ *
+ * Returns `undefined` rather than falling back to a default vendor so an unrecognised model
+ * is a decision the caller has to make out loud. Silently defaulting is precisely how an
+ * unlisted model gets priced at some other tier's rates — a consumer has already had Haiku
+ * billed at Sonnet rates that way.
+ *
+ * Takes a plain `string`, not a union: the interesting callers are reading a model id back
+ * off a stored message or a config file, where it is untrusted text.
+ *
+ * @beta
+ */
+export function vendorOfModel(modelId) {
+    if (SUPPORTED_ANTHROPIC_MODEL_IDS.includes(modelId))
+        return 'anthropic';
+    if (SUPPORTED_GEMINI_MODEL_IDS.includes(modelId))
+        return 'gemini';
+    return undefined;
+}

package/dist/esm/utils/token-cost.js

@@ -0,0 +1,238 @@
+/**
+ * Per-request cost pricing for the models this package can call.
+ *
+ * @remarks
+ * Extracted from the two transports' private cost paths so a host that prices
+ * requests of its own — a server proxy, a usage ledger, a benchmark — computes the
+ * same numbers instead of hand-copying the rate tables. Duplicated tables drift:
+ * an unlisted model silently prices at whatever the copy's fallback is, and a
+ * missing multiplier misprices every cached request.
+ *
+ * **Typed over raw provider usage, deliberately.** These take the token counts a
+ * provider response reports, NOT `ChatMessage`/`AggregateUsage`. Two reasons:
+ *
+ * 1. `ChatMessage.cacheWriteTokens` is a single total, but Anthropic bills cache
+ *    writes per TTL (5-minute at 1.25×, 1-hour at 2×). The split exists only in
+ *    the provider response, so pricing from a message cannot be exact.
+ * 2. The path that actually needs to compute a cost is the one where no transport
+ *    stamped one — a proxied or server-side call holding a raw usage block.
+ *
+ * When a `ChatMessage` already carries `cost`, use that; it was computed here at
+ * request time with information the message no longer has. Re-deriving a cost
+ * from a message's token fields is wrong in the expensive direction, because
+ * `inputTokens` is total prompt size *including* the cached part.
+ *
+ * **What this model cannot express, by construction.** Everything here is
+ * *per-request*: a function of the tokens one call consumed. Caching priced by
+ * **elapsed time** does not fit, and no additional bucket would make it fit —
+ * Gemini's explicit context caching, for instance, charges an hourly storage fee
+ * that accrues while you are making no requests at all. Nothing to attribute it to.
+ *
+ * A provider whose caching is billed that way needs a **separate ledger entry**,
+ * recorded against a cache's lifetime rather than against a request, and summed
+ * alongside these figures rather than inside them. Do not fold it into
+ * {@link TokenCostBreakdown} — a storage fee divided across whatever requests
+ * happened to occur is an invented number, and it would make two runs with
+ * identical token usage report different costs for reasons neither run caused.
+ *
+ * The vendors also differ in shape more than they differ in rates, which is why
+ * there is a function per provider rather than one with a normalised record:
+ * Anthropic charges a premium for the cache *write* and lets you choose the TTL;
+ * Gemini's implicit caching has no write charge at all; a provider with automatic,
+ * non-configurable caching has neither a write bucket nor a TTL to record. The
+ * shared vocabulary is the RESULT ({@link TokenCost}), not the input.
+ */
+/** One million — the unit every published rate is quoted in. */
+const TOKENS_PER_MILLION = 1000000;
+// ---------------------------------------------------------------------------
+// Anthropic
+// ---------------------------------------------------------------------------
+/**
+ * Standard tier pricing per million tokens —
+ * https://docs.claude.com/en/docs/about-claude/pricing
+ *
+ * @beta
+ */
+const ANTHROPIC_PRICING = {
+    'claude-haiku-4-5-20251001': { promptPerMillion: 1, candidatePerMillion: 5 },
+    // Fable 5 — Anthropic's most capable widely-released model; priced above Opus tier.
+    'claude-fable-5': { promptPerMillion: 10, candidatePerMillion: 50 },
+    // Opus 4.7 / 4.8 — same $5 / $25 per MTok. Stated per model rather than shared through a
+    // fall-through, so neither is ever "whatever was left over".
+    'claude-opus-4-8': { promptPerMillion: 5, candidatePerMillion: 25 },
+    'claude-opus-4-7': { promptPerMillion: 5, candidatePerMillion: 25 },
+    // Sonnet 5 is $2 / $10 — its OWN tier, and CHEAPER than the older Sonnet 4.6 below.
+    //
+    // This launched as an introductory rate through 2026-08-31, and an earlier version of this
+    // table deliberately charged the $3 / $15 standard rate instead, on the reasoning that the
+    // introductory period would lapse. Anthropic has since confirmed $2 / $10 as the permanent
+    // standard price and cancelled the scheduled increase, so that reasoning is dead and the old
+    // figure over-charged every Sonnet 5 request by 50%.
+    // https://platform.claude.com/docs/en/about-claude/pricing#model-pricing
+    'claude-sonnet-5': { promptPerMillion: 2, candidatePerMillion: 10 },
+    // Sonnet 4.6 remains on the older $3 / $15 Sonnet tier — the newer model is the cheaper one.
+    'claude-sonnet-4-6': { promptPerMillion: 3, candidatePerMillion: 15 },
+};
+/**
+ * Standard tier pricing per million tokens —
+ * https://docs.claude.com/en/docs/about-claude/pricing
+ *
+ * @remarks
+ * Backed by a total {@link https://www.typescriptlang.org/docs/handbook/utility-types.html#recordkeys-type | Record}
+ * over `AnthropicModelId` rather than a chain of checks with a default. That is the whole
+ * point: adding a model to `SUPPORTED_ANTHROPIC_MODEL_IDS` without pricing it becomes a
+ * COMPILE error instead of a silent charge at whatever the fall-through happened to be — the
+ * exact failure this module's header warns about, and one a consumer has already been bitten
+ * by. The Gemini half of this file has always had the guarantee; this half now matches.
+ *
+ * @beta
+ */
+export function anthropicRatesFor(model) {
+    return ANTHROPIC_PRICING[model];
+}
+/**
+ * Prompt-cache pricing multipliers, applied to the model's base input rate
+ * (`promptPerMillion`) — https://docs.claude.com/en/docs/build-with-claude/prompt-caching
+ * Reads bill at ~0.1× base input; writes bill by TTL — 5-minute at ~1.25× and 1-hour at 2×.
+ * Both write TTLs are reachable (`CachePolicy.ttl` is `'5m' | '1h'`), so each TTL bucket is
+ * costed from the response's per-TTL `cache_creation` breakdown rather than assuming one rate.
+ *
+ * @beta
+ */
+export const ANTHROPIC_CACHE_READ_MULTIPLIER = 0.1;
+/** @beta */
+export const ANTHROPIC_CACHE_WRITE_5M_MULTIPLIER = 1.25;
+/** @beta */
+export const ANTHROPIC_CACHE_WRITE_1H_MULTIPLIER = 2;
+/**
+ * Cost one Anthropic request.
+ *
+ * @beta
+ */
+export function anthropicTokenCost(model, usage) {
+    const { promptPerMillion, candidatePerMillion } = anthropicRatesFor(model);
+    const m = TOKENS_PER_MILLION;
+    // Split the creation total into its 1-hour portion and the 5-minute remainder and
+    // cost each at its own rate. All buckets are multiples of the same base input rate,
+    // so summing them stays correct whether or not caching was active (every cache
+    // field is 0 when it wasn't).
+    const cacheWrite5mTokens = Math.max(0, usage.cacheWriteTokens - usage.cacheWrite1hTokens);
+    const promptCost = (usage.uncachedInputTokens / m) * promptPerMillion;
+    const cacheReadCost = (usage.cacheReadTokens / m) * promptPerMillion * ANTHROPIC_CACHE_READ_MULTIPLIER;
+    const cacheWriteCost = (cacheWrite5mTokens / m) * promptPerMillion * ANTHROPIC_CACHE_WRITE_5M_MULTIPLIER +
+        (usage.cacheWrite1hTokens / m) * promptPerMillion * ANTHROPIC_CACHE_WRITE_1H_MULTIPLIER;
+    const candidateCost = (usage.outputTokens / m) * candidatePerMillion;
+    // Net saving vs no caching: the cache-read tokens would have cost full input price
+    // (we paid ~0.1× of that), while the write premium is an upfront cost that pays back
+    // on later reads — so the net dips negative on a write-heavy request and climbs
+    // positive as reads accrue.
+    const cacheReadFull = (usage.cacheReadTokens / m) * promptPerMillion;
+    const cacheWriteFull = (usage.cacheWriteTokens / m) * promptPerMillion;
+    return {
+        costUsd: promptCost + cacheReadCost + cacheWriteCost + candidateCost,
+        savedUsd: cacheReadFull - cacheReadCost + (cacheWriteFull - cacheWriteCost),
+        breakdown: {
+            promptUsd: promptCost,
+            cacheReadUsd: cacheReadCost,
+            cacheWriteUsd: cacheWriteCost,
+            candidateUsd: candidateCost,
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Gemini
+// ---------------------------------------------------------------------------
+/**
+ * Prompt size (tokens) at or below which the standard pricing tier applies.
+ * Above it, Gemini's long-context tier kicks in. Google applies a single tier
+ * to the whole request based on prompt size — it is not a marginal/blended rate.
+ *
+ * @beta
+ */
+export const GEMINI_LONG_CONTEXT_THRESHOLD = 200000;
+/**
+ * Cached / context-cache input tokens bill at a flat ~10% of the model's normal input
+ * rate — consistent across models (flash $0.30→$0.03, flash-lite $0.10→$0.01,
+ * pro $1.25→$0.125). Source: https://ai.google.dev/gemini-api/docs/pricing.
+ * (Explicit context caching also has an hourly storage fee; implicit caching — what the
+ * transport relies on — has none, so only this read discount applies. There is no write
+ * premium on this provider, which is why its savings figure is never negative.)
+ *
+ * @beta
+ */
+export const GEMINI_CACHED_INPUT_MULTIPLIER = 0.1;
+/**
+ * Paid Standard tier rates (USD per million tokens) —
+ * https://ai.google.dev/gemini-api/docs/pricing
+ */
+const GEMINI_PRICING = {
+    'gemini-2.5-flash-lite': {
+        kind: 'flat',
+        rate: { promptPerMillion: 0.1, candidatePerMillion: 0.4 },
+    },
+    'gemini-2.5-flash': { kind: 'flat', rate: { promptPerMillion: 0.3, candidatePerMillion: 2.5 } },
+    'gemini-2.5-pro': {
+        kind: 'tiered',
+        standard: { promptPerMillion: 1.25, candidatePerMillion: 10.0 },
+        longContext: { promptPerMillion: 2.5, candidatePerMillion: 15.0 },
+    },
+    'gemini-3.1-flash-lite': {
+        kind: 'flat',
+        rate: { promptPerMillion: 0.25, candidatePerMillion: 1.5 },
+    },
+    'gemini-3.5-flash': { kind: 'flat', rate: { promptPerMillion: 1.5, candidatePerMillion: 9.0 } },
+    'gemini-3.1-pro-preview': {
+        kind: 'tiered',
+        standard: { promptPerMillion: 2.0, candidatePerMillion: 12.0 },
+        longContext: { promptPerMillion: 4.0, candidatePerMillion: 18.0 },
+    },
+};
+/**
+ * Resolve the per-million-token rates for a model given the request's prompt size,
+ * selecting the long-context tier for tiered models when the prompt exceeds
+ * {@link GEMINI_LONG_CONTEXT_THRESHOLD}.
+ *
+ * @remarks
+ * `promptTokens` must be the **full** prompt size, cached slice included — the tier
+ * is chosen on what was sent, not on what was billed at full rate. A mostly-cached
+ * long prompt is still a long prompt.
+ *
+ * Unlike Anthropic's, this accessor is not a pure function of the model, which is
+ * why there is no single `ratesFor(model)` across both providers.
+ *
+ * @beta
+ */
+export function geminiRatesFor(model, promptTokens) {
+    const pricing = GEMINI_PRICING[model];
+    if (pricing.kind === 'flat') {
+        return pricing.rate;
+    }
+    return promptTokens > GEMINI_LONG_CONTEXT_THRESHOLD ? pricing.longContext : pricing.standard;
+}
+/**
+ * Cost one Gemini request.
+ *
+ * @beta
+ */
+export function geminiTokenCost(model, usage) {
+    // The pricing TIER is chosen on the full prompt size, BEFORE the cache split.
+    const { promptPerMillion, candidatePerMillion } = geminiRatesFor(model, usage.promptTokens);
+    const m = TOKENS_PER_MILLION;
+    const uncachedPromptTokens = Math.max(0, usage.promptTokens - usage.cachedTokens);
+    const promptCost = (uncachedPromptTokens / m) * promptPerMillion;
+    const cacheReadCost = (usage.cachedTokens / m) * promptPerMillion * GEMINI_CACHED_INPUT_MULTIPLIER;
+    // Thinking tokens bill at the output rate, and are incurred whenever the model
+    // thinks (always, on 2.5 Pro).
+    const candidateCost = ((usage.candidateTokens + usage.thoughtTokens) / m) * candidatePerMillion;
+    return {
+        costUsd: promptCost + cacheReadCost + candidateCost,
+        // Implicit caching has no write premium, so this is always >= 0.
+        savedUsd: (usage.cachedTokens / m) * promptPerMillion - cacheReadCost,
+        breakdown: {
+            promptUsd: promptCost,
+            cacheReadUsd: cacheReadCost,
+            cacheWriteUsd: 0,
+            candidateUsd: candidateCost,
+        },
+    };
+}