@warlock.js/ai-google 5.30.0 → 5.32.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ All notable changes to `@warlock.js/ai-google` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.32.0 - 2026-10-18
+
+### Changed
+
+- Pin the package development compiler to TypeScript 7.0.2 and use explicit Node types and source roots with supported module resolution.
+
+### Fixed
+
+- Gemini Developer API token counting sends the full `generateContentRequest`, including system instructions, tools and generation settings, through the existing SDK transport with cancellation and error mapping. Vertex counting is unchanged; unsupported cached-content counts carry the typed signal used by `countInputTokens` to estimate.
+
+### Added
+
+- Preserve raw candidate grounding metadata and normalize unique nonempty search queries in completions and streams. Export opt-in Gemini 3+ request prices as `GOOGLE_SERVER_TOOL_PRICING`; document older models’ per-prompt billing.
+
+## 5.31.0 - 2026-10-18
+
+### Fixed
+
+- Provider body options merge plain-object fields one level deep, preserving neutral reasoning, generation and structured-output settings unless the caller overrides their keys.
+- Consecutive messages that map to the same Gemini role are sent as one content with their parts in order. The results of parallel tool calls now travel as a single `user` turn of `functionResponse` parts in call order instead of one turn per result, and an agent compaction summary next to a same-role turn merges into it, so requests keep alternating `user` and `model` turns. Each `functionCall` keeps its own `thoughtSignature`, and `countTokens()` counts the same contents.
+
+### Added
+
+- Usage is marked `inputIncludesCache: true` (`promptTokenCount` includes cached content), and `complete()` / the streaming `done` chunk attach `usage.cost` when priced.
+- A built-in list price for `gemini-3.5-flash-lite` (`GOOGLE_MODEL_PRICING`, `googlePricingFor`), from the Gemini API pricing page as of 2026-10-17. Models priced by prompt length, by input modality, or with a scheduled price change stay unpriced.
+- 503 `UNAVAILABLE` throws `ProviderOverloadedError`. 400 and 500 failures are marked `billed: false`, as Google's billing docs state.
+- An adapter contract test verifies that aborting `signal` rejects `complete()` and `stream()` on the model and cancels the HTTP request.
+- With `streamChunks`, `stream()` yields `reasoning` for thought parts (sent when `thinkingConfig.includeThoughts` is on) and `usage` for every chunk carrying `usageMetadata`.
+- `ai.providerTool({ provider: "google", definition })` entries (`{ googleSearch: {} }`, `{ codeExecution: {} }`, `{ urlContext: {} }`) are sent verbatim as their own `Tool` after the function declarations; other providers' tools are skipped with a warning.
+- `providerOptions.google.body` forwards native per-call request options for completions and streams while protecting the model, conversation and tool definitions.
+- Models expose native `countTokens()` preflight. Vertex counts system instructions and tools; unsupported Developer API system/tool and cached-content counts fail explicitly.
+
 ## 5.30.0 - 2026-10-16
 
 ### Changed
@@ -81,6 +113,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed
@@ -154,7 +187,7 @@ changelogs.
 
 ### Deprecated
 
-- **Google has deprecated `generateImages`, the transport the `imagen-*` path still uses.** Verbatim from the `@google/genai` runtime warning: *"The generateImages method is deprecated and will be removed in the next major release (not before Jan. 1 2027). Please use the generateContent method with image models instead. See https://ai.google.dev/gemini-api/docs/deprecations#imagen-models and https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/image-generation#generate-images"* (`editImage` carries the same notice.) Nothing breaks today and the Imagen path is unchanged, but it is on a clock: new image work should prefer a `gemini-` id. The warning is emitted by `@google/genai` ≥ 2.17; with the bump below, this package now prints it whenever the `imagen-*` path is used
+- **Google has deprecated `generateImages`, the transport the `imagen-*` path still uses.** Verbatim from the `@google/genai` runtime warning: _"The generateImages method is deprecated and will be removed in the next major release (not before Jan. 1 2027). Please use the generateContent method with image models instead. See https://ai.google.dev/gemini-api/docs/deprecations#imagen-models and https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/capabilities/image-generation#generate-images"_ (`editImage` carries the same notice.) Nothing breaks today and the Imagen path is unchanged, but it is on a clock: new image work should prefer a `gemini-` id. The warning is emitted by `@google/genai` ≥ 2.17; with the bump below, this package now prints it whenever the `imagen-*` path is used
 
 ### Changed
 

