ak-gemini 2.4.1 → 2.6.0

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 },
@@ -71,7 +110,108 @@ const MODEL_PRICING = {
 	'gemini-embedding-001': { input: 0.15, output: 0 }
 };
 
-export { DEFAULT_SAFETY_SETTINGS, DEFAULT_THINKING_CONFIG, THINKING_SUPPORTED_MODELS, MODEL_PRICING, DEFAULT_MAX_OUTPUT_TOKENS };
+/**
+ * Alias → canonical model id map for pricing resolution.
+ * 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.
+ *
+ * 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.6-flash',
+	'gemini-pro-latest': 'gemini-3.1-pro-preview',
+	'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, 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]) {
+			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);
+	if (hit) return hit;
+	// The API echoes a pinned build in modelVersion (e.g. 'gemini-2.5-flash-001',
+	// 'gemini-3-flash-preview-09-2025') even when you request the bare id. Peel
+	// trailing '-<digits>' groups and retry until a priced id matches.
+	let stripped = modelId;
+	while (true) {
+		const next = stripped.replace(/-\d{2,}$/, '');
+		if (next === stripped) break;
+		stripped = next;
+		hit = tryKey(stripped);
+		if (hit) return hit;
+	}
+	return null;
+}
+
+/**
+ * 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 - Total prompt tokens as reported by the API (INCLUDES cached tokens)
+ * @param {number} responseTokens
+ * @param {number} [thoughtsTokens=0] - Thinking tokens (billed at output rate)
+ * @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, cachedTokens = 0) {
+	const pricing = resolvePricing(modelId);
+	if (!pricing) return null;
+
+	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_PRICING_AS_OF, MODEL_ALIASES, DEFAULT_MAX_OUTPUT_TOKENS, EFFORT_LEVELS, resolvePricing, computeCost };
 
 // ── BaseGemini Class ─────────────────────────────────────────────────────────
 
@@ -193,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 ──
@@ -214,6 +357,8 @@ class BaseGemini {
 		this._cumulativeUsage = {
 			promptTokens: 0,
 			responseTokens: 0,
+			thoughtsTokens: 0,
+			cachedTokens: 0,
 			totalTokens: 0,
 			attempts: 0
 		};
@@ -237,18 +382,28 @@ class BaseGemini {
 		const chatOptions = this._getChatCreateOptions();
 		this.chatSession = this.genAIClient.chats.create(chatOptions);
 
-		if (this.healthCheck) {
-			try {
-				await this._withRetry(() => this.genAIClient.models.list());
-				log.debug(`${this.constructor.name}: API connection successful.`);
-			} catch (e) {
-				throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-			}
-		}
+		await this._healthCheckPing();
 
 		log.debug(`${this.constructor.name}: Chat session initialized.`);
 	}
 
+	/**
+	 * Opt-in connectivity check via `models.list()` — runs only when
+	 * `healthCheck: true`. Fails fast (no exponential backoff): a readiness probe
+	 * should surface a bad config immediately, not after ~30s of 429 retries.
+	 * @returns {Promise<void>}
+	 * @protected
+	 */
+	async _healthCheckPing() {
+		if (!this.healthCheck) return;
+		try {
+			await this.genAIClient.models.list();
+			log.debug(`${this.constructor.name}: API connection successful.`);
+		} catch (e) {
+			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
+		}
+	}
+
 	/**
 	 * Builds the options object for `genAIClient.chats.create()`.
 	 * Override in subclasses to add tools, grounding, etc.
@@ -316,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.`);
 	}
 
@@ -416,12 +571,20 @@ class BaseGemini {
 	 */
 	_captureMetadata(response) {
 		const modelStatus = response?.modelStatus || null;
+		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: response.usageMetadata?.promptTokenCount || 0,
-			responseTokens: response.usageMetadata?.candidatesTokenCount || 0,
-			totalTokens: response.usageMetadata?.totalTokenCount || 0,
+			promptTokens,
+			responseTokens,
+			thoughtsTokens,
+			cachedTokens,
+			// totalTokenCount includes thoughts; fall back to summing the parts.
+			totalTokens: response.usageMetadata?.totalTokenCount || (promptTokens + responseTokens + thoughtsTokens),
 			timestamp: Date.now(),
 			groundingMetadata: response.candidates?.[0]?.groundingMetadata || null,
 			modelStatus
@@ -441,19 +604,82 @@ class BaseGemini {
 		if (!this.lastResponseMetadata) return null;
 
 		const meta = this.lastResponseMetadata;
-		const cumulative = this._cumulativeUsage || { promptTokens: 0, responseTokens: 0, totalTokens: 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: useCumulative ? cumulative.promptTokens : meta.promptTokens,
-			responseTokens: useCumulative ? cumulative.responseTokens : meta.responseTokens,
-			totalTokens: useCumulative ? cumulative.totalTokens : meta.totalTokens,
+			promptTokens,
+			responseTokens,
+			thoughtsTokens,
+			cachedTokens,
+			totalTokens,
 			attempts: useCumulative ? cumulative.attempts : 1,
 			modelVersion: meta.modelVersion,
 			requestedModel: meta.requestedModel,
 			timestamp: meta.timestamp,
 			groundingMetadata: meta.groundingMetadata || null,
-			modelStatus: meta.modelStatus || null
+			modelStatus: meta.modelStatus || null,
+			estimatedCost: this._estimatedCost(meta.modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
+		};
+	}
+
+	/**
+	 * Estimated USD cost, preferring the model id the API echoed (`modelVersion`)
+	 * and falling back to the requested model when that build isn't priced.
+	 * @param {string|null|undefined} modelVersion
+	 * @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, 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
+	 * mutable instance state (`lastResponseMetadata`/`_cumulativeUsage`). Safe to
+	 * call under concurrent send() calls on a shared instance — unlike
+	 * getLastUsage(), which reflects whichever call most recently mutated the
+	 * instance and can cross-talk between concurrent sends.
+	 * @param {Object} response - A single generateContent() response
+	 * @param {number} [attempts=1] - Attempts this call consumed
+	 * @returns {UsageData}
+	 * @protected
+	 */
+	_usageFromResponse(response, attempts = 1) {
+		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,
+			requestedModel: this.modelName,
+			timestamp: Date.now(),
+			groundingMetadata: response?.candidates?.[0]?.groundingMetadata || null,
+			modelStatus: response?.modelStatus || null,
+			estimatedCost: this._estimatedCost(modelVersion, promptTokens, responseTokens, thoughtsTokens, cachedTokens)
 		};
 	}
 
@@ -500,14 +726,16 @@ class BaseGemini {
 	 */
 	async estimateCost(nextPayload) {
 		const tokenInfo = await this.estimate(nextPayload);
-		const pricing = MODEL_PRICING[this.modelName] || { input: 0, output: 0 };
+		const pricing = resolvePricing(this.modelName);
 
 		return {
 			inputTokens: tokenInfo.inputTokens,
 			model: this.modelName,
 			pricing: pricing,
-			estimatedInputCost: (tokenInfo.inputTokens / 1_000_000) * pricing.input,
-			note: 'Cost is for input tokens only; output cost depends on response length'
+			estimatedInputCost: pricing ? (tokenInfo.inputTokens / 1_000_000) * pricing.input : null,
+			note: pricing
+				? 'Cost is for input tokens only; output cost depends on response length'
+				: `No pricing known for model "${this.modelName}"; estimatedInputCost is null`
 		};
 	}
 
@@ -690,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;
@@ -699,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/embedding.js

@@ -54,12 +54,10 @@ export default class Embedding extends BaseGemini {
 
 		log.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
 
-		try {
-			await this.genAIClient.models.list();
-			log.debug(`${this.constructor.name}: API connection successful.`);
-		} catch (e) {
-			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-		}
+		// Connectivity check is opt-in (healthCheck: true) — avoids an extra
+		// round-trip and the models.list() IAM surface. First embed() is a fine
+		// error signal on its own.
+		await this._healthCheckPing();
 
 		this._initialized = true;
 		log.debug(`${this.constructor.name}: Initialized (stateless mode).`);

package/image-generator.js

@@ -52,12 +52,10 @@ export default class ImageGenerator extends BaseGemini {
 
 		log.debug(`Initializing ${this.constructor.name} with model: ${this.modelName}...`);
 
-		try {
-			await this.genAIClient.models.list();
-			log.debug(`${this.constructor.name}: API connection successful.`);
-		} catch (e) {
-			throw new Error(`${this.constructor.name} initialization failed: ${e.message}`);
-		}
+		// Connectivity check is opt-in (healthCheck: true) — avoids an extra
+		// round-trip and the models.list() IAM surface. First generate() is a fine
+		// error signal on its own.
+		await this._healthCheckPing();
 
 		this._initialized = true;
 	}
@@ -108,10 +106,15 @@ export default class ImageGenerator extends BaseGemini {
 			config: this._buildConfig(opts)
 		}));
 
+		// Per-call usage computed synchronously from THIS response (concurrency-safe).
+		const usage = this._usageFromResponse(result);
+
 		this._captureMetadata(result);
 		this._cumulativeUsage = {
 			promptTokens: this.lastResponseMetadata.promptTokens,
 			responseTokens: this.lastResponseMetadata.responseTokens,
+			thoughtsTokens: this.lastResponseMetadata.thoughtsTokens,
+			cachedTokens: this.lastResponseMetadata.cachedTokens,
 			totalTokens: this.lastResponseMetadata.totalTokens,
 			attempts: 1
 		};
@@ -134,7 +137,7 @@ export default class ImageGenerator extends BaseGemini {
 			log.warn('ImageGenerator: no images returned. Check prompt or safety filters.');
 		}
 
-		return { images, text: text || null, usage: this.getLastUsage() };
+		return { images, text: text || null, usage };
 	}
 
 	/**