@warlock.js/ai-google 5.30.0 → 5.32.0

package/skills/setup-google/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-google
-description: 'Wire @warlock.js/ai-google — new GoogleSDK({apiKey} | {vertexai, project, location}) for Gemini API + Vertex AI. generateContent / embedContent + thoughtSignature round-trip for thinking models, batched embeddings. .model({name, vision?, reasoning?, audio?, pdf?}) with cost-truth capabilities (PDF + audio input map to Gemini inlineData), .image({name, pricing?}) for image generation via ai.image — the id picks the transport: gemini-* → generateContent + responseModalities IMAGE (usage passed through; generateImages is deprecated by Google), everything else → generateImages (Imagen, per-image, zero usage) — extended thinking via options.reasoning → thinkingConfig.thinkingBudget, usage reasoningTokens (thoughtsTokenCount) / cachedTokens (cachedContentTokenCount). Triggers: `GoogleSDK`, `google.model`, `google.embedder`, `google.image`, `imagen`, `generateImages`, `gemini image`, `nano banana`, `responseModalities`, `imageConfig`, `ai.image`, `inlineData`, `pdf input`, `audio input`, `thoughtSignature`, `responseJsonSchema`, `vertexai`, `reasoning`, `thinkingConfig`, `thinkingBudget`, `thoughtsTokenCount`, `reasoningTokens`, `cachedTokens`, `promptCaching`, `cacheControl`; "use gemini", "wire Vertex AI", "gemini embeddings", "gemini thinking tool calls", "gemini 2.5 thinking budget", "gemini cached content cost", "generate images with imagen", "generate an image with gemini", "gemini image model 404 not supported for predict", "send a pdf / audio to gemini"; import `import { GoogleSDK } from "@warlock.js/ai-google"`. Skip: the ai.image verb surface — the `generate-images` topic of the `warlock-js-ai` skill; agent loop the `run-ai-agent` topic of the `warlock-js-ai` skill; provider picking the `pick-ai-provider` topic of the `warlock-js-ai` skill; embedder usage the `embed-text` topic of the `warlock-js-ai` skill; siblings `@warlock.js/ai-openai`, `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-ollama`; raw `@google/genai`, `@google-cloud/vertexai`, Vercel `@ai-sdk/google`.'
+description: 'Wire @warlock.js/ai-google — new GoogleSDK({apiKey} | {vertexai, project, location}) for Gemini API + Vertex AI. generateContent / embedContent + thoughtSignature round-trip for thinking models, batched embeddings. .model({name, vision?, reasoning?, audio?, pdf?}) with cost-truth capabilities (PDF + audio input map to Gemini inlineData), .image({name, pricing?}) for image generation via ai.image — the id picks the transport: gemini-* → generateContent + responseModalities IMAGE (usage passed through; generateImages is deprecated by Google), everything else → generateImages (Imagen, per-image, zero usage) — extended thinking via options.reasoning → thinkingConfig.thinkingBudget, usage reasoningTokens (thoughtsTokenCount) / cachedTokens (cachedContentTokenCount). Triggers: `providerOptions`, `GoogleCallOptions`, `countTokens`, `GoogleSDK`, `google.model`, `google.embedder`, `google.image`, `imagen`, `generateImages`, `gemini image`, `nano banana`, `responseModalities`, `imageConfig`, `ai.image`, `inlineData`, `pdf input`, `audio input`, `thoughtSignature`, `responseJsonSchema`, `ai.providerTool`, `googleSearch`, `includeThoughts`, `streamChunks`, `vertexai`, `reasoning`, `thinkingConfig`, `thinkingBudget`, `thoughtsTokenCount`, `reasoningTokens`, `cachedTokens`, `inputIncludesCache`, `GOOGLE_MODEL_PRICING`, `googlePricingFor`, `ProviderOverloadedError`, `promptCaching`, `cacheControl`; "use gemini", "wire Vertex AI", "gemini embeddings", "gemini thinking tool calls", "gemini 2.5 thinking budget", "gemini cached content cost", "generate images with imagen", "generate an image with gemini", "gemini image model 404 not supported for predict", "send a pdf / audio to gemini"; import `import { GoogleSDK } from "@warlock.js/ai-google"`. Skip: the ai.image verb surface — the `generate-images` topic of the `warlock-js-ai` skill; agent loop the `run-ai-agent` topic of the `warlock-js-ai` skill; provider picking the `pick-ai-provider` topic of the `warlock-js-ai` skill; embedder usage the `embed-text` topic of the `warlock-js-ai` skill; siblings `@warlock.js/ai-openai`, `@warlock.js/ai-anthropic`, `@warlock.js/ai-bedrock`, `@warlock.js/ai-ollama`; raw `@google/genai`, `@google-cloud/vertexai`, Vercel `@ai-sdk/google`.'
 ---
 
 # `@warlock.js/ai-google`