package/cjs/index.cjs

@@ -19,8 +19,13 @@ let _warlock_js_logger = require("@warlock.js/logger");
 *
 * `total` falls back to `input + output` when Google omits
 * `totalTokenCount`.
+*
+* `promptTokenCount` "includes the number of tokens in the cached
+* content" (https://ai.google.dev/api/generate-content#UsageMetadata), so
+* the usage is marked `inputIncludesCache: true`.
 */
 function applyGoogleUsage(usage, raw) {
+	usage.inputIncludesCache = true;
 	usage.input = raw.promptTokenCount ?? usage.input;
 	usage.output = raw.candidatesTokenCount ?? usage.output;
 	usage.total = raw.totalTokenCount ?? usage.input + usage.output;
@@ -78,6 +83,12 @@ function mapFinishReason(raw) {
 * 4. **Tool calls are `functionCall` parts.** An assistant message
 *    with `toolCalls` becomes a `"model"` content: an optional leading
 *    `text` part followed by one `functionCall` part per call.
+* 5. **Adjacent same-role turns merge.** Consecutive contents with the
+*    same role become one content with their parts in order, so the
+*    results of parallel tool calls travel as one `user` turn (as the
+*    `@google/genai` SDK's own automatic function calling sends them)
+*    and a compaction summary next to a same-role turn does not break
+*    the user/model alternation.
 *
 * @example
 * const { systemInstruction, contents } = toGoogleContents([
@@ -137,10 +148,36 @@ function toGoogleContents(messages) {
 	}
 	return {
 		systemInstruction: systemParts.length > 0 ? systemParts.join("\n\n") : void 0,
-		contents
+		contents: mergeAdjacentContents(contents)
 	};
 }
 /**
+* Join consecutive contents that share a role into one, keeping part
+* order: parallel `functionResponse` parts stay in their `functionCall`
+* order, and each `functionCall` keeps its own `thoughtSignature`.
+* Returns new content objects; the input contents are not modified.
+*
+* Source for the single-turn shape: `@google/genai` 2.19.0
+* `Models.generateContent` (automatic function calling) sends every
+* function response of one model turn as a single `{ role: "user",
+* parts }` content, in call order.
+*/
+function mergeAdjacentContents(contents) {
+	const merged = [];
+	for (const content of contents) {
+		const previous = merged.at(-1);
+		if (previous && previous.role === content.role) {
+			merged[merged.length - 1] = {
+				...previous,
+				parts: [...previous.parts ?? [], ...content.parts ?? []]
+			};
+			continue;
+		}
+		merged.push(content);
+	}
+	return merged;
+}
+/**
 * Multipart content is only meaningful on user messages — for any
 * other role collapse a `ContentPart[]` to concatenated text. Plain
 * strings pass through unchanged.
@@ -252,35 +289,48 @@ function wrapGoogleError(thrown) {
 	const shape = toShape(thrown);
 	const context = buildContext(shape);
 	const message = shape.message ?? (thrown instanceof Error ? thrown.message : String(thrown));
+	const billed = shape.status === 400 || shape.status === 500 ? false : void 0;
 	if (isTimeout(shape)) return new _warlock_js_ai.ProviderTimeoutError(message, {
 		cause: thrown,
-		context
+		context,
+		billed
 	});
 	if (shape.status === 401 || shape.status === 403 || /permission_denied|api key not valid|unauthenticated/i.test(message)) return new _warlock_js_ai.ProviderAuthError(message, {
 		cause: thrown,
-		context
+		context,
+		billed
 	});
 	if (shape.status === 429 || /resource_exhausted|quota/i.test(message)) return new _warlock_js_ai.ProviderRateLimitError(message, {
 		cause: thrown,
-		context
+		context,
+		billed
 	});
 	if (shape.status === 400) {
 		if (/token count|context length|exceeds the maximum|input is too long/i.test(message)) return new _warlock_js_ai.ContextLengthExceededError(message, {
 			cause: thrown,
-			context
+			context,
+			billed
 		});
 		return new _warlock_js_ai.InvalidRequestError(message, {
 			cause: thrown,
-			context
+			context,
+			billed
 		});
 	}
 	if (shape.status === 404 || isClientStatus(shape.status)) return new _warlock_js_ai.InvalidRequestError(message, {
 		cause: thrown,
-		context
+		context,
+		billed
+	});
+	if (shape.status === 503 || /\bUNAVAILABLE\b/.test(message) || /overloaded/i.test(message)) return new _warlock_js_ai.ProviderOverloadedError(message, {
+		cause: thrown,
+		context,
+		billed
 	});
 	return new _warlock_js_ai.ProviderError(message, {
 		cause: thrown,
-		context
+		context,
+		billed
 	});
 }
 /**
@@ -449,7 +499,7 @@ const DEFAULT_RESPONSE_MODALITIES = ["TEXT", "IMAGE"];
 * or image generation being "stopped" for safety, prohibited content,
 * recitation, blocklist, or SPII.
 */
-const FILTERED_FINISH_REASONS = new Set([
+const FILTERED_FINISH_REASONS = /* @__PURE__ */ new Set([
 	"SAFETY",
 	"IMAGE_SAFETY",
 	"PROHIBITED_CONTENT",
@@ -747,6 +797,106 @@ var GoogleImageModel = class {
 	}
 };
 
+//#endregion
+//#region ../../packages/ai-google/src/known-pricing.ts
+/**
+* Built-in Gemini API list prices (paid tier, Standard), USD per
+* 1,000,000 tokens, keyed by exact model id. `cachedInput` is the
+* context-cache read rate; the hourly cache-storage charge is not a token
+* rate and is never included.
+*
+* Source: https://ai.google.dev/gemini-api/docs/pricing, fetched
+* 2026-10-17. Only models with one flat token price are listed. Left out
+* on purpose — pass `pricing` yourself for them:
+*
+* - Models priced by prompt length (the Pro models, split at 200k
+*   prompt tokens).
+* - Models with a higher audio-input rate (most Flash / Flash-Lite
+*   models): `Usage` does not split input by modality.
+* - Models with a scheduled price change (gemini-4-argon, the 3.8 / 3.6
+*   Flash models).
+*/
+const GOOGLE_MODEL_PRICING = { "gemini-3.5-flash-lite": {
+	input: .3,
+	output: 2.5,
+	cachedInput: .03
+} };
+/**
+* Look up the built-in list price for a Gemini model id (exact match),
+* or `undefined` so cost stays unknown rather than wrong.
+*
+* @example
+* googlePricingFor("gemini-3.5-flash-lite"); // { input: 0.3, output: 2.5, cachedInput: 0.03 }
+* googlePricingFor("gemini-2.5-pro"); // undefined — priced by prompt length
+*/
+function googlePricingFor(modelName) {
+	return GOOGLE_MODEL_PRICING[modelName];
+}
+/** USD per nonempty unique query for Gemini 3+, before free monthly allowances.
+* Gemini 2.5 and older bill per grounded prompt; do not use this rate for them.
+* https://ai.google.dev/gemini-api/docs/google-search#pricing — verified 2026-10-18. */
+const GOOGLE_SERVER_TOOL_PRICING = { webSearch: .014 };
+
+//#endregion
+//#region ../../packages/ai-google/src/utils/grounding.ts
+/** Candidate snapshots are replaced, not added: streamed metadata may repeat.
+* Installed @google/genai 2.19.0 GroundingMetadata.webSearchQueries; REST schema:
+* https://ai.google.dev/api/generate-content#GroundingMetadata
+* Billing ignores empty queries and counts unique queries for Gemini 3+:
+* https://ai.google.dev/gemini-api/docs/google-search#pricing
+* Gemini 2.5 and older bill per grounded prompt; this counter is NOT that unit. */
+function applyGrounding(usage, snapshots, response) {
+	for (const [position, candidate] of (response.candidates ?? []).entries()) if (candidate.groundingMetadata) snapshots.set(candidate.index ?? position, candidate.groundingMetadata);
+	const reported = [...snapshots.values()].filter((metadata) => metadata.webSearchQueries !== void 0);
+	if (reported.length > 0) {
+		const queries = reported.flatMap((metadata) => metadata.webSearchQueries ?? []);
+		usage.serverToolUse = {
+			...usage.serverToolUse,
+			webSearchRequests: new Set(queries.filter((query) => query !== "")).size,
+			googleWebSearchQueries: queries.length
+		};
+	}
+}
+/** Retain chunks, supports, search entry point and queries without flattening them. */
+function groundingMetadata(snapshots) {
+	return snapshots.size ? { google: { groundingMetadata: [...snapshots].map(([index, metadata]) => ({
+		index,
+		...metadata
+	})) } } : void 0;
+}
+
+//#endregion
+//#region ../../packages/ai-google/src/provider-options.ts
+const RESERVED_FIELDS = /* @__PURE__ */ new Set([
+	"systemInstruction",
+	"tools",
+	"abortSignal",
+	"httpOptions"
+]);
+function mergeProviderBody(built, options) {
+	const body = (options?.providerOptions?.google)?.body ?? {};
+	const reserved = Object.keys(body).filter((key) => RESERVED_FIELDS.has(key));
+	if (reserved.length > 0) throw new _warlock_js_ai.InvalidRequestError(`providerOptions.google.body cannot set ${reserved.join(", ")}: use the call's messages, tools and model options.`, { context: { fields: reserved } });
+	const defaults = built;
+	const overrides = Object.fromEntries(Object.entries(body).map(([key, value]) => {
+		const previous = defaults[key];
+		return [key, isPlainObject(previous) && isPlainObject(value) ? {
+			...previous,
+			...value
+		} : value];
+	}));
+	return {
+		...built,
+		...overrides
+	};
+}
+/** Merge only plain objects; arrays, null and provider scalar values replace the field. */
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+}
+
 //#endregion
 //#region ../../packages/ai-google/src/known-vision-models.ts
 /**
@@ -787,6 +937,8 @@ function inferVisionCapability(modelId) {
 //#endregion
 //#region ../../packages/ai-google/src/model.ts
 const LOG_MODULE = "ai.google";
+/** `provider` value of `ai.providerTool()` entries this adapter sends verbatim. */
+const GOOGLE_WIRE_FORMAT = "google";
 /**
 * Bucketed `thinkingBudget` (token caps) for the neutral
 * `reasoning.effort` levels when the caller gives no explicit
@@ -881,22 +1033,90 @@ var GoogleModel = class {
 		const toolCalls = this.extractToolCalls(response);
 		const finishReason = toolCalls ? "tool_calls" : mapFinishReason(response.candidates?.[0]?.finishReason);
 		const usage = this.extractUsage(response);
+		const grounding = /* @__PURE__ */ new Map();
+		applyGrounding(usage, grounding, response);
+		const providerMetadata = groundingMetadata(grounding);
+		(0, _warlock_js_ai.attachCost)(usage, this.pricing);
 		this.logger.debug(LOG_MODULE, "response", "generateContent call succeeded", {
 			finishReason,
 			usage
 		});
 		return {
+			...providerMetadata ? { providerMetadata } : {},
 			content: response.text ?? "",
 			finishReason,
 			usage,
 			toolCalls
 		};
 	}
+	/** Count native input tokens with the same converted content, system and tools. */
+	async countTokens(messages, options) {
+		const { systemInstruction, contents } = toGoogleContents(messages);
+		const config = this.buildConfig(systemInstruction, options);
+		if (config.cachedContent !== void 0) throw new _warlock_js_ai.InvalidRequestError("The Google SDK countTokens endpoint cannot count a cachedContent reference.", { reason: "count-unsupported" });
+		try {
+			const response = this.ai.vertexai ? await this.ai.models.countTokens({
+				model: this.name,
+				contents,
+				config: {
+					...config.systemInstruction !== void 0 ? { systemInstruction: config.systemInstruction } : {},
+					...config.tools !== void 0 ? { tools: config.tools } : {},
+					...config.abortSignal ? { abortSignal: config.abortSignal } : {},
+					...config.httpOptions ? { httpOptions: config.httpOptions } : {}
+				}
+			}) : await this.countDeveloperTokens(contents, config);
+			if (response.totalTokens === void 0) throw new _warlock_js_ai.InvalidRequestError("Google countTokens returned no totalTokens.");
+			return response.totalTokens;
+		} catch (thrown) {
+			throw this.logAndWrap(thrown);
+		}
+	}
+	/**
+	* REST counts the full generation request, unlike the typed Developer API
+	* converter in @google/genai 2.19.0. See https://ai.google.dev/api/tokens.
+	* extraBody keeps the SDK's auth, fetch, base URL, retries and cancellation.
+	*/
+	countDeveloperTokens(contents, config) {
+		config.abortSignal?.throwIfAborted();
+		const { systemInstruction, serviceTier, tools, toolConfig, safetySettings, cachedContent, abortSignal, httpOptions, ...generationConfig } = config;
+		delete generationConfig.automaticFunctionCalling;
+		const model = this.name.startsWith("models/") ? this.name : `models/${this.name}`;
+		return this.ai.models.countTokens({
+			model: this.name,
+			contents,
+			config: {
+				abortSignal,
+				httpOptions: {
+					...httpOptions,
+					extraBody: {
+						...httpOptions?.extraBody,
+						contents: void 0,
+						generateContentRequest: {
+							model,
+							contents,
+							...serviceTier !== void 0 ? { serviceTier } : {},
+							...systemInstruction !== void 0 ? { systemInstruction: { parts: [{ text: systemInstruction }] } } : {},
+							...tools !== void 0 ? { tools } : {},
+							...toolConfig !== void 0 ? { toolConfig } : {},
+							...safetySettings !== void 0 ? { safetySettings } : {},
+							...cachedContent !== void 0 ? { cachedContent } : {},
+							...Object.keys(generationConfig).length > 0 ? { generationConfig } : {}
+						}
+					}
+				}
+			}
+		});
+	}
 	/**
 	* Incremental streaming completion via `generateContentStream`.
 	* Yields neutral `ModelStreamChunk`s — `delta` for text, `tool-call`
 	* per function call (Gemini emits a fully-formed call, not partial
 	* JSON), and a terminal `done` with the final finish reason + usage.
+	*
+	* With `options.streamChunks` it also yields `reasoning` for thought
+	* parts (only sent when `thinkingConfig.includeThoughts` is on — set it
+	* through `providerOptions.google.body`) and `usage` whenever a chunk
+	* carries `usageMetadata`. No `tool-args`: calls arrive whole.
 	*/
 	async *stream(messages, options) {
 		this.logger.debug(LOG_MODULE, "request", "Starting generateContentStream call", {
@@ -923,8 +1143,17 @@ var GoogleModel = class {
 			output: 0,
 			total: 0
 		};
+		const want = (0, _warlock_js_ai.resolveStreamChunks)(options);
+		const grounding = /* @__PURE__ */ new Map();
 		try {
 			for await (const chunk of iterable) {
+				applyGrounding(usage, grounding, chunk);
+				if (want.reasoning) {
+					for (const part of chunk.candidates?.[0]?.content?.parts ?? []) if (part.thought === true && typeof part.text === "string" && part.text !== "") yield {
+						type: "reasoning",
+						delta: part.text
+					};
+				}
 				const text = chunk.text;
 				if (text) yield {
 					type: "delta",
@@ -944,20 +1173,29 @@ var GoogleModel = class {
 				}
 				const candidateFinish = chunk.candidates?.[0]?.finishReason;
 				if (candidateFinish) rawFinishReason = candidateFinish;
-				if (chunk.usageMetadata) applyGoogleUsage(usage, chunk.usageMetadata);
+				if (chunk.usageMetadata) {
+					applyGoogleUsage(usage, chunk.usageMetadata);
+					if (want.usage) yield {
+						type: "usage",
+						usage: { ...usage }
+					};
+				}
 			}
 		} catch (thrown) {
 			throw this.logAndWrap(thrown);
 		}
 		const finishReason = sawToolCall ? "tool_calls" : mapFinishReason(rawFinishReason);
+		(0, _warlock_js_ai.attachCost)(usage, this.pricing);
 		this.logger.debug(LOG_MODULE, "response", "generateContentStream call succeeded", {
 			finishReason,
 			usage
 		});
+		const providerMetadata = groundingMetadata(grounding);
 		yield {
 			type: "done",
 			finishReason,
-			usage
+			usage,
+			...providerMetadata ? { providerMetadata } : {}
 		};
 	}
 	/**
@@ -969,15 +1207,15 @@ var GoogleModel = class {
 	buildConfig(systemInstruction, options) {
 		const temperature = options?.temperature ?? this.config.temperature;
 		const maxOutputTokens = options?.maxTokens ?? this.config.maxTokens;
-		return {
+		return mergeProviderBody({
 			...systemInstruction ? { systemInstruction } : {},
 			...temperature !== void 0 ? { temperature } : {},
 			...maxOutputTokens !== void 0 ? { maxOutputTokens } : {},
 			...options?.signal ? { abortSignal: options.signal } : {},
-			...this.buildTools(options?.tools),
+			...this.buildTools(options),
 			...this.buildStructuredOutput(options?.responseSchema),
 			...this.buildThinking(options?.reasoning)
-		};
+		}, options);
 	}
 	/**
 	* Translate the neutral `reasoning` option into Gemini's
@@ -1002,11 +1240,21 @@ var GoogleModel = class {
 	}
 	/**
 	* Spread-friendly tools fragment. Empty object when no tools were
-	* supplied so the caller can unconditionally spread it.
+	* supplied so the caller can unconditionally spread it. Function tools
+	* come first; `ai.providerTool({ provider: "google" })` definitions
+	* (`{ googleSearch: {} }`, `{ codeExecution: {} }`, `{ urlContext: {} }`,
+	* …) follow verbatim as their own `Tool` entries. Other providers'
+	* definitions are skipped with a warning.
 	*/
-	buildTools(tools) {
-		const mapped = toGoogleTools(tools);
-		return mapped ? { tools: mapped } : {};
+	buildTools(options) {
+		const { tools, definitions } = (0, _warlock_js_ai.selectProviderTools)(options, {
+			accepts: [GOOGLE_WIRE_FORMAT, this.provider],
+			module: LOG_MODULE,
+			model: this.name,
+			logger: this.logger
+		});
+		const mapped = [...toGoogleTools(tools) ?? [], ...definitions];
+		return mapped.length > 0 ? { tools: mapped } : {};
 	}
 	/**
 	* Translate the neutral `responseSchema` into Gemini's native JSON
@@ -1154,11 +1402,12 @@ var GoogleSDK = class {
 	* `GoogleGenAI` client. The SDK's `provider` label is forwarded.
 	*
 	* Pricing resolution: per-model `config.pricing` wins; otherwise the
-	* SDK-level registry entry keyed by `config.name`; otherwise
-	* `undefined` (no cost computed).
+	* SDK-level registry entry keyed by `config.name`; otherwise the
+	* built-in list price (`GOOGLE_MODEL_PRICING`); otherwise `undefined`
+	* (no cost computed).
 	*/
 	model(config) {
-		const resolvedPricing = config.pricing ?? this.pricing?.[config.name];
+		const resolvedPricing = config.pricing ?? this.pricing?.[config.name] ?? googlePricingFor(config.name);
 		const resolvedConfig = resolvedPricing === config.pricing ? config : {
 			...config,
 			pricing: resolvedPricing
@@ -1219,7 +1468,10 @@ var GoogleSDK = class {
 };
 
 //#endregion
+exports.GOOGLE_MODEL_PRICING = GOOGLE_MODEL_PRICING;
+exports.GOOGLE_SERVER_TOOL_PRICING = GOOGLE_SERVER_TOOL_PRICING;
 exports.GeminiImageModel = GeminiImageModel;
 exports.GoogleImageModel = GoogleImageModel;
 exports.GoogleSDK = GoogleSDK;
+exports.googlePricingFor = googlePricingFor;
 //# sourceMappingURL=index.cjs.map