ak-gemini 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 2.6.0
+
+> **Upgrading from 2.5.0?** [UPGRADING.md](./UPGRADING.md) walks through only what you
+> need to change, with before/after examples.
+
+Feature request from a downstream consumer (`smarterchild/agent`, Vertex AI),
+paired with ak-claude 0.2.0. **Minor** bump — cached-token billing changes
+reported cost (see "Behavior changes" below).
+
+### Behavior changes (read before upgrading)
+- **Cached tokens are now billed at the discounted cached rate.**
+  `usageMetadata.cachedContentTokenCount` is surfaced as `usage.cachedTokens` and
+  factored into `estimatedCost`. **Gemini INCLUDES cached tokens in
+  `promptTokenCount`**, so they are *subtracted* from the prompt count and
+  re-billed at `cachedInput` — they are a subset, not an addition. (ak-claude is
+  the opposite: Anthropic excludes cache tokens from `input_tokens` and they are
+  added on top. The asymmetry is intentional; do not "unify" it.) Reported cost
+  for cache-heavy calls drops by up to ~10×. Models with no published cached rate
+  bill cached tokens at the full input rate — an overestimate, never an
+  underestimate.
+- **Pro models switch to their >200k-context tier above 200,000 prompt tokens.**
+  `gemini-2.5-pro` and `gemini-3.1-pro-preview` previously billed every call at
+  the ≤200k rate. Long-context calls now report roughly 2× the input cost they
+  did before, which is what Google actually charges.
+- **`gemini-2.5-flash` output pricing corrected from $2.50 to $3.00 per M.**
+  Reported cost for that model rises accordingly.
+- **`gemini-flash-latest` now resolves to `gemini-3.6-flash`** (was
+  `gemini-3.5-flash`) and **`gemini-flash-lite-latest` to `gemini-3.5-flash-lite`**
+  for pricing. Alias resolution is logged at debug — prefer the model id the API
+  echoes in `modelVersion`, which `_estimatedCost` already does.
+- **`getLastUsage()` now reports non-zero `thoughtsTokens` on `Chat`,
+  `ToolAgent`, `CodeAgent`, `RagAgent`, and `Transformer`.** These classes seeded
+  `_cumulativeUsage` without the thinking-token count, so `getLastUsage()`
+  reported `0` (and undercounted cost) even when the response carried thoughts.
+  `result.usage` was already correct.
+
+### Added
+- **`effort: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'`** on every
+  class — the cross-package option name (identical to ak-claude). Maps to
+  `thinkingConfig.thinkingLevel` and wins over an explicit `thinkingLevel` /
+  `thinkingBudget` (the two are mutually exclusive on the wire). `xhigh` and
+  `max` are ak-claude-only levels and clamp to `high`. An unrecognized level
+  throws at construction.
+- **`usage.cachedTokens`** on every `send()`/`chat()`/`generate()` result and on
+  `getLastUsage()`.
+- **Pricing for new models:** `gemini-3.6-flash` ($1.50/$7.50, cached $0.15) and
+  `gemini-3.5-flash-lite` ($0.30/$2.50, cached $0.03).
+- **`cachedInput` rates** on every model where Google publishes one, plus
+  `inputAbove200k` / `outputAbove200k` / `cachedInputAbove200k` on the tiered Pro
+  models.
+- **New exports:** `MODEL_PRICING_AS_OF` (the date the table was last verified
+  against Google's pricing page) and `EFFORT_LEVELS`. `resolvePricing()` now
+  returns `asOf` and `tierThreshold`.
+- `computeCost()` takes two new optional trailing args:
+  `computeCost(modelId, prompt, response, thoughtsTokens?, cachedTokens?)`.
+
+### Notes
+- `null` from `resolvePricing()` / `usage.estimatedCost` means the model's
+  pricing is **unknown** — it does not mean the call was free.
+- Cache **storage** ($1.00/1M tokens/hour on Flash tiers, $4.50 on Pro) is
+  time-based and is **not** modelled by `estimatedCost` — only per-token charges
+  are.
+- Image-output tokens on Nano Banana models ($60/M or $120/M) are still not
+  modelled.
+
 ## 2.5.0
 
 Fixes from a downstream consumer's adversarial review. This is a **minor** bump —

package/README.md

@@ -285,9 +285,29 @@ const cost = await instance.estimateCost({ some: 'payload' });
 
 ```javascript
 const usage = instance.getLastUsage();
-// { promptTokens, responseTokens, totalTokens, attempts, modelVersion, requestedModel, timestamp }
+// { promptTokens, responseTokens, thoughtsTokens, cachedTokens, totalTokens,
+//   attempts, modelVersion, requestedModel, timestamp, estimatedCost }
 ```
 
+`estimatedCost` is USD from `MODEL_PRICING`. **`null` means the model's pricing is
+unknown — not that the call was free.**
+
+**`cachedTokens` is a subset of `promptTokens`, not an addition.** Gemini includes
+`cachedContentTokenCount` inside `promptTokenCount`, so `computeCost()` subtracts
+them and re-bills at the discounted `cachedInput` rate. (`ak-claude` is the
+opposite — Anthropic excludes cache tokens from `input_tokens` and they are added
+on top.) Models with no published cached rate bill cached tokens at the full input
+rate: an overestimate, never an underestimate.
+
+Two things are deliberately **not** modelled: cache **storage** (time-based,
+$1.00/1M tokens/hour on Flash tiers and $4.50 on Pro) and image-output tokens on
+the Nano Banana models ($60/M or $120/M).
+
+Pro models are tiered — `gemini-2.5-pro` and `gemini-3.1-pro-preview` switch to a
+higher rate above 200,000 prompt tokens. `resolvePricing()` returns `tierThreshold`
+and `asOf` (the date the table was last verified against Google's pricing page,
+also exported as `MODEL_PRICING_AS_OF`).
+
 ### Few-Shot Seeding
 
 ```javascript
@@ -298,13 +318,30 @@ await instance.seed([
 
 ### Thinking Configuration
 
+Use `effort` — it is the same option name in `ak-claude`, so one config object
+works against both packages:
+
 ```javascript
 new Chat({
-  modelName: 'gemini-2.5-flash',
-  thinkingConfig: { thinkingBudget: 1024 }
+  modelName: 'gemini-3.5-flash',
+  effort: 'high'          // 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
 });
+// wire: thinkingConfig: { thinkingLevel: 'high' }
+```
+
+`xhigh` and `max` are ak-claude-only levels and clamp to `high` here. An
+unrecognized level throws at construction.
+
+The raw SDK shape still works:
+
+```javascript
+new Chat({ modelName: 'gemini-2.5-flash', thinkingConfig: { thinkingBudget: 1024 } });
 ```
 
+`thinkingLevel` and `thinkingBudget` are mutually exclusive on the wire — when
+`effort` is set (or you pass `thinkingLevel` yourself), `thinkingBudget` is
+dropped. `effort` wins over both.
+
 ### Google Search Grounding
 
 Ground responses in real-time web search results. Available on all classes.
@@ -390,7 +427,8 @@ All classes accept `BaseGeminiOptions`:
 | `project` | string | env var | GCP project ID |
 | `location` | string | `'global'` | GCP region |
 | `chatConfig` | object | — | Gemini chat config overrides |
-| `thinkingConfig` | object | — | Thinking features config |
+| `thinkingConfig` | object | — | Thinking features config (`thinkingBudget` or `thinkingLevel`) |
+| `effort` | string | — | `'minimal'`\|`'low'`\|`'medium'`\|`'high'`\|`'xhigh'`\|`'max'`. Maps to `thinkingConfig.thinkingLevel`; wins over it |
 | `maxOutputTokens` | number | `50000` | Max tokens in response (`null` removes limit) |
 | `logLevel` | string | based on NODE_ENV | `'trace'`\|`'debug'`\|`'info'`\|`'warn'`\|`'error'`\|`'none'` |
 | `labels` | object | — | Billing labels (Vertex AI) |
@@ -478,6 +516,13 @@ All tests use real Gemini API calls (no mocks). Rate limiting (429 errors) can c
 
 ---
 
+## Upgrading
+
+**Upgrading from 2.5.0 to 2.6.0?** See [UPGRADING.md](./UPGRADING.md). 2.6.0 adds the
+`effort` option and corrects cost reporting — cached tokens now bill at the discounted
+rate, Pro models are tiered above 200k, and `thoughtsTokens` is no longer dropped from
+`getLastUsage()`. Full detail in [CHANGELOG.md](./CHANGELOG.md).
+
 ## Migration from v1.x
 
 See [MIGRATION.md](./MIGRATION.md) for a detailed guide on upgrading from v1.x to v2.0.

package/UPGRADING.md

@@ -0,0 +1,111 @@
+# Upgrading ak-gemini
+
+Per-version upgrade notes. For the full list of changes see [CHANGELOG.md](./CHANGELOG.md). For the v1.x → v2.0 rewrite, see [MIGRATION.md](./MIGRATION.md).
+
+---
+
+## 2.5.0 → 2.6.0
+
+**Minor bump. No API surface is removed and no call signature breaks.** What changes is what `estimatedCost` reports — in most cases it goes *down*, because cached tokens and context tiers are now modelled correctly.
+
+Companion release to **ak-claude 0.2.0**; the two packages keep matching option names.
+
+### At a glance
+
+| If you… | Then… |
+|---|---|
+| don't use context caching and stay under 200k tokens | numbers are unchanged, except `gemini-2.5-flash` — see #3 |
+| use context caching (`cachedContent` / `useCache()`) | your reported cost drops — cached tokens now bill at the discounted rate, see #1 |
+| send >200k-token prompts to a Pro model | your reported cost rises to the correct tier rate — see #2 |
+| use `gemini-2.5-flash` | output rate corrected $2.50 → $3.00 per M — see #3 |
+| use `gemini-flash-latest` or `gemini-flash-lite-latest` | these aliases now resolve to newer models — see #4 |
+| read `getLastUsage()` on Chat / ToolAgent / CodeAgent / RagAgent / Transformer | `thoughtsTokens` is now non-zero when thinking ran — see #5 |
+| want to control reasoning depth | new `effort` option — see #6 |
+
+---
+
+### 1. Cached tokens are billed at the cached rate
+
+**This is the change most likely to move your numbers.**
+
+Gemini's `promptTokenCount` **includes** `cachedContentTokenCount`. Before 2.6.0, ak-gemini billed the whole prompt count at the full input rate, so cached tokens were charged as if they were fresh — a large overestimate on cache-heavy workloads.
+
+`computeCost()` now subtracts cached tokens from the prompt count and re-bills them at `cachedInput` (roughly a 10× discount):
+
+```js
+// promptTokens: 10_000, of which cachedTokens: 8_000, on gemini-3.5-flash
+// 2.5.0:  10_000 × $1.50/M                        = $0.0150
+// 2.6.0:   2_000 × $1.50/M + 8_000 × $0.15/M      = $0.0042
+```
+
+`usage.cachedTokens` is now exposed on both `getLastUsage()` and per-call `result.usage`.
+
+> **`cachedTokens` is a SUBSET of `promptTokens`, not an addition.** Do not sum them. This is the opposite of **ak-claude**, where Anthropic *excludes* cache tokens from `input_tokens` and they are added on top. If you have code that normalizes usage across both packages, this asymmetry is the thing to get right.
+
+Models with no published `cachedInput` rate fall back to the full input rate — an overestimate, never an underestimate.
+
+**Still not modelled:** cache *storage*, which is time-based ($1.00 per 1M tokens per hour on Flash tiers, $4.50 on Pro). `estimatedCost` covers per-token charges only.
+
+### 2. Context-tier pricing above 200k tokens
+
+Pro models switch to a higher rate above 200,000 prompt tokens. Previously ak-gemini always billed the ≤200k tier, understating cost on long-context calls.
+
+```js
+resolvePricing('gemini-2.5-pro')
+// { input: 1.25, output: 10.00, cachedInput: 0.125,
+//   inputAbove200k: 2.50, outputAbove200k: 15.00, cachedInputAbove200k: 0.25,
+//   tierThreshold: 200000, asOf: '2026-07-28' }
+```
+
+`computeCost()` picks the tier from `promptTokens` automatically. Populated for `gemini-2.5-pro` and `gemini-3.1-pro-preview`.
+
+### 3. `gemini-2.5-flash` output rate corrected
+
+$2.50 → **$3.00** per M output tokens. The old value was wrong against Google's published pricing. If you track cost over time, expect a step change here.
+
+### 4. Alias repointing
+
+| Alias | 2.5.0 resolved to | 2.6.0 resolves to |
+|---|---|---|
+| `gemini-flash-latest` | `gemini-3.5-flash` | `gemini-3.6-flash` |
+| `gemini-flash-lite-latest` | `gemini-3.1-flash-lite` | `gemini-3.5-flash-lite` |
+
+Aliases are a pricing-table convenience and go stale whenever Google rotates what they point at. ak-gemini already prefers the model id the API **echoes** (`response.modelVersion`) over the alias you requested, and now logs each alias resolution at debug level. Pin a concrete model id if you need cost reporting you can audit.
+
+New pricing entries: `gemini-3.6-flash` ($1.50 / $7.50) and `gemini-3.5-flash-lite` ($0.30 / $2.50).
+
+### 5. `thoughtsTokens` now appears in `getLastUsage()`
+
+`Chat`, `ToolAgent`, `CodeAgent`, `RagAgent`, and `Transformer` seeded their cumulative usage without `thoughtsTokens`, so `getLastUsage()` reported `0` and **omitted thinking tokens from `estimatedCost`** even when the response carried them. Per-call `result.usage` was already correct.
+
+If you read cost from `getLastUsage()` on a thinking-enabled model, your reported cost will rise — it was under-reporting before. Thinking tokens bill at the output rate.
+
+### 6. New `effort` option
+
+The cross-package reasoning-depth knob — same option name in ak-claude.
+
+```js
+new Chat({ modelName: 'gemini-3.5-flash', effort: 'high' })
+// → thinkingConfig: { thinkingLevel: 'high' }
+```
+
+Accepts `'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'`. Gemini's wire field only goes up to `high`, so **`xhigh` and `max` clamp to `high`** — they exist so the same config object works against both packages. An unrecognized value **throws at construction**.
+
+`effort` wins over an explicit `thinkingLevel` or `thinkingBudget`; `thinkingLevel` and `thinkingBudget` are mutually exclusive on the wire, so setting `effort` deletes any budget. `thinkingConfig: null` still disables thinking outright and takes precedence over `effort`.
+
+`thinkingConfig: { thinkingBudget: N }` continues to work unchanged.
+
+### New exports
+
+```js
+import {
+  MODEL_PRICING_AS_OF,   // date the pricing table was last verified
+  EFFORT_LEVELS,         // ['minimal','low','medium','high','xhigh','max']
+  resolvePricing,        // now returns `tierThreshold` and `asOf`
+  computeCost            // now takes (model, prompt, response, thoughts?, cached?)
+} from 'ak-gemini';
+```
+
+`computeCost()`'s new `cachedTokens` argument is optional and trailing — existing 3- and 4-argument calls behave as before, except for the tier selection in #2.
+
+> **A `null` from `resolvePricing()` or `estimatedCost` means UNKNOWN, not free.** Unpriced models (Gemma, anything not in the table) return `null`. Don't coerce it to `0` in a cost rollup.

package/base.js

@@ -25,6 +25,22 @@ const DEFAULT_THINKING_CONFIG = {
 
 const DEFAULT_MAX_OUTPUT_TOKENS = 50_000;
 
+/**
+ * Effort levels accepted by the cross-package `effort` option.
+ * Gemini's wire field is `thinkingConfig.thinkingLevel`, which accepts
+ * minimal/low/medium/high. `xhigh` and `max` exist on ak-claude only and are
+ * clamped to `high` so the same config object works against both packages.
+ */
+const EFFORT_LEVELS = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+const EFFORT_TO_THINKING_LEVEL = {
+	minimal: 'minimal',
+	low: 'low',
+	medium: 'medium',
+	high: 'high',
+	xhigh: 'high',
+	max: 'high'
+};
+
 /** Models that support thinking features. Image / live / tts variants intentionally excluded. */
 const THINKING_SUPPORTED_MODELS = [
 	/^gemini-3(\.\d+)?-pro(-preview)?$/,
@@ -36,33 +52,56 @@ const THINKING_SUPPORTED_MODELS = [
 	/^gemini-2\.0-flash$/
 ];
 
+/** Date the pricing table below was last verified against Google's pricing page. */
+const MODEL_PRICING_AS_OF = '2026-07-28';
+
+/** Context-window size at which tiered models switch to their higher rate. */
+const TIER_THRESHOLD = 200_000;
+
 /**
- * Model pricing per million tokens (Paid Tier Standard, base rate, as of July 2026).
+ * Model pricing per million tokens (Paid Tier Standard, base rate, as of MODEL_PRICING_AS_OF).
  * Source: https://ai.google.dev/gemini-api/docs/pricing
  *
+ * Fields:
+ * - `input` / `output` — standard per-1M rates (≤200k tier where a model is tiered).
+ * - `cachedInput` — per-1M rate for tokens served from a context cache. Omitted when
+ *   Google does not publish one; computeCost() then falls back to the full `input`
+ *   rate, which OVERSTATES rather than understates cost.
+ * - `inputAbove200k` / `outputAbove200k` / `cachedInputAbove200k` — >200k context tier.
+ *
  * NOTES:
- * - Pro models use tiered pricing (≤200k vs >200k context). Listed rate is ≤200k base tier.
  * - Gemma models (e.g. Gemma 4) are intentionally excluded — they are open models with
  *   no paid per-token tier on the Gemini API (Vertex deployments bill by compute).
  * - Image-output tokens on Nano Banana models bill at $60/M (1.5 Flash Image) or $120/M (3 Pro Image).
  *   Only text-input/text-output rates are modelled here; image-output cost is NOT included in estimateCost().
  * - Audio input is more expensive on most models — listed rate covers text/image/video input.
+ * - Cache STORAGE ($1.00/1M tokens/hour on Flash tiers, $4.50 on Pro) is time-based and
+ *   NOT modelled here — estimatedCost only covers per-token charges.
+ * - A null result from resolvePricing()/computeCost() means UNKNOWN, not free.
  */
 const MODEL_PRICING = {
 	// Gemini 3.x stable
-	'gemini-3.5-flash': { input: 1.50, output: 9.00 },
-	'gemini-3.1-flash-lite': { input: 0.25, output: 1.50 },
+	'gemini-3.6-flash': { input: 1.50, output: 7.50, cachedInput: 0.15 },
+	'gemini-3.5-flash': { input: 1.50, output: 9.00, cachedInput: 0.15 },
+	'gemini-3.5-flash-lite': { input: 0.30, output: 2.50, cachedInput: 0.03 },
+	'gemini-3.1-flash-lite': { input: 0.25, output: 1.50, cachedInput: 0.025 },
 	// Gemini 3.x preview
-	'gemini-3.1-pro-preview': { input: 2.00, output: 12.00 }, // ≤200k tier
+	'gemini-3.1-pro-preview': {
+		input: 2.00, output: 12.00, cachedInput: 0.20,
+		inputAbove200k: 4.00, outputAbove200k: 18.00, cachedInputAbove200k: 0.40
+	},
 	'gemini-3-pro-preview': { input: 2.00, output: 12.00 },   // ≤200k tier; launch rate (superseded by 3.1, off the pricing page)
 	'gemini-3-flash-preview': { input: 0.50, output: 3.00 },
-	'gemini-3.1-flash-lite-preview': { input: 0.25, output: 1.50 },
+	'gemini-3.1-flash-lite-preview': { input: 0.25, output: 1.50, cachedInput: 0.025 },
 	'gemini-3.1-flash-image-preview': { input: 0.50, output: 3.00 }, // text-only; image-output is $60/M
 	'gemini-3-pro-image-preview': { input: 2.00, output: 12.00 },   // text-only; image-output is $120/M
 	// Gemini 2.5 stable
-	'gemini-2.5-flash': { input: 0.30, output: 2.50 },
-	'gemini-2.5-flash-lite': { input: 0.10, output: 0.40 },
-	'gemini-2.5-pro': { input: 1.25, output: 10.00 }, // ≤200k tier
+	'gemini-2.5-flash': { input: 0.30, output: 3.00, cachedInput: 0.05 },
+	'gemini-2.5-flash-lite': { input: 0.10, output: 0.40, cachedInput: 0.01 },
+	'gemini-2.5-pro': {
+		input: 1.25, output: 10.00, cachedInput: 0.125,
+		inputAbove200k: 2.50, outputAbove200k: 15.00, cachedInputAbove200k: 0.25
+	},
 	'gemini-2.5-flash-image': { input: 0.30, output: 0 }, // image-output is ~$0.039/image (1290 tokens)
 	// Deprecated but kept for back-compat (shut down June 2026)
 	'gemini-2.0-flash': { input: 0.10, output: 0.40 },
@@ -76,25 +115,44 @@ const MODEL_PRICING = {
  * Google publishes floating `-latest` aliases that resolve server-side to a
  * concrete model; they never appear in MODEL_PRICING directly. Map them to the
  * canonical id whose rate they currently bill at so estimatedCost can resolve.
- * Revisit when Google rotates what an alias points to.
+ *
+ * These go stale whenever Google rotates an alias. Prefer the model id the API
+ * ECHOES (`response.modelVersion`) over the alias you requested — `_estimatedCost`
+ * already does this, and alias resolution is logged at debug level.
  */
 const MODEL_ALIASES = {
-	'gemini-flash-latest': 'gemini-3.5-flash',
+	'gemini-flash-latest': 'gemini-3.6-flash',
 	'gemini-pro-latest': 'gemini-3.1-pro-preview',
-	'gemini-flash-lite-latest': 'gemini-3.1-flash-lite'
+	'gemini-flash-lite-latest': 'gemini-3.5-flash-lite'
 };
 
 /**
  * Resolves pricing for a model id, following `-latest` aliases.
+ * A null result means pricing is UNKNOWN, not free.
  * @param {string|null|undefined} modelId
- * @returns {{ input: number, output: number }|null} Pricing, or null if unknown.
+ * @returns {{ input: number, output: number, cachedInput?: number, inputAbove200k?: number, outputAbove200k?: number, cachedInputAbove200k?: number, tierThreshold: number, asOf: string }|null}
  */
 function resolvePricing(modelId) {
+	const entry = _lookupPricing(modelId);
+	if (!entry) return null;
+	return { ...entry, tierThreshold: TIER_THRESHOLD, asOf: MODEL_PRICING_AS_OF };
+}
+
+/**
+ * Raw table lookup with alias + pinned-build fallback. No asOf/tier decoration.
+ * @param {string|null|undefined} modelId
+ * @returns {any|null}
+ * @private
+ */
+function _lookupPricing(modelId) {
 	if (!modelId) return null;
 	const tryKey = (id) => {
 		if (MODEL_PRICING[id]) return MODEL_PRICING[id];
 		const alias = MODEL_ALIASES[id];
-		if (alias && MODEL_PRICING[alias]) return MODEL_PRICING[alias];
+		if (alias && MODEL_PRICING[alias]) {
+			log.debug(`Pricing: alias "${id}" resolved to "${alias}". If Google has rotated this alias the rate may be wrong — prefer the echoed modelVersion.`);
+			return MODEL_PRICING[alias];
+		}
 		return null;
 	};
 	let hit = tryKey(modelId);
@@ -116,20 +174,44 @@ function resolvePricing(modelId) {
 /**
  * Computes estimated USD cost from token counts using MODEL_PRICING.
  * Thinking ("thoughts") tokens are billed at the output rate.
+ *
+ * IMPORTANT: Gemini's `promptTokenCount` INCLUDES `cachedContentTokenCount`, so
+ * cached tokens are SUBTRACTED from promptTokens and re-billed at the discounted
+ * cached rate. (ak-claude is the opposite — Anthropic's `input_tokens` excludes
+ * cache tokens and they are added on top. Do not "unify" these.)
+ *
+ * When a model has no published `cachedInput` rate, cached tokens bill at the full
+ * input rate — an overestimate, never an underestimate.
+ *
+ * Cache STORAGE (per token-hour) is not modelled.
+ *
  * @param {string|null|undefined} modelId
- * @param {number} promptTokens
+ * @param {number} promptTokens - Total prompt tokens as reported by the API (INCLUDES cached tokens)
  * @param {number} responseTokens
  * @param {number} [thoughtsTokens=0] - Thinking tokens (billed at output rate)
- * @returns {number|null} Cost in USD, or null when pricing is unknown.
+ * @param {number} [cachedTokens=0] - Tokens served from a context cache (subset of promptTokens)
+ * @returns {number|null} Cost in USD, or null when pricing is UNKNOWN (not free).
  */
-function computeCost(modelId, promptTokens, responseTokens, thoughtsTokens = 0) {
+function computeCost(modelId, promptTokens, responseTokens, thoughtsTokens = 0, cachedTokens = 0) {
 	const pricing = resolvePricing(modelId);
 	if (!pricing) return null;
-	return (promptTokens / 1_000_000) * pricing.input
-		+ ((responseTokens + thoughtsTokens) / 1_000_000) * pricing.output;
+
+	const above = (promptTokens || 0) > TIER_THRESHOLD;
+	const inputRate = (above && pricing.inputAbove200k) || pricing.input;
+	const outputRate = (above && pricing.outputAbove200k) || pricing.output;
+	const cachedRate = above
+		? (pricing.cachedInputAbove200k ?? pricing.cachedInput ?? inputRate)
+		: (pricing.cachedInput ?? inputRate);
+
+	const cached = Math.max(0, Math.min(cachedTokens || 0, promptTokens || 0));
+	const billablePrompt = Math.max(0, (promptTokens || 0) - cached);
+
+	return (billablePrompt / 1_000_000) * inputRate
+		+ (cached / 1_000_000) * cachedRate
+		+ (((responseTokens || 0) + (thoughtsTokens || 0)) / 1_000_000) * outputRate;
 }
 
-export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, MODEL_ALIASES, DEFAULT_MAX_OUTPUT_TOKENS, resolvePricing, computeCost };
+export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, MODEL_PRICING_AS_OF, MODEL_ALIASES, DEFAULT_MAX_OUTPUT_TOKENS, EFFORT_LEVELS, resolvePricing, computeCost };
 
 // ── BaseGemini Class ─────────────────────────────────────────────────────────
 
@@ -251,6 +333,9 @@ class BaseGemini {
 		}
 
 		// ── Thinking Config ──
+		// `effort` is the cross-package option (same name in ak-claude); it maps to
+		// Gemini's `thinkingConfig.thinkingLevel`.
+		this.effort = this._normalizeEffort(options.effort);
 		this._configureThinking(options.thinkingConfig);
 
 		// ── GenAI Client ──
@@ -272,6 +357,8 @@ class BaseGemini {
 		this._cumulativeUsage = {
 			promptTokens: 0,
 			responseTokens: 0,
+			thoughtsTokens: 0,
+			cachedTokens: 0,
 			totalTokens: 0,
 			attempts: 0
 		};
@@ -384,7 +471,7 @@ class BaseGemini {
 		}
 		this.chatSession = this._createChatSession([]);
 		this.lastResponseMetadata = null;
-		this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 0 };
+		this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, thoughtsTokens: 0, cachedTokens: 0, totalTokens: 0, attempts: 0 };
 		log.debug(`${this.constructor.name}: Conversation history cleared.`);
 	}
 
@@ -487,12 +574,15 @@ class BaseGemini {
 		const promptTokens = response.usageMetadata?.promptTokenCount || 0;
 		const responseTokens = response.usageMetadata?.candidatesTokenCount || 0;
 		const thoughtsTokens = response.usageMetadata?.thoughtsTokenCount || 0;
+		// NB: promptTokenCount INCLUDES cachedContentTokenCount — see computeCost().
+		const cachedTokens = response.usageMetadata?.cachedContentTokenCount || 0;
 		this.lastResponseMetadata = {
 			modelVersion: response.modelVersion || null,
 			requestedModel: this.modelName,
 			promptTokens,
 			responseTokens,
 			thoughtsTokens,
+			cachedTokens,
 			// totalTokenCount includes thoughts; fall back to summing the parts.
 			totalTokens: response.usageMetadata?.totalTokenCount || (promptTokens + responseTokens + thoughtsTokens),
 			timestamp: Date.now(),
@@ -514,18 +604,24 @@ class BaseGemini {
 		if (!this.lastResponseMetadata) return null;
 
 		const meta = this.lastResponseMetadata;
-		const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, thoughtsTokens: 0, attempts: 1 };
+		const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, thoughtsTokens: 0, cachedTokens: 0, attempts: 1 };
 		const useCumulative = cumulative.attempts > 0;
 
 		const promptTokens = useCumulative ? cumulative.promptTokens : meta.promptTokens;
 		const responseTokens = useCumulative ? cumulative.responseTokens : meta.responseTokens;
 		const thoughtsTokens = useCumulative ? (cumulative.thoughtsTokens || 0) : (meta.thoughtsTokens || 0);
 		const totalTokens = useCumulative ? cumulative.totalTokens : meta.totalTokens;
+		// Cached tokens accumulate across retries when tracked; otherwise fall back
+		// to the last response's value (single-call classes).
+		const cachedTokens = useCumulative && cumulative.cachedTokens !== undefined
+			? cumulative.cachedTokens
+			: (meta.cachedTokens || 0);
 
 		return {
 			promptTokens,
 			responseTokens,
 			thoughtsTokens,
+			cachedTokens,
 			totalTokens,
 			attempts: useCumulative ? cumulative.attempts : 1,
 			modelVersion: meta.modelVersion,
@@ -533,7 +629,7 @@ class BaseGemini {
 			timestamp: meta.timestamp,
 			groundingMetadata: meta.groundingMetadata || null,
 			modelStatus: meta.modelStatus || null,
-			estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens)
+			estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
 		};
 	}
 
@@ -544,12 +640,13 @@ class BaseGemini {
 	 * @param {number} promptTokens
 	 * @param {number} responseTokens
 	 * @param {number} [thoughtsTokens=0]
+	 * @param {number} [cachedTokens=0] - Cached-content tokens (a SUBSET of promptTokens)
 	 * @returns {number|null}
 	 * @protected
 	 */
-	_estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens = 0) {
-		return computeCost(modelVersion, promptTokens, responseTokens, thoughtsTokens)
-			?? computeCost(this.modelName, promptTokens, responseTokens, thoughtsTokens);
+	_estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens = 0, cachedTokens = 0) {
+		return computeCost(modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
+			?? computeCost(this.modelName, promptTokens, responseTokens, thoughtsTokens, cachedTokens);
 	}
 
 	/**
@@ -567,12 +664,14 @@ class BaseGemini {
 		const promptTokens = response?.usageMetadata?.promptTokenCount || 0;
 		const responseTokens = response?.usageMetadata?.candidatesTokenCount || 0;
 		const thoughtsTokens = response?.usageMetadata?.thoughtsTokenCount || 0;
+		const cachedTokens = response?.usageMetadata?.cachedContentTokenCount || 0;
 		const totalTokens = response?.usageMetadata?.totalTokenCount || (promptTokens + responseTokens + thoughtsTokens);
 		const modelVersion = response?.modelVersion || null;
 		return {
 			promptTokens,
 			responseTokens,
 			thoughtsTokens,
+			cachedTokens,
 			totalTokens,
 			attempts,
 			modelVersion,
@@ -580,7 +679,7 @@ class BaseGemini {
 			timestamp: Date.now(),
 			groundingMetadata: response?.candidates?.[0]?.groundingMetadata || null,
 			modelStatus: response?.modelStatus || null,
-			estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens)
+			estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
 		};
 	}
 
@@ -819,7 +918,7 @@ class BaseGemini {
 	_configureThinking(thinkingConfig) {
 		const modelSupportsThinking = THINKING_SUPPORTED_MODELS.some(p => p.test(this.modelName));
 
-		if (thinkingConfig === undefined) return;
+		if (thinkingConfig === undefined && this.effort === null) return;
 
 		if (thinkingConfig === null) {
 			delete this.chatConfig.thinkingConfig;
@@ -828,17 +927,47 @@ class BaseGemini {
 		}
 
 		if (!modelSupportsThinking) {
-			log.warn(`Model ${this.modelName} does not support thinking features. Ignoring thinkingConfig.`);
+			log.warn(`Model ${this.modelName} does not support thinking features. Ignoring thinkingConfig/effort.`);
 			return;
 		}
 
-		const config = { ...DEFAULT_THINKING_CONFIG, ...thinkingConfig };
-		if (thinkingConfig.thinkingLevel !== undefined) {
+		const config = { ...DEFAULT_THINKING_CONFIG, ...(thinkingConfig || {}) };
+
+		// `effort` wins over an explicit thinkingLevel/thinkingBudget — it is the
+		// cross-package knob and is set deliberately.
+		if (this.effort !== null) {
+			const level = EFFORT_TO_THINKING_LEVEL[this.effort];
+			if (level !== this.effort) {
+				log.debug(`Effort '${this.effort}' has no Gemini equivalent; using thinkingLevel '${level}'.`);
+			}
+			config.thinkingLevel = level;
+		}
+
+		// thinkingLevel and thinkingBudget are mutually exclusive on the wire.
+		if (config.thinkingLevel !== undefined) {
 			delete config.thinkingBudget;
 		}
+
 		this.chatConfig.thinkingConfig = config;
 		log.debug(`Thinking config applied: ${JSON.stringify(config)}`);
 	}
+
+	/**
+	 * Validates the cross-package `effort` option.
+	 * Throws rather than warns: this runs in the constructor before log levels are
+	 * finalized, so a warning could be swallowed.
+	 * @param {string|null|undefined} effort
+	 * @returns {'minimal'|'low'|'medium'|'high'|'xhigh'|'max'|null}
+	 * @protected
+	 */
+	_normalizeEffort(effort) {
+		if (effort === undefined || effort === null) return null;
+		const level = String(effort).toLowerCase();
+		if (!EFFORT_LEVELS.includes(level)) {
+			throw new Error(`Invalid effort "${effort}". Expected one of: ${EFFORT_LEVELS.join(', ')}.`);
+		}
+		return /** @type {any} */ (level);
+	}
 }
 
 export default BaseGemini;

package/chat.js

@@ -87,6 +87,8 @@ class Chat extends BaseGemini {
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};

package/code-agent.js

@@ -922,6 +922,8 @@ ${lang.codeRules}
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};

package/image-generator.js

@@ -114,6 +114,7 @@ export default class ImageGenerator extends BaseGemini {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
 			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};

package/index.cjs

@@ -32,12 +32,14 @@ __export(index_exports, {
   BaseGemini: () => base_default,
   Chat: () => chat_default,
   CodeAgent: () => code_agent_default,
+  EFFORT_LEVELS: () => EFFORT_LEVELS,
   Embedding: () => Embedding,
   HarmBlockThreshold: () => import_genai2.HarmBlockThreshold,
   HarmCategory: () => import_genai2.HarmCategory,
   ImageGenerator: () => ImageGenerator,
   MODEL_ALIASES: () => MODEL_ALIASES,
   MODEL_PRICING: () => MODEL_PRICING,
+  MODEL_PRICING_AS_OF: () => MODEL_PRICING_AS_OF,
   Message: () => message_default,
   RagAgent: () => rag_agent_default,
   ThinkingLevel: () => import_genai2.ThinkingLevel,
@@ -400,6 +402,15 @@ var DEFAULT_THINKING_CONFIG = {
   thinkingBudget: 0
 };
 var DEFAULT_MAX_OUTPUT_TOKENS = 5e4;
+var EFFORT_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"];
+var EFFORT_TO_THINKING_LEVEL = {
+  minimal: "minimal",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "high",
+  max: "high"
+};
 var THINKING_SUPPORTED_MODELS = [
   /^gemini-3(\.\d+)?-pro(-preview)?$/,
   /^gemini-3(\.\d+)?-flash(-preview)?$/,
@@ -409,26 +420,42 @@ var THINKING_SUPPORTED_MODELS = [
   /^gemini-2\.5-flash-lite(-preview)?$/,
   /^gemini-2\.0-flash$/
 ];
+var MODEL_PRICING_AS_OF = "2026-07-28";
+var TIER_THRESHOLD = 2e5;
 var MODEL_PRICING = {
   // Gemini 3.x stable
-  "gemini-3.5-flash": { input: 1.5, output: 9 },
-  "gemini-3.1-flash-lite": { input: 0.25, output: 1.5 },
+  "gemini-3.6-flash": { input: 1.5, output: 7.5, cachedInput: 0.15 },
+  "gemini-3.5-flash": { input: 1.5, output: 9, cachedInput: 0.15 },
+  "gemini-3.5-flash-lite": { input: 0.3, output: 2.5, cachedInput: 0.03 },
+  "gemini-3.1-flash-lite": { input: 0.25, output: 1.5, cachedInput: 0.025 },
   // Gemini 3.x preview
-  "gemini-3.1-pro-preview": { input: 2, output: 12 },
-  // ≤200k tier
+  "gemini-3.1-pro-preview": {
+    input: 2,
+    output: 12,
+    cachedInput: 0.2,
+    inputAbove200k: 4,
+    outputAbove200k: 18,
+    cachedInputAbove200k: 0.4
+  },
   "gemini-3-pro-preview": { input: 2, output: 12 },
   // ≤200k tier; launch rate (superseded by 3.1, off the pricing page)
   "gemini-3-flash-preview": { input: 0.5, output: 3 },
-  "gemini-3.1-flash-lite-preview": { input: 0.25, output: 1.5 },
+  "gemini-3.1-flash-lite-preview": { input: 0.25, output: 1.5, cachedInput: 0.025 },
   "gemini-3.1-flash-image-preview": { input: 0.5, output: 3 },
   // text-only; image-output is $60/M
   "gemini-3-pro-image-preview": { input: 2, output: 12 },
   // text-only; image-output is $120/M
   // Gemini 2.5 stable
-  "gemini-2.5-flash": { input: 0.3, output: 2.5 },
-  "gemini-2.5-flash-lite": { input: 0.1, output: 0.4 },
-  "gemini-2.5-pro": { input: 1.25, output: 10 },
-  // ≤200k tier
+  "gemini-2.5-flash": { input: 0.3, output: 3, cachedInput: 0.05 },
+  "gemini-2.5-flash-lite": { input: 0.1, output: 0.4, cachedInput: 0.01 },
+  "gemini-2.5-pro": {
+    input: 1.25,
+    output: 10,
+    cachedInput: 0.125,
+    inputAbove200k: 2.5,
+    outputAbove200k: 15,
+    cachedInputAbove200k: 0.25
+  },
   "gemini-2.5-flash-image": { input: 0.3, output: 0 },
   // image-output is ~$0.039/image (1290 tokens)
   // Deprecated but kept for back-compat (shut down June 2026)
@@ -438,16 +465,24 @@ var MODEL_PRICING = {
   "gemini-embedding-001": { input: 0.15, output: 0 }
 };
 var MODEL_ALIASES = {
-  "gemini-flash-latest": "gemini-3.5-flash",
+  "gemini-flash-latest": "gemini-3.6-flash",
   "gemini-pro-latest": "gemini-3.1-pro-preview",
-  "gemini-flash-lite-latest": "gemini-3.1-flash-lite"
+  "gemini-flash-lite-latest": "gemini-3.5-flash-lite"
 };
 function resolvePricing(modelId) {
+  const entry = _lookupPricing(modelId);
+  if (!entry) return null;
+  return { ...entry, tierThreshold: TIER_THRESHOLD, asOf: MODEL_PRICING_AS_OF };
+}
+function _lookupPricing(modelId) {
   if (!modelId) return null;
   const tryKey = (id) => {
     if (MODEL_PRICING[id]) return MODEL_PRICING[id];
     const alias = MODEL_ALIASES[id];
-    if (alias && MODEL_PRICING[alias]) return MODEL_PRICING[alias];
+    if (alias && MODEL_PRICING[alias]) {
+      logger_default.debug(`Pricing: alias "${id}" resolved to "${alias}". If Google has rotated this alias the rate may be wrong \u2014 prefer the echoed modelVersion.`);
+      return MODEL_PRICING[alias];
+    }
     return null;
   };
   let hit = tryKey(modelId);
@@ -462,10 +497,16 @@ function resolvePricing(modelId) {
   }
   return null;
 }
-function computeCost(modelId, promptTokens, responseTokens, thoughtsTokens = 0) {
+function computeCost(modelId, promptTokens, responseTokens, thoughtsTokens = 0, cachedTokens = 0) {
   const pricing = resolvePricing(modelId);
   if (!pricing) return null;
-  return promptTokens / 1e6 * pricing.input + (responseTokens + thoughtsTokens) / 1e6 * pricing.output;
+  const above = (promptTokens || 0) > TIER_THRESHOLD;
+  const inputRate = above && pricing.inputAbove200k || pricing.input;
+  const outputRate = above && pricing.outputAbove200k || pricing.output;
+  const cachedRate = above ? pricing.cachedInputAbove200k ?? pricing.cachedInput ?? inputRate : pricing.cachedInput ?? inputRate;
+  const cached = Math.max(0, Math.min(cachedTokens || 0, promptTokens || 0));
+  const billablePrompt = Math.max(0, (promptTokens || 0) - cached);
+  return billablePrompt / 1e6 * inputRate + cached / 1e6 * cachedRate + ((responseTokens || 0) + (thoughtsTokens || 0)) / 1e6 * outputRate;
 }
 var BaseGemini = class {
   /**
@@ -530,6 +571,7 @@ var BaseGemini = class {
     } else {
       this.chatConfig.maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS;
     }
+    this.effort = this._normalizeEffort(options.effort);
     this._configureThinking(options.thinkingConfig);
     const clientOptions = this.vertexai ? {
       vertexai: true,
@@ -544,6 +586,8 @@ var BaseGemini = class {
     this._cumulativeUsage = {
       promptTokens: 0,
       responseTokens: 0,
+      thoughtsTokens: 0,
+      cachedTokens: 0,
       totalTokens: 0,
       attempts: 0
     };
@@ -640,7 +684,7 @@ var BaseGemini = class {
     }
     this.chatSession = this._createChatSession([]);
     this.lastResponseMetadata = null;
-    this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 0 };
+    this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, thoughtsTokens: 0, cachedTokens: 0, totalTokens: 0, attempts: 0 };
     logger_default.debug(`${this.constructor.name}: Conversation history cleared.`);
   }
   // ── Few-Shot Seeding ─────────────────────────────────────────────────────
@@ -729,12 +773,14 @@ ${contextText}
     const promptTokens = response.usageMetadata?.promptTokenCount || 0;
     const responseTokens = response.usageMetadata?.candidatesTokenCount || 0;
     const thoughtsTokens = response.usageMetadata?.thoughtsTokenCount || 0;
+    const cachedTokens = response.usageMetadata?.cachedContentTokenCount || 0;
     this.lastResponseMetadata = {
       modelVersion: response.modelVersion || null,
       requestedModel: this.modelName,
       promptTokens,
       responseTokens,
       thoughtsTokens,
+      cachedTokens,
       // totalTokenCount includes thoughts; fall back to summing the parts.
       totalTokens: response.usageMetadata?.totalTokenCount || promptTokens + responseTokens + thoughtsTokens,
       timestamp: Date.now(),
@@ -754,16 +800,18 @@ ${contextText}
   getLastUsage() {
     if (!this.lastResponseMetadata) return null;
     const meta = this.lastResponseMetadata;
-    const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, thoughtsTokens: 0, attempts: 1 };
+    const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 0, thoughtsTokens: 0, cachedTokens: 0, attempts: 1 };
     const useCumulative = cumulative.attempts > 0;
     const promptTokens = useCumulative ? cumulative.promptTokens : meta.promptTokens;
     const responseTokens = useCumulative ? cumulative.responseTokens : meta.responseTokens;
     const thoughtsTokens = useCumulative ? cumulative.thoughtsTokens || 0 : meta.thoughtsTokens || 0;
     const totalTokens = useCumulative ? cumulative.totalTokens : meta.totalTokens;
+    const cachedTokens = useCumulative && cumulative.cachedTokens !== void 0 ? cumulative.cachedTokens : meta.cachedTokens || 0;
     return {
       promptTokens,
       responseTokens,
       thoughtsTokens,
+      cachedTokens,
       totalTokens,
       attempts: useCumulative ? cumulative.attempts : 1,
       modelVersion: meta.modelVersion,
@@ -771,7 +819,7 @@ ${contextText}
       timestamp: meta.timestamp,
       groundingMetadata: meta.groundingMetadata || null,
       modelStatus: meta.modelStatus || null,
-      estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens)
+      estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
     };
   }
   /**
@@ -781,11 +829,12 @@ ${contextText}
    * @param {number} promptTokens
    * @param {number} responseTokens
    * @param {number} [thoughtsTokens=0]
+   * @param {number} [cachedTokens=0] - Cached-content tokens (a SUBSET of promptTokens)
    * @returns {number|null}
    * @protected
    */
-  _estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens = 0) {
-    return computeCost(modelVersion, promptTokens, responseTokens, thoughtsTokens) ?? computeCost(this.modelName, promptTokens, responseTokens, thoughtsTokens);
+  _estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens = 0, cachedTokens = 0) {
+    return computeCost(modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens) ?? computeCost(this.modelName, promptTokens, responseTokens, thoughtsTokens, cachedTokens);
   }
   /**
    * Builds a usage object directly from a single API response, WITHOUT reading
@@ -802,12 +851,14 @@ ${contextText}
     const promptTokens = response?.usageMetadata?.promptTokenCount || 0;
     const responseTokens = response?.usageMetadata?.candidatesTokenCount || 0;
     const thoughtsTokens = response?.usageMetadata?.thoughtsTokenCount || 0;
+    const cachedTokens = response?.usageMetadata?.cachedContentTokenCount || 0;
     const totalTokens = response?.usageMetadata?.totalTokenCount || promptTokens + responseTokens + thoughtsTokens;
     const modelVersion = response?.modelVersion || null;
     return {
       promptTokens,
       responseTokens,
       thoughtsTokens,
+      cachedTokens,
       totalTokens,
       attempts,
       modelVersion,
@@ -815,7 +866,7 @@ ${contextText}
       timestamp: Date.now(),
       groundingMetadata: response?.candidates?.[0]?.groundingMetadata || null,
       modelStatus: response?.modelStatus || null,
-      estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens)
+      estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
     };
   }
   // ── Token Estimation ─────────────────────────────────────────────────────
@@ -1020,23 +1071,49 @@ ${contextText}
    */
   _configureThinking(thinkingConfig) {
     const modelSupportsThinking = THINKING_SUPPORTED_MODELS.some((p) => p.test(this.modelName));
-    if (thinkingConfig === void 0) return;
+    if (thinkingConfig === void 0 && this.effort === null) return;
     if (thinkingConfig === null) {
       delete this.chatConfig.thinkingConfig;
       logger_default.debug(`thinkingConfig set to null - removed from configuration`);
       return;
     }
     if (!modelSupportsThinking) {
-      logger_default.warn(`Model ${this.modelName} does not support thinking features. Ignoring thinkingConfig.`);
+      logger_default.warn(`Model ${this.modelName} does not support thinking features. Ignoring thinkingConfig/effort.`);
       return;
     }
-    const config = { ...DEFAULT_THINKING_CONFIG, ...thinkingConfig };
-    if (thinkingConfig.thinkingLevel !== void 0) {
+    const config = { ...DEFAULT_THINKING_CONFIG, ...thinkingConfig || {} };
+    if (this.effort !== null) {
+      const level = EFFORT_TO_THINKING_LEVEL[this.effort];
+      if (level !== this.effort) {
+        logger_default.debug(`Effort '${this.effort}' has no Gemini equivalent; using thinkingLevel '${level}'.`);
+      }
+      config.thinkingLevel = level;
+    }
+    if (config.thinkingLevel !== void 0) {
       delete config.thinkingBudget;
     }
     this.chatConfig.thinkingConfig = config;
     logger_default.debug(`Thinking config applied: ${JSON.stringify(config)}`);
   }
+  /**
+   * Validates the cross-package `effort` option.
+   * Throws rather than warns: this runs in the constructor before log levels are
+   * finalized, so a warning could be swallowed.
+   * @param {string|null|undefined} effort
+   * @returns {'minimal'|'low'|'medium'|'high'|'xhigh'|'max'|null}
+   * @protected
+   */
+  _normalizeEffort(effort) {
+    if (effort === void 0 || effort === null) return null;
+    const level = String(effort).toLowerCase();
+    if (!EFFORT_LEVELS.includes(level)) {
+      throw new Error(`Invalid effort "${effort}". Expected one of: ${EFFORT_LEVELS.join(", ")}.`);
+    }
+    return (
+      /** @type {any} */
+      level
+    );
+  }
 };
 var base_default = BaseGemini;
 
@@ -1168,7 +1245,7 @@ var Transformer = class extends base_default {
     let lastPayload = this._preparePayload(payload);
     const messageOptions = {};
     if (opts.labels) messageOptions.labels = opts.labels;
-    this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 0 };
+    this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, thoughtsTokens: 0, cachedTokens: 0, totalTokens: 0, attempts: 0 };
     let lastError = null;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       try {
@@ -1176,6 +1253,8 @@ var Transformer = class extends base_default {
         if (this.lastResponseMetadata) {
           this._cumulativeUsage.promptTokens += this.lastResponseMetadata.promptTokens || 0;
           this._cumulativeUsage.responseTokens += this.lastResponseMetadata.responseTokens || 0;
+          this._cumulativeUsage.thoughtsTokens += this.lastResponseMetadata.thoughtsTokens || 0;
+          this._cumulativeUsage.cachedTokens += this.lastResponseMetadata.cachedTokens || 0;
           this._cumulativeUsage.totalTokens += this.lastResponseMetadata.totalTokens || 0;
           this._cumulativeUsage.attempts = attempt + 1;
         }
@@ -1311,6 +1390,8 @@ Respond with JSON only \u2013 no comments or explanations.
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -1336,7 +1417,7 @@ Respond with JSON only \u2013 no comments or explanations.
     const exampleHistory = history.slice(0, this.exampleCount || 0);
     this.chatSession = this._createChatSession(exampleHistory);
     this.lastResponseMetadata = null;
-    this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 0 };
+    this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, thoughtsTokens: 0, cachedTokens: 0, totalTokens: 0, attempts: 0 };
     logger_default.debug(`Conversation cleared. Preserved ${exampleHistory.length} example items.`);
   }
   /**
@@ -1435,6 +1516,8 @@ var Chat = class extends base_default {
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -1530,6 +1613,7 @@ var Message = class extends base_default {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
       thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -1687,6 +1771,8 @@ var ToolAgent = class extends base_default {
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -2698,6 +2784,8 @@ ${this.envOverview}`;
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -3016,6 +3104,8 @@ ${serialized}` });
     this._cumulativeUsage = {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
+      thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -3333,6 +3423,7 @@ var ImageGenerator = class extends base_default {
       promptTokens: this.lastResponseMetadata.promptTokens,
       responseTokens: this.lastResponseMetadata.responseTokens,
       thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+      cachedTokens: this.lastResponseMetadata.cachedTokens,
       totalTokens: this.lastResponseMetadata.totalTokens,
       attempts: 1
     };
@@ -3408,12 +3499,14 @@ var index_default = { Transformer: transformer_default, Chat: chat_default, Mess
   BaseGemini,
   Chat,
   CodeAgent,
+  EFFORT_LEVELS,
   Embedding,
   HarmBlockThreshold,
   HarmCategory,
   ImageGenerator,
   MODEL_ALIASES,
   MODEL_PRICING,
+  MODEL_PRICING_AS_OF,
   Message,
   RagAgent,
   ThinkingLevel,

package/index.js

@@ -29,7 +29,7 @@ export { default as RagAgent } from './rag-agent.js';
 export { default as Embedding } from './embedding.js';
 export { default as ImageGenerator } from './image-generator.js';
 export { default as BaseGemini } from './base.js';
-export { MODEL_PRICING, MODEL_ALIASES, resolvePricing, computeCost } from './base.js';
+export { MODEL_PRICING, MODEL_PRICING_AS_OF, MODEL_ALIASES, EFFORT_LEVELS, resolvePricing, computeCost } from './base.js';
 export { default as log } from './logger.js';
 export { ThinkingLevel, HarmCategory, HarmBlockThreshold } from '@google/genai';
 export { extractJSON, attemptJSONRecovery, validateSchema } from './json-helpers.js';

package/message.js

@@ -128,6 +128,7 @@ class Message extends BaseGemini {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
 			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};

package/package.json

@@ -2,7 +2,7 @@
 	"name": "ak-gemini",
 	"author": "ak@mixpanel.com",
 	"description": "AK's Generative AI Helper for doing... everything",
-	"version": "2.5.0",
+	"version": "2.6.0",
 	"main": "index.js",
 	"files": [
 		"index.js",
@@ -20,7 +20,8 @@
 		"types.d.ts",
 		"logger.js",
 		"GUIDE.md",
-		"CHANGELOG.md"
+		"UPGRADING.md",
+    "CHANGELOG.md"
 	],
 	"types": "types.d.ts",
 	"exports": {

package/rag-agent.js

@@ -213,6 +213,8 @@ class RagAgent extends BaseGemini {
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};

package/tool-agent.js

@@ -200,6 +200,8 @@ class ToolAgent extends BaseGemini {
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};

package/transformer.js

@@ -201,7 +201,7 @@ class Transformer extends BaseGemini {
 		if (opts.labels) messageOptions.labels = opts.labels;
 
 		// Reset cumulative usage tracking
-		this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 0 };
+		this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, thoughtsTokens: 0, cachedTokens: 0, totalTokens: 0, attempts: 0 };
 
 		let lastError = null;
 
@@ -215,6 +215,8 @@ class Transformer extends BaseGemini {
 				if (this.lastResponseMetadata) {
 					this._cumulativeUsage.promptTokens += this.lastResponseMetadata.promptTokens || 0;
 					this._cumulativeUsage.responseTokens += this.lastResponseMetadata.responseTokens || 0;
+					this._cumulativeUsage.thoughtsTokens += this.lastResponseMetadata.thoughtsTokens || 0;
+					this._cumulativeUsage.cachedTokens += this.lastResponseMetadata.cachedTokens || 0;
 					this._cumulativeUsage.totalTokens += this.lastResponseMetadata.totalTokens || 0;
 					this._cumulativeUsage.attempts = attempt + 1;
 				}
@@ -389,6 +391,8 @@ Respond with JSON only – no comments or explanations.
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};
@@ -422,7 +426,7 @@ Respond with JSON only – no comments or explanations.
 		this.chatSession = this._createChatSession(exampleHistory);
 
 		this.lastResponseMetadata = null;
-		this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, totalTokens: 0, attempts: 0 };
+		this._cumulativeUsage = { promptTokens: 0, responseTokens: 0, thoughtsTokens: 0, cachedTokens: 0, totalTokens: 0, attempts: 0 };
 
 		log.debug(`Conversation cleared. Preserved ${exampleHistory.length} example items.`);
 	}

package/types.d.ts

@@ -6,11 +6,38 @@ export { ThinkingLevel, HarmCategory, HarmBlockThreshold };
 
 export interface ThinkingConfig {
   includeThoughts?: boolean;
-  /** Token budget for thinking. 0 = disabled, -1 = automatic. */
+  /** Token budget for thinking. 0 = disabled, -1 = automatic. Mutually exclusive with thinkingLevel. */
   thinkingBudget?: number;
   thinkingLevel?: ThinkingLevel;
 }
 
+/**
+ * Cross-package reasoning-effort levels (same option name in ak-claude).
+ * Gemini's wire field is `thinkingConfig.thinkingLevel`; `xhigh` and `max` are
+ * ak-claude-only levels and clamp to `high` here.
+ */
+export type EffortLevel = 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+/** Per-million-token rates for a single model. */
+export interface ModelPricing {
+  input: number;
+  output: number;
+  /** Rate for tokens served from a context cache. Absent when Google publishes none — cost then falls back to `input` (overestimate). */
+  cachedInput?: number;
+  /** >200k-context tier rates, present only on tiered (Pro) models. */
+  inputAbove200k?: number;
+  outputAbove200k?: number;
+  cachedInputAbove200k?: number;
+}
+
+/** ModelPricing decorated with the tier threshold and the table's verification date. */
+export interface ResolvedPricing extends ModelPricing {
+  /** Prompt-token count above which the *Above200k rates apply. */
+  tierThreshold: number;
+  /** ISO date the pricing table was last verified against Google's pricing page. */
+  asOf: string;
+}
+
 export interface SafetySetting {
   category: HarmCategory;
   threshold: HarmBlockThreshold;
@@ -54,6 +81,9 @@ export interface ResponseMetadata {
   requestedModel: string;
   promptTokens: number;
   responseTokens: number;
+  thoughtsTokens?: number;
+  /** Cached-content tokens. A SUBSET of promptTokens, not an addition to it. */
+  cachedTokens?: number;
   totalTokens: number;
   timestamp: number;
   groundingMetadata?: GroundingMetadata | null;
@@ -66,6 +96,14 @@ export interface UsageData {
   responseTokens: number;
   /** CUMULATIVE thinking ("thoughts") tokens; billed at the output rate. Included in totalTokens and estimatedCost. */
   thoughtsTokens?: number;
+  /**
+   * CUMULATIVE cached-content tokens (`usageMetadata.cachedContentTokenCount`).
+   * NOTE: Gemini INCLUDES these in promptTokens — they are a subset, not an
+   * addition. `estimatedCost` subtracts them from promptTokens and re-bills them
+   * at the discounted cached rate. (ak-claude is the opposite: Anthropic's cache
+   * tokens are excluded from input_tokens and added on top.)
+   */
+  cachedTokens?: number;
   /** CUMULATIVE total tokens across all retry attempts (includes thoughtsTokens) */
   totalTokens: number;
   /** Number of attempts (1 = first try success, 2+ = retries needed) */
@@ -78,7 +116,11 @@ export interface UsageData {
   groundingMetadata?: GroundingMetadata | null;
   /** Model lifecycle status from Google (e.g., 'DEPRECATED'). Surfaced from @google/genai 1.47+. */
   modelStatus?: string | null;
-  /** Estimated USD cost from MODEL_PRICING (input+output). null when the model's pricing is unknown. */
+  /**
+   * Estimated USD cost from MODEL_PRICING (input + cached input + output + thoughts).
+   * `null` means the model's pricing is UNKNOWN — it does NOT mean the call was free.
+   * Cache STORAGE (per token-hour) and image-output tokens are not modelled.
+   */
   estimatedCost?: number | null;
 }
 
@@ -149,6 +191,12 @@ export interface BaseGeminiOptions {
   chatConfig?: Partial<ChatConfig>;
   /** Thinking features configuration */
   thinkingConfig?: ThinkingConfig | null;
+  /**
+   * Reasoning effort (cross-package option; same name in ak-claude). Maps to
+   * `thinkingConfig.thinkingLevel` and wins over an explicit thinkingLevel /
+   * thinkingBudget. Throws on an unrecognized level.
+   */
+  effort?: EffortLevel | null;
   /** Maximum output tokens (default: 50000, null removes limit) */
   maxOutputTokens?: number | null;
   /** Sampling temperature (shorthand for chatConfig.temperature; wins over chatConfig) */
@@ -596,6 +644,8 @@ export declare class BaseGemini {
   cachedContent: string | null;
   serviceTier: ServiceTier | null;
   includeServerSideToolInvocations: boolean;
+  /** Normalized `effort` option; null when unset. */
+  effort: EffortLevel | null;
 
   init(force?: boolean): Promise<void>;
   seed(examples?: TransformationExample[], opts?: SeedOptions): Promise<any[]>;
@@ -606,11 +656,14 @@ export declare class BaseGemini {
   estimateCost(nextPayload: Record<string, unknown> | string): Promise<{
     inputTokens: number;
     model: string;
-    pricing: { input: number; output: number } | null;
+    pricing: ResolvedPricing | null;
     estimatedInputCost: number | null;
     note: string;
   }>;
 
+  /** @internal Validates the `effort` option; throws on an unknown level. */
+  protected _normalizeEffort(effort?: string | null): EffortLevel | null;
+
   // Context Caching
   createCache(config?: CacheConfig): Promise<CachedContentInfo>;
   getCache(cacheName: string): Promise<CachedContentInfo>;
@@ -765,13 +818,28 @@ export declare function attemptJSONRecovery(text: string, maxAttempts?: number):
 export declare function validateSchema(data: any, schema: Record<string, any>, path?: string): string[];
 
 /** Per-million-token pricing keyed by model id. */
-export declare const MODEL_PRICING: Record<string, { input: number; output: number }>;
+export declare const MODEL_PRICING: Record<string, ModelPricing>;
+/** ISO date the pricing table was last verified against Google's published rates. */
+export declare const MODEL_PRICING_AS_OF: string;
 /** Floating `-latest` alias → canonical model id, for pricing resolution. */
 export declare const MODEL_ALIASES: Record<string, string>;
-/** Resolves pricing for a model id (follows -latest aliases). null when unknown. */
-export declare function resolvePricing(modelId: string | null | undefined): { input: number; output: number } | null;
-/** Estimated USD cost from token counts. null when the model's pricing is unknown. */
-export declare function computeCost(modelId: string | null | undefined, promptTokens: number, responseTokens: number): number | null;
+/** Valid values for the `effort` option. */
+export declare const EFFORT_LEVELS: readonly EffortLevel[];
+/** Resolves pricing for a model id (follows -latest aliases). `null` means UNKNOWN, not free. */
+export declare function resolvePricing(modelId: string | null | undefined): ResolvedPricing | null;
+/**
+ * Estimated USD cost from token counts. `null` means UNKNOWN, not free.
+ * `cachedTokens` is a SUBSET of `promptTokens` (Gemini includes them) and is
+ * subtracted before billing at the cached rate. Thinking tokens bill at the
+ * output rate. Tier is selected from `promptTokens` vs 200k.
+ */
+export declare function computeCost(
+  modelId: string | null | undefined,
+  promptTokens: number,
+  responseTokens: number,
+  thoughtsTokens?: number,
+  cachedTokens?: number
+): number | null;
 
 declare const _default: {
   Transformer: typeof Transformer;