@@ -29,21 +29,21 @@ const vertex = new GoogleSDK({
 ## Producing a model
 
 ```ts
-google.model({ name: "gemini-2.5-flash" })
-google.model({ name: "gemini-2.5-pro", temperature: 0.2 })
-google.model({ name: "gemini-1.5-flash", maxTokens: 2048 })
+google.model({ name: "gemini-2.5-flash" });
+google.model({ name: "gemini-2.5-pro", temperature: 0.2 });
+google.model({ name: "gemini-1.5-flash", maxTokens: 2048 });
 ```
 
 ## Capabilities — what's auto-set
 
-| Flag | Default |
-| --- | --- |
-| `structuredOutput` | `true` (via `responseMimeType` + `responseJsonSchema`) |
-| `vision` | Inferred from model id substring. `true` when the id contains `gemini-1.5`, `gemini-2` (covers 2.x / 2.5), `gemini-exp`, `gemini-flash`, or `gemini-pro-vision`; `false` for bare `gemini-pro` / `gemini-1.0-pro` and any unknown id. Case-insensitive, tolerates date/preview/vendor-prefix suffixes (`models/gemini-1.5-flash-001`). |
-| `reasoning` | `true` — every Gemini 2.5 model thinks; older families harmlessly ignore an empty budget. Set `reasoning: false` to stop forwarding `thinkingConfig` to a model that rejects it. |
-| `promptCaching` | Always `true` — Gemini reports cache-read hits (`cachedContentTokenCount`) via implicit caching and accepts explicit context caching. |
-| `audio` | Mirrors the `vision` inference (the multimodal Gemini families accept audio parts). Override with `audio: true \| false`. |
-| `pdf` | Mirrors the `vision` inference (the multimodal Gemini families accept PDF / document parts). Override with `pdf: true \| false`. |
+| Flag               | Default                                                                                                                                                                                                                                                                                                                                |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `structuredOutput` | `true` (via `responseMimeType` + `responseJsonSchema`)                                                                                                                                                                                                                                                                                 |
+| `vision`           | Inferred from model id substring. `true` when the id contains `gemini-1.5`, `gemini-2` (covers 2.x / 2.5), `gemini-exp`, `gemini-flash`, or `gemini-pro-vision`; `false` for bare `gemini-pro` / `gemini-1.0-pro` and any unknown id. Case-insensitive, tolerates date/preview/vendor-prefix suffixes (`models/gemini-1.5-flash-001`). |
+| `reasoning`        | `true` — every Gemini 2.5 model thinks; older families harmlessly ignore an empty budget. Set `reasoning: false` to stop forwarding `thinkingConfig` to a model that rejects it.                                                                                                                                                       |
+| `promptCaching`    | Always `true` — Gemini reports cache-read hits (`cachedContentTokenCount`) via implicit caching and accepts explicit context caching.                                                                                                                                                                                                  |
+| `audio`            | Mirrors the `vision` inference (the multimodal Gemini families accept audio parts). Override with `audio: true \| false`.                                                                                                                                                                                                              |
+| `pdf`              | Mirrors the `vision` inference (the multimodal Gemini families accept PDF / document parts). Override with `pdf: true \| false`.                                                                                                                                                                                                       |
 
 Explicit config always wins (`google.model({ name, reasoning: false, audio: false, pdf: true })`).
 
@@ -56,6 +56,15 @@ Gemini content roles must be `"user"` or `"model"` — there is no `"system"` ro
 - Neutral `assistant` → Gemini `"model"`; `user` stays `"user"`.
 - Assistant tool calls → `"model"` content: optional leading `{ text }` + one `{ functionCall: { name, args } }` part per call (`id` deliberately omitted — see below).
 - Tool results (`role: "tool"`) → a `"user"` content with one `{ functionResponse: { name, response } }` part. `response` must be a JSON object, so a stringified-JSON tool result is parsed back to an object; a non-object result is wrapped as `{ result: <raw> }`.
+- Adjacent contents with the same role merge into one, parts kept in order: parallel tool results become ONE `"user"` content with several `functionResponse` parts in call order (as `@google/genai`'s automatic function calling sends them), and an agent compaction summary merges with a same-role neighbour (user-framed summary + input; assistant summary + the next tool-call turn, text part first, each `functionCall` keeping its `thoughtSignature`). Roles therefore alternate `user`/`model`; `countTokens()` uses the same builder.
+
+Neutral history and the `contents` the adapter sends for it:
+
+```text
+user "look both up"              → { role: "user",  parts: [{ text }] }
+assistant toolCalls [a, b]       → { role: "model", parts: [{ functionCall: a }, { functionCall: b }] }
+tool a, tool b                   → { role: "user",  parts: [{ functionResponse: a }, { functionResponse: b }] }
+```
 
 **Gemini matches a result to its call by name, not id** — the Developer API assigns no function-call ids. The adapter sets neutral `id` = tool name so `toolCallId` is non-empty. The wire `id` is omitted from both `functionCall` and `functionResponse` (echoing an empty/synthetic id is rejected by Gemini). **Limitation:** two parallel calls to the same tool in one turn share an id — inherent to the Developer API's id-less design.
 
@@ -83,12 +92,12 @@ PDF and audio reach the wire only when the model declares the matching capabilit
 
 `google.image({ name })` returns an `ImageModelContract` for the `ai.image()` verb. **The model id picks the transport:**
 
-| Model id | Transport | Usage it can report |
-| --- | --- | --- |
+| Model id                                        | Transport                                                                 | Usage it can report                                                       |
+| ----------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
 | `gemini-*` (e.g. `gemini-3.1-flash-lite-image`) | `ai.models.generateContent` with `responseModalities` including `"IMAGE"` | whatever `usageMetadata` Google attaches — price with `{ input, output }` |
-| anything else (`imagen-*`, unknown ids) | `ai.models.generateImages` (Imagen) | none, always zero — price with `{ perImage }` |
+| anything else (`imagen-*`, unknown ids)         | `ai.models.generateImages` (Imagen)                                       | none, always zero — price with `{ perImage }`                             |
 
-A `gemini-` id sent to `generateImages` comes back `404 … is not supported for predict` (observed verbatim from Google) — `generateImages` routes to `{model}:predict`. `generateContent` is the SDK's own named replacement: its runtime deprecation notice for `generateImages` says *"Please use the generateContent method with image models instead"*. Routing on the id is what lets both families go through one factory. A leading `models/` resource prefix is tolerated.
+A `gemini-` id sent to `generateImages` comes back `404 … is not supported for predict` (observed verbatim from Google) — `generateImages` routes to `{model}:predict`. `generateContent` is the SDK's own named replacement: its runtime deprecation notice for `generateImages` says _"Please use the generateContent method with image models instead"_. Routing on the id is what lets both families go through one factory. A leading `models/` resource prefix is tolerated.
 
 This is **routing, not validation** — no id is refused locally. An id matching neither family takes the `generateImages` route (the pre-existing one) and fails at Google as a typed provider error, not with a local throw.
 
@@ -99,13 +108,13 @@ This is **routing, not validation** — no id is refused locally. An id matching
 ```ts
 const gemini = google.image({
   name: "gemini-3.1-flash-lite-image",
-  pricing: { input: 0.3, output: 30 },     // token-metered
+  pricing: { input: 0.3, output: 30 }, // token-metered
 });
 
 const { data, error, usage } = await ai.image({
   model: gemini,
   prompt: "a red bicycle on a white background",
-  aspectRatio: "16:9",                     // → config.imageConfig.aspectRatio
+  aspectRatio: "16:9", // → config.imageConfig.aspectRatio
   options: { imageSize: "2K", personGeneration: "ALLOW_ADULT" }, // → imageConfig passthroughs
 });
 ```
@@ -127,7 +136,7 @@ const imagen = google.image({ name: "imagen-4.0-generate-001", pricing: { perIma
 const { data, error } = await ai.image({
   model: imagen,
   prompt: "a watercolor lighthouse at dawn",
-  aspectRatio: "3:4",          // Imagen ratio (vs OpenAI's WxH `size`)
+  aspectRatio: "3:4", // Imagen ratio (vs OpenAI's WxH `size`)
   negativePrompt: "text, watermark",
   options: { imageSize: "2K", personGeneration: "allow_adult" }, // Imagen passthroughs
 });
@@ -135,7 +144,7 @@ const { data, error } = await ai.image({
 
 - Imagen is **per-image-metered** (price with `{ perImage }`) and returns base64 bytes — no hosted URL, and `usage` is an honest `{ input: 0, output: 0, total: 0 }`.
 - When every candidate is safety-filtered (`raiFilteredReason`), the run surfaces a typed `ContentFilterError` on `result.error`.
-- ⏳ **This path is on a clock.** `@google/genai` warns at runtime: *"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."* This package depends on `@google/genai` `^2.17.1`, which does emit that warning. Nothing breaks today, but new work should prefer a `gemini-*` id.
+- ⏳ **This path is on a clock.** `@google/genai` warns at runtime: _"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."_ This package depends on `@google/genai` `^2.17.1`, which does emit that warning. Nothing breaks today, but new work should prefer a `gemini-*` id.
 
 ### Not implemented: the `interactions` API
 
@@ -147,6 +156,17 @@ The verb surface lives in the `generate-images` topic of the `warlock-js-ai` ski
 
 `model.stream()` drains `generateContentStream`. Each chunk's `.text` → `{ type: "delta" }`; `functionCall` parts (read from `candidates[0].content.parts`, not the `.functionCalls` getter — the getter drops `thoughtSignature`) are emitted as `{ type: "tool-call" }` **fully formed** (Gemini streams a complete call with parsed `args`, not partial JSON), carrying `providerMetadata.thoughtSignature` when present. Terminal `{ type: "done", finishReason, usage }` — usage from the final chunk's `usageMetadata`.
 
+Opt-in chunks (`options.streamChunks`, set by `agent.stream()`): `{ type: "reasoning", delta }` per thought part (`thought: true`; sent only with `providerOptions.google.body.thinkingConfig.includeThoughts: true`) and `{ type: "usage", usage }` per chunk carrying `usageMetadata`. No `tool-args` (calls arrive whole).
+
+**Provider-defined tools:** `ai.providerTool({ provider: "google", definition: { googleSearch: {} } })` (also `{ codeExecution: {} }`, `{ urlContext: {} }`) is appended verbatim as its own `Tool` after the function declarations; other providers' tools are skipped with a warning.
+
+```ts
+ai.agent({
+  model: google.model({ name: "gemini-2.5-flash" }),
+  tools: [ai.providerTool({ provider: "google", definition: { googleSearch: {} } })],
+});
+```
+
 ## Finish-reason mapping
 
 `STOP` → `stop` · `MAX_TOKENS` → `length` · `SAFETY` / `RECITATION` / `BLOCKLIST` / `PROHIBITED_CONTENT` / `MALFORMED_FUNCTION_CALL` / unknown / null → `error`. `tool_calls` is derived from function-call presence.
@@ -156,7 +176,7 @@ The verb surface lives in the `generate-images` topic of the `warlock-js-ai` ski
 ```ts
 const embedder = google.embedder({ name: "gemini-embedding-001" });
 const { vector } = await embedder.embed("Hello world");
-const { vectors } = await embedder.embedMany(["a", "b"]);   // single batched call
+const { vectors } = await embedder.embedMany(["a", "b"]); // single batched call
 ```
 
 `embedContent` accepts an array natively, so `embedMany` is **one request** (unlike Bedrock/Titan). Pass `dimensions` to forward Gemini's `outputDimensionality` truncation hint.
@@ -172,14 +192,31 @@ Wrapped into the typed `@warlock.js/ai` `AIError` hierarchy. Gemini has no machi
 - 400 with token/context phrasing → `ContextLengthExceededError`, else `InvalidRequestError`
 - 404 / any other 4xx → `InvalidRequestError`
 - 504 / `DEADLINE_EXCEEDED` / `ETIMEDOUT` / `ECONNABORTED` / `AbortError` → `ProviderTimeoutError`
+- 503 / `UNAVAILABLE` / "overloaded" → `ProviderOverloadedError` (`code: "PROVIDER_OVERLOADED"`, `retryable: true`) — Gemini documents 503 as "temporarily overloaded or down" (https://ai.google.dev/gemini-api/docs/api-errors)
 - anything else (5xx and status-less) → `ProviderError`
 
+Every wrapped error carries `status`, `retryable` and `billed`. Google states "If your request fails with a 400 or 500 error, you won't be charged for the tokens used" (https://ai.google.dev/gemini-api/docs/billing, checked 2026-10-17), so a 400 or 500 is `billed: false`; 401 / 403 are `false` too (never reached a billable account); everything else is `"unknown"`.
+
+```ts
+import { ai, ProviderError, ProviderOverloadedError } from "@warlock.js/ai";
+import { GoogleSDK } from "@warlock.js/ai-google";
+
+const google = new GoogleSDK({ apiKey: process.env.GEMINI_API_KEY ?? "" });
+const result = await ai.agent({ model: google.model({ name: "gemini-2.5-flash" }) }).execute("hi");
+
+if (result.error instanceof ProviderOverloadedError) {
+  console.log(result.error.status, result.error.retryable); // 503, true — retry or fall back
+} else if (result.error instanceof ProviderError) {
+  console.log(result.error.billed); // false for a 400 / 500
+}
+```
+
 Timeout is checked first, so an aborted/`AbortError` request always classifies as `ProviderTimeoutError` regardless of status. `AIError` instances pass through unwrapped (no double-wrap).
 
 ## Token counting
 
 ```ts
-await google.count("some text")  // approximate heuristic, offline
+await google.count("some text"); // approximate heuristic, offline
 ```
 
 `count(text, model?)` accepts an optional model arg for signature parity but **ignores it** — the estimate is `approximateTokenCount` (≈ `ceil(chars / 4)`) from `@warlock.js/ai`, never a `countTokens` network call.
@@ -200,25 +237,81 @@ Gemini's `thinkingBudget` semantics (for direct `maxTokens` use): `0` disables t
 
 ## Token usage
 
-`complete()` / `stream()` map Gemini's `usageMetadata` into the neutral `Usage` (`{ input, output, total }`): `promptTokenCount` → `input`, `candidatesTokenCount` → `output`, `totalTokenCount` → `total` (falling back to `input + output` when absent). `cachedContentTokenCount`, when > 0, is surfaced as `usage.cachedTokens`; `thoughtsTokenCount` (a reasoning model's thinking-phase tokens), when > 0, as `usage.reasoningTokens`. Both are omitted when zero/absent. Embeddings have no usage (see above).
+`complete()` / `stream()` map Gemini's `usageMetadata` into the neutral `Usage` (`{ input, output, total }`): `promptTokenCount` → `input`, `candidatesTokenCount` → `output`, `totalTokenCount` → `total` (falling back to `input + output` when absent). `cachedContentTokenCount`, when > 0, is surfaced as `usage.cachedTokens`; `thoughtsTokenCount` (a reasoning model's thinking-phase tokens), when > 0, as `usage.reasoningTokens`. Both are omitted when zero/absent. `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` and cost bills cached tokens out of `input` once. When the model is priced, `usage.cost` is attached on `complete()` and the streaming `done` chunk. Embeddings have no usage (see above).
 
 ## Pricing
 
-Optional USD pricing flows in two ways, resolved per `model()` call:
+Resolution per `model()` call: per-model `pricing` > SDK-level registry entry > built-in `GOOGLE_MODEL_PRICING` > `undefined` (no cost computed). The resolved `ModelPricing` is attached to the produced model, and each response's `usage.cost` is computed from it.
 
 ```ts
-// SDK-level registry, keyed by model name:
+import { totalCost } from "@warlock.js/ai";
+import { GOOGLE_MODEL_PRICING, GoogleSDK, googlePricingFor } from "@warlock.js/ai-google";
+
 const google = new GoogleSDK({
-  apiKey,
-  pricing: { "gemini-2.5-flash": { input: 0.3, output: 2.5 } },
+  apiKey: process.env.GEMINI_API_KEY ?? "",
+  pricing: { "gemini-2.5-flash": { input: 0.3, output: 2.5, cachedInput: 0.03 } }, // text-input rate
 });
 
-google.model({ name: "gemini-2.5-flash" });               // → inherits the registry entry
-google.model({ name: "gemini-2.5-flash", pricing: {...} }); // → per-model pricing wins
-google.model({ name: "gemini-2.5-pro" });                  // → no entry → pricing undefined (no cost computed)
+google.model({ name: "gemini-2.5-flash" }); // → the registry entry
+google.model({ name: "gemini-3.5-flash-lite" }).pricing; // → built-in { input: 0.3, output: 2.5, cachedInput: 0.03 }
+google.model({ name: "gemini-2.5-pro" }).pricing; // → undefined (prompt-length tiers; pass pricing yourself)
+googlePricingFor("gemini-3.5-flash-lite"); // the same built-in entry
+Object.keys(GOOGLE_MODEL_PRICING); // the priced ids
+
+const { usage } = await google
+  .model({ name: "gemini-3.5-flash-lite" })
+  .complete([{ role: "user", content: "hi" }]);
+console.log(totalCost(usage.cost));
 ```
 
-Resolution order: per-model `pricing` > SDK-level registry entry > `undefined`. The resolved `ModelPricing` is attached to the produced model so the agent runtime can compute cost from usage.
+`GOOGLE_MODEL_PRICING` comes from https://ai.google.dev/gemini-api/docs/pricing (paid tier, Standard), fetched 2026-10-17. Only models with a single flat token price are listed. Deliberately unpriced: the Pro models (priced by prompt length, split at 200k prompt tokens), models whose audio input bills higher than text (`Usage` does not split input by modality — price them with the text rate yourself only if you send no audio), and models with a scheduled price change. The hourly context-cache storage charge is not a per-token rate and is never included.
+
+## Provider config options and input-token counts
+
+Native body fields merge after neutral options. When both values are plain
+objects, their immediate keys merge and caller-provided keys win; untouched
+neutral fields remain. Arrays, scalars and `null` replace the field. This merge
+is one level deep: a nested object explicitly supplied by the caller replaces
+that nested value.
+
+`providerOptions.google.body` adds native `GenerateContentConfig` fields,
+merged after neutral generation options for both completion and streaming:
+
+```ts
+const options = { providerOptions: { google: { body: { topP: 0.8, topK: 4 } } } };
+await model.complete(messages, options);
+```
+
+The key stays `google` for custom provider labels. Other provider keys are
+ignored. `GoogleCallOptions` is exported. `systemInstruction`, `tools`,
+`abortSignal` and `httpOptions` are protected and throw `InvalidRequestError`;
+use neutral messages/tools/signal and SDK transport configuration for them.
+
+`model.countTokens(messages, options?)` counts the converted contents, system
+instructions and tools on both the Gemini Developer API (API key) and Vertex AI.
+Developer API counting sends the full `generateContentRequest`, including tool
+configuration and generation settings, as documented in the
+[Gemini token-counting reference](https://ai.google.dev/api/tokens). It uses the
+existing SDK transport, preserving API-key auth, custom fetch, base URL/proxy
+settings, headers, retries and cancellation. Vertex retains its typed SDK path.
+
+Cached-content references still throw `InvalidRequestError` with
+`reason: "count-unsupported"`. Use `countInputTokens` for budget preflight: it
+returns an estimate for this explicit limitation; authentication, network,
+rate-limit and ordinary validation errors still propagate. `sdk.count(text)`
+remains a separate offline estimate.
+
+```ts
+import { countInputTokens } from "@warlock.js/ai";
+
+const messages = [
+  { role: "system" as const, content: "Be concise." },
+  { role: "user" as const, content: "Hello" },
+];
+const tools = [{ name: "lookup", description: "Look up data", execute: async () => "ok" }];
+const { tokens, source } = await countInputTokens(model, messages, { tools });
+// source is "native" for ordinary Developer API and Vertex requests, including tools.
+```
 
 ## When NOT to use this skill
 
@@ -230,3 +323,41 @@ Resolution order: per-model `pricing` > SDK-level registry entry > `undefined`.
 - The `run-ai-agent` topic of the `warlock-js-ai` skill
 - The `pick-ai-provider` topic of the `warlock-js-ai` skill
 - The `embed-text` topic of the `warlock-js-ai` skill
+
+## Search grounding metadata and fees
+
+`response.providerMetadata.google.groundingMetadata` retains the raw grounding
+metadata for each indexed candidate: queries, chunks, supports and search entry
+point. Streaming `done` carries the same metadata. Agent reports retain it per
+trip. Hosted search never produces a local function call.
+
+`usage.serverToolUse.webSearchRequests` counts unique nonempty
+`groundingMetadata.webSearchQueries`; `googleWebSearchQueries` records the raw
+array length, including duplicates and empty entries. Stream snapshots replace
+prior metadata per candidate rather than accumulating repeated snapshots.
+The [official schema](https://ai.google.dev/api/generate-content#GroundingMetadata)
+defines the queries array.
+
+[Google's pricing guide](https://ai.google.dev/gemini-api/docs/google-search#pricing)
+(verified 2026-10-18) bills Gemini 3 and newer per unique nonempty query: $14 per
+1,000 queries after the shared monthly free allowance. You can explicitly use
+the exported `GOOGLE_SERVER_TOOL_PRICING` as `pricing.serverTools` for that
+model family. Gemini 2.5 and older bill per grounded prompt; their query count
+is not a billable-prompt count, so leave this fee unpriced or account for it
+outside this per-query table. Free allowances are not subtracted locally.
+No web-fetch/code-execution count is inferred from result parts. See
+[cost tracking](https://warlock.js.org/v/latest/ai/recipes/cost-tracking/#hosted-tool-request-fees).
+
+```ts
+import { GOOGLE_SERVER_TOOL_PRICING } from "@warlock.js/ai-google";
+const model = google.model({
+  name: "gemini-3.5-flash-lite",
+
+  pricing: { ...{ input: 0.3, output: 2.5 }, serverTools: GOOGLE_SERVER_TOOL_PRICING },
+});
+const response = await model.complete(messages, {
+  providerTools: [{ provider: "google", definition: { googleSearch: {} } }],
+});
+console.log(response.usage.serverToolUse?.webSearchRequests);
+console.log(response.providerMetadata);
+```