@gullabs/google 0.13.0 → 0.16.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { zodToStandardSchema, toConfigJsonSchema, createModelRegistry, LlmError, assertNever, computeCost, redactSecrets, classifyError } from '@gullabs/core';
+import { maxOutputTokensSchema, zodToStandardSchema, toConfigJsonSchema, toConfigKeys, createModelRegistry, LlmError, classifyError, assertJsonSchemaProfile, assertInputMimeTypesAdmitted, assertModelMatchesDescriptor, assertNever, redactSecrets, assertMediaTypeAdmitted, parseRetryAfter, computeCost, isMediaTypeAdmitted, sha256Hex, canonicalJson } from '@gullabs/core';
 import { z } from 'zod';
 
 // src/adapter.ts
@@ -15,9 +15,18 @@ function requireApiKey(auth) {
 var FLEX_DEFAULT_TIMEOUT_MS = 15e5;
 var STANDARD_DEFAULT_TIMEOUT_MS = 3e5;
 var TRANSPORT_TIMEOUT_BUFFER_MS = 5e3;
+var MAX_TIMER_MS = 2147483647;
+var GOOGLE_MAX_TIMEOUT_MS = MAX_TIMER_MS - TRANSPORT_TIMEOUT_BUFFER_MS;
+var GEMINI_API_ROOT = "https://generativelanguage.googleapis.com";
+async function newGoogleGenAI(auth) {
+  const { GoogleGenAI: Sdk } = await import('@google/genai');
+  return new Sdk({
+    apiKey: requireApiKey(auth),
+    httpOptions: { baseUrl: `${GEMINI_API_ROOT}/` }
+  });
+}
 async function buildGoogleClient(auth) {
-  const { GoogleGenAI } = await import('@google/genai');
-  const ai = new GoogleGenAI({ apiKey: requireApiKey(auth) });
+  const ai = await newGoogleGenAI(auth);
   return {
     models: {
       async generateContent(params) {
@@ -25,12 +34,59 @@ async function buildGoogleClient(auth) {
         return result;
       },
       async countTokens(params) {
+        if (params.systemInstruction !== void 0 || params.tools !== void 0) {
+          return countTokensWithRequest(requireApiKey(auth), params);
+        }
         const result = await ai.models.countTokens(params);
         return result;
       }
     }
   };
 }
+var GEMINI_API_BASE = `${GEMINI_API_ROOT}/v1beta`;
+var MAX_ERROR_BODY_CHARS = 500;
+async function countTokensWithRequest(apiKey, params) {
+  const { ApiError } = await import('@google/genai');
+  const model = params.model.startsWith("models/") ? params.model : `models/${params.model}`;
+  const response = await fetch(`${GEMINI_API_BASE}/${model}:countTokens`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-goog-api-key": apiKey },
+    body: JSON.stringify({
+      generateContentRequest: {
+        model,
+        contents: params.contents,
+        ...params.systemInstruction !== void 0 ? { systemInstruction: params.systemInstruction } : {},
+        ...params.tools !== void 0 ? { tools: params.tools } : {}
+      }
+    }),
+    ...params.config?.abortSignal !== void 0 ? { signal: params.config.abortSignal } : {}
+  });
+  const raw = await response.text();
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = void 0;
+  }
+  if (!response.ok) {
+    const body = typeof parsed === "object" && parsed !== null && typeof parsed.error === "object" ? parsed : {
+      error: {
+        message: raw.length > MAX_ERROR_BODY_CHARS ? `${raw.slice(0, MAX_ERROR_BODY_CHARS)}\u2026` : raw,
+        code: response.status,
+        status: response.statusText
+      }
+    };
+    throw new ApiError({ message: JSON.stringify(body), status: response.status });
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new LlmError("Gemini countTokens response is not a JSON object", {
+      kind: "server",
+      retryable: true,
+      provider: "google"
+    });
+  }
+  return parsed;
+}
 
 // src/reasoning-budget.ts
 var GOOGLE_REASONING_EFFORT_BUDGET = {
@@ -39,6 +95,69 @@ var GOOGLE_REASONING_EFFORT_BUDGET = {
   medium: 8192,
   high: 24576
 };
+var GOOGLE_HIGH_EFFORT_MIN_OUTPUT_TOKENS = 4096;
+
+// src/json-schema.ts
+var GEMINI_KEYWORDS = [
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "enum",
+  "anyOf",
+  "$ref",
+  "$defs",
+  "items",
+  "prefixItems",
+  "minItems",
+  "maxItems",
+  "minimum",
+  "maximum",
+  "format",
+  "pattern",
+  "minLength",
+  "maxLength"
+];
+var GEMMA_IGNORED_KEYWORDS = /* @__PURE__ */ new Set([
+  "format",
+  "minLength",
+  "maxLength"
+]);
+var GOOGLE_FORMATS = ["date-time", "date", "email"];
+var GEMINI_PROFILE = {
+  provider: "google",
+  keywords: GEMINI_KEYWORDS,
+  formats: GOOGLE_FORMATS,
+  limits: {},
+  circularRefs: true,
+  booleanItems: true,
+  patternSubset: true
+};
+var GEMMA_PROFILE = {
+  ...GEMINI_PROFILE,
+  keywords: GEMINI_KEYWORDS.filter((keyword) => !GEMMA_IGNORED_KEYWORDS.has(keyword))
+};
+function googleJsonSchemaProfile(canonicalModel) {
+  return canonicalModel.startsWith("gemma-") ? GEMMA_PROFILE : GEMINI_PROFILE;
+}
+
+// src/safety-settings.ts
+var GOOGLE_SAFETY_CATEGORIES = [
+  "HARM_CATEGORY_HARASSMENT",
+  "HARM_CATEGORY_HATE_SPEECH",
+  "HARM_CATEGORY_SEXUALLY_EXPLICIT",
+  "HARM_CATEGORY_DANGEROUS_CONTENT",
+  "HARM_CATEGORY_CIVIC_INTEGRITY",
+  "HARM_CATEGORY_JAILBREAK"
+];
+var GOOGLE_SAFETY_THRESHOLDS = [
+  "HARM_BLOCK_THRESHOLD_UNSPECIFIED",
+  "BLOCK_LOW_AND_ABOVE",
+  "BLOCK_MEDIUM_AND_ABOVE",
+  "BLOCK_ONLY_HIGH",
+  "BLOCK_NONE",
+  "OFF"
+];
 
 // src/grounding.ts
 function hostnameFrom(url) {
@@ -67,23 +186,116 @@ function toCitation(chunk) {
     sourceName
   };
 }
-function normalizeGroundingCitations(groundingMetadata) {
+function utf16IndexAtByte(text, byte) {
+  if (!Number.isInteger(byte) || byte < 0) return void 0;
+  let bytes = 0;
+  let units = 0;
+  if (byte === 0) return 0;
+  for (const char of text) {
+    const code = char.codePointAt(0);
+    bytes += code < 128 ? 1 : code < 2048 ? 2 : code < 65536 ? 3 : 4;
+    units += char.length;
+    if (bytes === byte) return units;
+    if (bytes > byte) return void 0;
+  }
+  return void 0;
+}
+function segmentRange(segment, answerParts, joined, onDropped) {
+  if (segment === null || typeof segment !== "object") return void 0;
+  const raw = segment;
+  const partIndex = raw["partIndex"] ?? 0;
+  const startByte = raw["startIndex"] ?? 0;
+  const endByte = raw["endIndex"];
+  if (typeof partIndex !== "number" || typeof startByte !== "number" || typeof endByte !== "number") {
+    return void 0;
+  }
+  const part = answerParts[partIndex];
+  if (part === void 0) return void 0;
+  const start = utf16IndexAtByte(part.text, startByte);
+  const end = utf16IndexAtByte(part.text, endByte);
+  if (start === void 0 || end === void 0 || end <= start) return void 0;
+  const range = { start: part.offset + start, end: part.offset + end };
+  const expected = raw["text"];
+  if (typeof expected === "string" && joined.slice(range.start, range.end) !== expected) {
+    onDropped(
+      `google: dropped a textRange for a grounding segment (partIndex ${partIndex}, bytes ${startByte}-${endByte}): the answer at that range does not equal segment.text. The source stays cited without a range.`
+    );
+    return void 0;
+  }
+  return range;
+}
+function readSupports(groundingMetadata, answerParts, onDropped) {
+  const supports = groundingMetadata["groundingSupports"];
+  if (!Array.isArray(supports)) return void 0;
+  const joined = answerParts.map((part) => part?.text ?? "").join("");
+  const byChunk = /* @__PURE__ */ new Map();
+  for (const support of supports) {
+    if (support === null || typeof support !== "object") continue;
+    const record = support;
+    const indices = record["groundingChunkIndices"];
+    if (!Array.isArray(indices)) continue;
+    const range = segmentRange(record["segment"], answerParts, joined, onDropped);
+    for (const index of indices) {
+      if (typeof index !== "number") continue;
+      if (!byChunk.has(index) || byChunk.get(index) === void 0 && range) {
+        byChunk.set(index, range);
+      }
+    }
+  }
+  return byChunk;
+}
+function normalizeGroundingCitations(groundingMetadata, answerParts = [], onDropped = () => {
+}) {
   if (groundingMetadata === null || typeof groundingMetadata !== "object") return [];
-  const chunks = groundingMetadata["groundingChunks"];
+  const metadata = groundingMetadata;
+  const chunks = metadata["groundingChunks"];
   if (!Array.isArray(chunks)) return [];
-  const seen = /* @__PURE__ */ new Set();
-  const citations = [];
-  for (const chunk of chunks) {
+  const supports = readSupports(metadata, answerParts, onDropped);
+  const byUrl = /* @__PURE__ */ new Map();
+  chunks.forEach((chunk, chunkIndex) => {
     const citation = toCitation(chunk);
-    if (citation === void 0) continue;
-    if (seen.has(citation.url)) continue;
-    seen.add(citation.url);
-    citations.push(citation);
+    if (citation === void 0) return;
+    const existing = byUrl.get(citation.url);
+    const target = existing ?? citation;
+    if (existing === void 0) byUrl.set(citation.url, citation);
+    if (supports === void 0) return;
+    if (supports.has(chunkIndex)) {
+      target.cited = true;
+      const range = supports.get(chunkIndex);
+      if (range !== void 0 && target.textRange === void 0) {
+        target.textRange = { ...range };
+      }
+    } else if (target.cited === void 0) {
+      target.cited = false;
+    }
+  });
+  return [...byUrl.values()];
+}
+function countWebSearchQueries(groundingMetadata) {
+  if (groundingMetadata === null || typeof groundingMetadata !== "object") {
+    return void 0;
   }
-  return citations;
+  const queries = groundingMetadata["webSearchQueries"];
+  if (!Array.isArray(queries)) return void 0;
+  const named = queries.filter((q) => typeof q === "string" && q.length > 0).length;
+  return named === 0 && queries.length > 0 ? void 0 : named;
+}
+function readSearchEntryPoint(groundingMetadata) {
+  if (groundingMetadata === null || typeof groundingMetadata !== "object") {
+    return void 0;
+  }
+  const entry = groundingMetadata["searchEntryPoint"];
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+    return void 0;
+  }
+  return Object.keys(entry).length > 0 ? entry : void 0;
 }
 
 // src/tool-call-id.ts
+var SYNTHESIZED_PREFIX = "anyllm_call_";
+function isSynthesizedToolCallId(id) {
+  return id.startsWith(SYNTHESIZED_PREFIX);
+}
 function reserveProviderToolCallIds(ids) {
   const reserved = /* @__PURE__ */ new Set();
   for (const id of ids) {
@@ -96,7 +308,7 @@ function nextFallbackToolCallId(toolName, counters, reserved, counterKey = toolN
   let id;
   do {
     n += 1;
-    id = `call_${toolName}_${n}`;
+    id = `${SYNTHESIZED_PREFIX}${toolName}_${n}`;
   } while (reserved.has(id));
   counters.set(counterKey, n);
   return id;
@@ -109,78 +321,645 @@ function resolveToolCallId(providerId, toolName, counters, reserved, counterKey)
 }
 
 // src/flex-fallback.ts
-var CAPACITY_PATTERNS = [
-  /capacity/i,
-  /overload/i,
-  /overloaded/i,
-  /unavailable/i,
-  /no\s+capacity/i,
-  /temporar(?:y|ily)/i,
-  /try\s+again/i
-];
-var QUOTA_PATTERNS = [
-  /quota/i,
-  /billing/i,
-  /billable/i,
-  /payment/i,
-  /rate\s+limit/i,
-  /exceeded/i,
-  /insufficient/i
-];
 function isGeminiCapacityError(err) {
-  if (err.kind === "server") return err.httpStatus === 503;
-  if (err.kind !== "rate_limited") return false;
-  const message = err.message;
-  if (QUOTA_PATTERNS.some((pattern) => pattern.test(message))) {
-    return false;
-  }
-  return CAPACITY_PATTERNS.some((pattern) => pattern.test(message));
-}
-var GOOGLE_TRANSPORT_ERROR_PATTERN = /fetch failed|connection error|econnreset|econnrefused|etimedout|eai_again|epipe|socket hang up/i;
-function matchesGoogleTransportSignature(err) {
-  if (!(err instanceof Error)) return false;
-  if (GOOGLE_TRANSPORT_ERROR_PATTERN.test(err.message)) return true;
-  const code = err.code;
-  return typeof code === "string" && GOOGLE_TRANSPORT_ERROR_PATTERN.test(code);
-}
-function isGoogleTransportError(rawErr) {
-  if (matchesGoogleTransportSignature(rawErr)) return true;
-  if (rawErr instanceof Error) {
-    const cause = rawErr.cause;
-    if (matchesGoogleTransportSignature(cause)) return true;
-  }
-  return false;
-}
-function isGoogleModelNotFound(rawErr) {
-  if (!(rawErr instanceof Error)) return false;
-  if (rawErr.status !== 404) return false;
+  return err.httpStatus === 503;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseGoogleErrorBody(rawErr) {
+  const source = rawErr instanceof LlmError ? rawErr.cause : rawErr;
+  if (!(source instanceof Error)) return void 0;
+  let parsed;
   try {
-    const parsed = JSON.parse(rawErr.message);
-    return parsed.error?.code === 404 && parsed.error.status === "NOT_FOUND";
+    parsed = JSON.parse(source.message);
   } catch {
-    return false;
+    return void 0;
+  }
+  if (!isRecord(parsed) || !isRecord(parsed["error"])) return void 0;
+  const error = parsed["error"];
+  const details = Array.isArray(error["details"]) ? error["details"].filter(isRecord) : [];
+  return {
+    ...typeof error["status"] === "string" ? { status: error["status"] } : {},
+    ...typeof error["message"] === "string" ? { message: error["message"] } : {},
+    details
+  };
+}
+function detailOfType(body, type) {
+  return body.details.filter((d) => d["@type"] === `type.googleapis.com/${type}`);
+}
+function errorInfoReasons(body) {
+  return detailOfType(body, "google.rpc.ErrorInfo").flatMap(
+    (d) => typeof d["reason"] === "string" ? [d["reason"]] : []
+  );
+}
+function isDailyQuota(body) {
+  return detailOfType(body, "google.rpc.QuotaFailure").some(
+    (failure) => Array.isArray(failure["violations"]) && failure["violations"].some(
+      (v) => isRecord(v) && typeof v["quotaId"] === "string" && v["quotaId"].includes("PerDay")
+    )
+  );
+}
+var PROTO_DURATION = /^\d+(?:\.\d{1,9})?s$/;
+function durationText(delay) {
+  if (typeof delay === "string") return PROTO_DURATION.test(delay) ? delay : void 0;
+  if (!isRecord(delay)) return void 0;
+  const { seconds, nanos } = delay;
+  const whole = typeof seconds === "number" && Number.isSafeInteger(seconds) && seconds >= 0 ? String(seconds) : typeof seconds === "string" && /^\d+$/.test(seconds) ? seconds : seconds === void 0 ? "0" : void 0;
+  const fraction = typeof nanos === "number" && Number.isInteger(nanos) && nanos >= 0 && nanos < 1e9 ? String(nanos).padStart(9, "0") : nanos === void 0 ? "0" : void 0;
+  return whole !== void 0 && fraction !== void 0 ? `${whole}.${fraction}s` : void 0;
+}
+function retryDelayMs(body) {
+  for (const info of detailOfType(body, "google.rpc.RetryInfo")) {
+    const text = durationText(info["retryDelay"]);
+    if (text === void 0) continue;
+    const ms = parseRetryAfter({ "retry-after": text }, Date.now());
+    if (ms !== void 0) return ms;
   }
+  return void 0;
+}
+var API_KEY_REASONS = /* @__PURE__ */ new Set(["API_KEY_INVALID", "API_KEY_EXPIRED"]);
+var STALE_CACHE_MESSAGE = "CachedContent not found";
+function isGoogleNotFoundError(err) {
+  if (typeof err !== "object" || err === null) return false;
+  const obj = err;
+  const httpStatus = classifyError(err).httpStatus ?? numericStatus(obj["httpStatus"]);
+  if (httpStatus === 404 || obj["status"] === "NOT_FOUND" || obj["code"] === "NOT_FOUND") {
+    return true;
+  }
+  const body = parseGoogleErrorBody(err);
+  const message = body?.message ?? (typeof obj["message"] === "string" ? obj["message"] : "");
+  if (httpStatus === 403) return /may not exist|not found/i.test(message);
+  const statusKnown = httpStatus !== void 0 || body?.status !== void 0 || typeof obj["status"] === "string" || [obj["status"], obj["code"]].some((value) => typeof value === "number");
+  if (statusKnown) return false;
+  return /not\s*found|404/i.test(message) && /file|cachedcontent/i.test(message);
+}
+function numericStatus(value) {
+  const n = typeof value === "number" ? value : typeof value === "string" && /^\d{3}$/.test(value.trim()) ? Number(value) : void 0;
+  return n !== void 0 && Number.isInteger(n) && n >= 100 && n <= 599 ? n : void 0;
 }
 function classifyGoogleError(rawErr, extra) {
   const base = classifyError(rawErr);
-  const reclassifyAsTransport = base.kind === "unknown" && isGoogleTransportError(rawErr);
-  const reclassifyAsBadRequest = base.kind === "unknown" && isGoogleModelNotFound(rawErr);
-  return new LlmError(base.message, {
-    kind: reclassifyAsTransport ? "server" : reclassifyAsBadRequest ? "bad_request" : base.kind,
-    retryable: reclassifyAsTransport ? true : base.retryable,
+  const body = parseGoogleErrorBody(rawErr);
+  let kind = base.kind;
+  let retryable = base.retryable;
+  let reason = base.reason;
+  let retryAfterMs = base.retryAfterMs;
+  let message = base.message;
+  if (extra?.transportTimeout !== void 0) {
+    kind = "timeout";
+    retryable = false;
+    reason = "transport_timeout";
+    retryAfterMs = void 0;
+    message = extra.transportTimeout;
+  } else if (!(rawErr instanceof LlmError) && base.kind === "timeout" && base.httpStatus === void 0) {
+    retryable = false;
+    reason = "transport_timeout";
+    retryAfterMs = void 0;
+  }
+  if (body !== void 0 && base.httpStatus !== void 0) {
+    if (errorInfoReasons(body).some((r) => API_KEY_REASONS.has(r))) {
+      kind = "invalid_auth";
+      retryable = false;
+    } else if (base.httpStatus === 403 && body.message?.startsWith(STALE_CACHE_MESSAGE) === true) {
+      kind = "bad_request";
+      retryable = false;
+      reason = "cache_not_found";
+    } else if (base.httpStatus === 429) {
+      if (isDailyQuota(body)) {
+        kind = "rate_limited";
+        retryable = false;
+        reason = "daily_quota";
+        retryAfterMs = void 0;
+      } else {
+        retryAfterMs = retryDelayMs(body) ?? retryAfterMs;
+      }
+    }
+  }
+  return new LlmError(message, {
+    kind,
+    retryable,
+    ...reason !== void 0 ? { reason } : {},
     ...base.httpStatus !== void 0 ? { httpStatus: base.httpStatus } : {},
-    ...base.retryAfterMs !== void 0 ? { retryAfterMs: base.retryAfterMs } : {},
+    ...retryAfterMs !== void 0 ? { retryAfterMs } : {},
     provider: "google",
     cause: base.cause ?? rawErr,
     ...extra?.servedServiceTier !== void 0 ? { servedServiceTier: extra.servedServiceTier } : {}
   });
 }
 
+// src/platform-scheduler.ts
+var PLATFORM_SCHEDULER = {
+  setTimeout: (callback, ms) => globalThis.setTimeout(callback, ms),
+  clearTimeout: (handle) => {
+    globalThis.clearTimeout(handle);
+  }
+};
+
+// src/pricing.ts
+var pricingVersion = "gemini-2026-10-03";
+var GEMINI_PRICED_TIERS = ["standard", "flex"];
+function freezeRates(rates) {
+  if (rates.gt200k !== void 0) Object.freeze(rates.gt200k);
+  if (rates.audio !== void 0) Object.freeze(rates.audio);
+  return Object.freeze(rates);
+}
+function tiers(standard, flex) {
+  return Object.freeze({ standard: freezeRates(standard), flex: freezeRates(flex) });
+}
+var GEMINI_PRICING = Object.freeze({
+  // Gemini 2.5 Pro. Flex cached equals standard on both context bands. No separate audio price.
+  "gemini-2.5-pro": tiers(
+    {
+      inputPerM: 125e4,
+      cachedPerM: 125e3,
+      outputPerM: 1e7,
+      gt200k: { inputPerM: 25e5, cachedPerM: 25e4, outputPerM: 15e6 }
+    },
+    {
+      inputPerM: 625e3,
+      cachedPerM: 125e3,
+      outputPerM: 5e6,
+      gt200k: { inputPerM: 125e4, cachedPerM: 25e4, outputPerM: 75e5 }
+    }
+  ),
+  // Gemini 2.5 Flash. Flex cached stays $0.03. Audio: $1.00 / cached $0.10 standard,
+  // $0.50 / cached $0.10 flex.
+  "gemini-2.5-flash": tiers(
+    {
+      inputPerM: 3e5,
+      cachedPerM: 3e4,
+      outputPerM: 25e5,
+      audio: { inputPerM: 1e6, cachedPerM: 1e5 }
+    },
+    {
+      inputPerM: 15e4,
+      cachedPerM: 3e4,
+      outputPerM: 125e4,
+      audio: { inputPerM: 5e5, cachedPerM: 1e5 }
+    }
+  ),
+  // Gemini 2.5 Flash-Lite. Flex cached stays $0.01. Audio: $0.30 / cached $0.03
+  // standard, $0.15 / cached $0.03 flex.
+  "gemini-2.5-flash-lite": tiers(
+    {
+      inputPerM: 1e5,
+      cachedPerM: 1e4,
+      outputPerM: 4e5,
+      audio: { inputPerM: 3e5, cachedPerM: 3e4 }
+    },
+    {
+      inputPerM: 5e4,
+      cachedPerM: 1e4,
+      outputPerM: 2e5,
+      audio: { inputPerM: 15e4, cachedPerM: 3e4 }
+    }
+  ),
+  // Gemini 3.1 Flash-Lite. Flex cached is the published $0.0125. Audio: $0.50 /
+  // cached $0.05 standard, $0.25 / cached $0.025 flex.
+  "gemini-3.1-flash-lite": tiers(
+    {
+      inputPerM: 25e4,
+      cachedPerM: 25e3,
+      outputPerM: 15e5,
+      audio: { inputPerM: 5e5, cachedPerM: 5e4 }
+    },
+    {
+      inputPerM: 125e3,
+      cachedPerM: 12500,
+      outputPerM: 75e4,
+      audio: { inputPerM: 25e4, cachedPerM: 25e3 }
+    }
+  ),
+  // Gemini 3.8 / 3.7 / 3.6 Flash intro rates (2026-09-25), one rate for all
+  // modalities. Flex cached is half of the intro cached rate. Re-snapshot on 2027-01-01.
+  "gemini-3.8-flash": tiers(
+    { inputPerM: 75e4, cachedPerM: 75e3, outputPerM: 375e4 },
+    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 }
+  ),
+  "gemini-3.7-flash": tiers(
+    { inputPerM: 75e4, cachedPerM: 75e3, outputPerM: 375e4 },
+    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 }
+  ),
+  "gemini-3.6-flash": tiers(
+    { inputPerM: 75e4, cachedPerM: 75e3, outputPerM: 375e4 },
+    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 }
+  ),
+  // Gemini 3.5 Flash-Lite, one rate for all modalities (audio included). Flex
+  // cached is the published $0.02, not half of $0.03.
+  "gemini-3.5-flash-lite": tiers(
+    { inputPerM: 3e5, cachedPerM: 3e4, outputPerM: 25e5 },
+    { inputPerM: 15e4, cachedPerM: 2e4, outputPerM: 125e4 }
+  ),
+  // Gemini 3.1 Pro Preview. Flex cached equals standard on both bands. No separate audio price.
+  "gemini-3.1-pro-preview": tiers(
+    {
+      inputPerM: 2e6,
+      cachedPerM: 2e5,
+      outputPerM: 12e6,
+      gt200k: { inputPerM: 4e6, cachedPerM: 4e5, outputPerM: 18e6 }
+    },
+    {
+      inputPerM: 1e6,
+      cachedPerM: 2e5,
+      outputPerM: 6e6,
+      gt200k: { inputPerM: 2e6, cachedPerM: 4e5, outputPerM: 9e6 }
+    }
+  )
+});
+var PER_QUERY = Object.freeze({
+  unit: "query",
+  microUsdPerUnit: 14e3
+});
+var PER_GROUNDED_PROMPT = Object.freeze({
+  unit: "prompt",
+  microUsdPerUnit: 35e3
+});
+var GEMINI_GROUNDING_PRICING = Object.freeze({
+  "gemini-2.5-pro": PER_GROUNDED_PROMPT,
+  "gemini-2.5-flash": PER_GROUNDED_PROMPT,
+  "gemini-2.5-flash-lite": PER_GROUNDED_PROMPT,
+  "gemini-3.1-flash-lite": PER_QUERY,
+  "gemini-3.8-flash": PER_QUERY,
+  "gemini-3.7-flash": PER_QUERY,
+  "gemini-3.6-flash": PER_QUERY,
+  "gemini-3.5-flash-lite": PER_QUERY,
+  "gemini-3.1-pro-preview": PER_QUERY
+});
+function resolveGeminiGroundingRate(model) {
+  return Object.hasOwn(GEMINI_GROUNDING_PRICING, model) ? GEMINI_GROUNDING_PRICING[model] : void 0;
+}
+function isPricedGeminiTier(tier) {
+  return GEMINI_PRICED_TIERS.includes(tier);
+}
+function lookupGeminiTierRates(model, tier) {
+  const entry = Object.hasOwn(GEMINI_PRICING, model) ? GEMINI_PRICING[model] : void 0;
+  if (entry === void 0) return void 0;
+  if (tier !== void 0 && !isPricedGeminiTier(tier)) return void 0;
+  return entry;
+}
+function resolveGeminiRates(model, tier) {
+  const entry = lookupGeminiTierRates(model, tier);
+  if (entry === void 0) return void 0;
+  const key = tier ?? "standard";
+  return entry[key];
+}
+
+// src/cost.ts
+function tokenDetail(usage, key) {
+  const value = usage.details[key];
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.floor(value) : void 0;
+}
+function modalitySplitTotal(usage, prefix) {
+  let total;
+  for (const [key, value] of Object.entries(usage.details)) {
+    if (key.startsWith(prefix) && Number.isFinite(value) && value >= 0) {
+      total = (total ?? 0) + value;
+    }
+  }
+  return total;
+}
+function promptLanes(usage) {
+  const total = usage.inputTokens;
+  const cachedReported = usage.cachedInputTokens ?? 0;
+  const promptAudio = tokenDetail(usage, "input_audio");
+  const cachedAudio = tokenDetail(usage, "cached_audio");
+  const gaps = [];
+  const gap = (reason) => {
+    if (!gaps.includes(reason)) gaps.push(reason);
+  };
+  const cached = Math.min(cachedReported, total);
+  if (cachedReported > total) gap("inconsistent");
+  const audioCached = Math.min(cachedAudio ?? 0, cached);
+  if ((cachedAudio ?? 0) > cached) gap("inconsistent");
+  if (promptAudio !== void 0 && promptAudio < audioCached) gap("inconsistent");
+  const audioTotal = Math.min(Math.max(promptAudio ?? 0, audioCached), total);
+  if ((promptAudio ?? 0) > total) gap("inconsistent");
+  const audioUncached = Math.min(audioTotal - audioCached, total - cached);
+  if (audioTotal - audioCached > total - cached) gap("inconsistent");
+  if (usage.details["audio_input_requested"] === 1 && !((promptAudio ?? 0) > 0)) {
+    gap("audio-unreported");
+  }
+  const promptSplit = modalitySplitTotal(usage, "input_");
+  const promptHoldsNoAudio = promptAudio === 0 || promptAudio === void 0 && promptSplit !== void 0 && promptSplit >= total;
+  if (cached > 0 && cachedAudio === void 0 && !promptHoldsNoAudio) {
+    gap("cached-audio-unknown");
+  }
+  return {
+    audioUncached,
+    audioCached,
+    otherUncached: total - cached - audioUncached,
+    otherCached: cached - audioCached,
+    gaps
+  };
+}
+function priceCall(model, usage, tier) {
+  if (usage.details["usage_missing"] === 1) {
+    return {
+      microUsd: null,
+      usd: null,
+      pricingVersion,
+      confidence: "estimated",
+      details: { input: 0, cached: 0, output: 0, tools: 0 },
+      unpricedReason: "The response carried no usageMetadata, so the tokens billed are unknown."
+    };
+  }
+  const modelRates = resolveGeminiRates(model, tier);
+  const audioRates = modelRates?.audio;
+  let cost;
+  if (audioRates === void 0) {
+    cost = computeCost(model, usage, tier, resolveGeminiRates, pricingVersion);
+  } else {
+    const lanes = promptLanes(usage);
+    const textUsage = {
+      ...usage,
+      inputTokens: lanes.otherUncached + lanes.otherCached,
+      cachedInputTokens: lanes.otherCached
+    };
+    const text = computeCost(model, textUsage, tier, resolveGeminiRates, pricingVersion);
+    const audioUncachedCost = Math.round(
+      lanes.audioUncached * audioRates.inputPerM / 1e6
+    );
+    const audioCachedCost = Math.round(
+      lanes.audioCached * audioRates.cachedPerM / 1e6
+    );
+    const microUsd2 = (text.microUsd ?? 0) + audioUncachedCost + audioCachedCost;
+    cost = {
+      ...text,
+      microUsd: microUsd2,
+      usd: microUsd2 / 1e6,
+      // An audio share the response does not pin down can understate the amount.
+      ...lanes.gaps.length > 0 ? { confidence: "estimated" } : {},
+      details: {
+        ...text.details,
+        input: text.details.input + audioUncachedCost,
+        cached: text.details.cached + audioCachedCost
+      }
+    };
+  }
+  if (cost.microUsd === null) return cost;
+  if (usage.details["web_search_requested"] !== 1) return cost;
+  const calls = usage.details["web_search_calls"];
+  if (calls === 0) return cost;
+  const rate = resolveGeminiGroundingRate(model);
+  const tools = rate === void 0 || calls === void 0 ? 0 : rate.unit === "query" ? Math.round(calls * rate.microUsdPerUnit) : rate.microUsdPerUnit;
+  const microUsd = cost.microUsd + tools;
+  return {
+    ...cost,
+    microUsd,
+    usd: microUsd / 1e6,
+    confidence: "estimated",
+    details: { ...cost.details, tools }
+  };
+}
+function geminiPricingSource() {
+  return {
+    version: pricingVersion,
+    price(model, usage, tier) {
+      return priceCall(model, usage, tier);
+    },
+    hasModel(model) {
+      return resolveGeminiRates(model, void 0) !== void 0;
+    },
+    listModels() {
+      return Object.keys(GEMINI_PRICING);
+    }
+  };
+}
+
+// src/utf8.ts
+function utf8ByteLength(text) {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const unit = text.charCodeAt(i);
+    if (unit < 128) bytes += 1;
+    else if (unit < 2048) bytes += 2;
+    else if (unit >= 55296 && unit <= 56319) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 56320 && next <= 57343) {
+        bytes += 4;
+        i += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+var STATE_PATH = "transientProviderState";
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+var ENTRY_KEYS = /* @__PURE__ */ new Set([
+  "messageIndex",
+  "partIndex",
+  "kind",
+  "model",
+  "partSha256",
+  "signature"
+]);
+function badState(path, why) {
+  return new LlmError(`${path}: ${why}`, {
+    kind: "bad_request",
+    retryable: false,
+    provider: "google",
+    issues: [{ path, message: why }]
+  });
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hashedForm(part, path) {
+  switch (part.kind) {
+    case "text":
+      return { kind: "text", text: part.text };
+    case "tool-call":
+      return {
+        kind: "tool-call",
+        toolCallId: part.toolCallId,
+        toolName: part.toolName,
+        args: part.args
+      };
+    default:
+      throw badState(
+        path,
+        `a thought signature cannot be attached to a "${part.kind}" part`
+      );
+  }
+}
+function partSha256(part, path = "part") {
+  return sha256Hex(canonicalJson(hashedForm(part, path)));
+}
+function parseSignatureState(value) {
+  if (value === void 0) return [];
+  if (!isRecord2(value)) {
+    throw badState(STATE_PATH, "must be { google: { signatures: [...] } }");
+  }
+  for (const key of Object.keys(value)) {
+    if (key !== "google") {
+      throw badState(
+        `${STATE_PATH}.${key}`,
+        `holds another provider's state; Google state is { google: { signatures: [...] } }`
+      );
+    }
+  }
+  const google = value["google"];
+  if (!isRecord2(google)) {
+    throw badState(`${STATE_PATH}.google`, "must be { signatures: [...] }");
+  }
+  for (const key of Object.keys(google)) {
+    if (key !== "signatures") {
+      throw badState(`${STATE_PATH}.google.${key}`, "is not a known key");
+    }
+  }
+  const list = google["signatures"];
+  if (!Array.isArray(list)) {
+    throw badState(`${STATE_PATH}.google.signatures`, "must be an array");
+  }
+  return list.map((raw, index) => {
+    const path = `${STATE_PATH}.google.signatures.${index}`;
+    if (!isRecord2(raw)) throw badState(path, "must be an object");
+    for (const key of Object.keys(raw)) {
+      if (!ENTRY_KEYS.has(key)) throw badState(`${path}.${key}`, "is not a known key");
+    }
+    const { messageIndex, partIndex, kind, model, partSha256: digest, signature } = raw;
+    if (typeof messageIndex !== "number" || !Number.isInteger(messageIndex) || messageIndex < 0) {
+      throw badState(`${path}.messageIndex`, "must be a non-negative integer");
+    }
+    if (typeof partIndex !== "number" || !Number.isInteger(partIndex) || partIndex < 0) {
+      throw badState(`${path}.partIndex`, "must be a non-negative integer");
+    }
+    if (kind !== "text" && kind !== "tool-call") {
+      throw badState(`${path}.kind`, 'must be "text" or "tool-call"');
+    }
+    if (typeof model !== "string" || model.length === 0) {
+      throw badState(`${path}.model`, "must be a non-empty string");
+    }
+    if (typeof digest !== "string" || !SHA256_HEX.test(digest)) {
+      throw badState(`${path}.partSha256`, "must be 64 lowercase hex characters");
+    }
+    if (typeof signature !== "string" || signature.length === 0) {
+      throw badState(`${path}.signature`, "must be a non-empty string");
+    }
+    return { messageIndex, partIndex, kind, model, partSha256: digest, signature };
+  });
+}
+var STALE = "history was edited, reordered or produced by another model after the signature was issued";
+function resolveSignatures(entries, messages, model) {
+  const bySlot = /* @__PURE__ */ new Map();
+  const kept = [];
+  const dropped = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const [index, entry] of entries.entries()) {
+    const path = `${STATE_PATH}.google.signatures.${index}`;
+    const slot = `${entry.messageIndex}:${entry.partIndex}`;
+    const where = `messages.${entry.messageIndex}.parts.${entry.partIndex}`;
+    const stale = (field, why) => {
+      if (entry.kind === "tool-call") throw badState(`${path}.${field}`, why);
+      dropped.push(`${where}: ${why}`);
+    };
+    if (seen.has(slot)) throw badState(path, `duplicates the entry for ${where}`);
+    seen.add(slot);
+    if (entry.model !== model) {
+      stale(
+        "model",
+        `was issued for model "${entry.model}" but this request names "${model}"; signatures are not replayed across models (${STALE})`
+      );
+      continue;
+    }
+    const message = messages[entry.messageIndex];
+    if (message === void 0 || message.role !== "assistant") {
+      stale(
+        "messageIndex",
+        `does not point at an assistant message in messages (${STALE})`
+      );
+      continue;
+    }
+    const part = message.parts[entry.partIndex];
+    if (part === void 0) {
+      stale("partIndex", `is out of range for the message (${STALE})`);
+      continue;
+    }
+    if (part.kind !== entry.kind) {
+      stale(
+        "kind",
+        `is for a "${entry.kind}" part but ${where} is a "${part.kind}" part (${STALE})`
+      );
+      continue;
+    }
+    if (partSha256(part, where) !== entry.partSha256) {
+      stale("partSha256", `does not match ${where} (${STALE})`);
+      continue;
+    }
+    bySlot.set(slot, entry.signature);
+    kept.push(entry);
+  }
+  for (const [mi, message] of messages.entries()) {
+    if (message.role !== "assistant") continue;
+    const first = message.parts.findIndex((part) => part.kind === "tool-call");
+    if (first === -1 || bySlot.has(`${mi}:${first}`)) continue;
+    const call = message.parts[first];
+    throw badState(
+      `messages.${mi}.parts.${first}`,
+      `replays tool call "${call?.kind === "tool-call" ? call.toolCallId : ""}" without its thought signature in transientProviderState; Gemini 3 rejects a function call that lost it. Send the transientProviderState from the result that produced this message, and the history unedited, with the same model string. If you removed messages from the history, remove their entries with dropMessagesFromSignatureState`
+    );
+  }
+  return { bySlot, kept, dropped };
+}
+function signatureEntry(messageIndex, partIndex, model, part, signature) {
+  if (part.kind !== "text" && part.kind !== "tool-call") {
+    throw badState(
+      `messages.${messageIndex}.parts.${partIndex}`,
+      `a thought signature cannot be attached to a "${part.kind}" part`
+    );
+  }
+  return {
+    messageIndex,
+    partIndex,
+    kind: part.kind,
+    model,
+    partSha256: partSha256(part),
+    signature
+  };
+}
+function dropMessagesFromSignatureState(state, indices) {
+  const removed = /* @__PURE__ */ new Set();
+  for (const [i, value] of indices.entries()) {
+    if (!Number.isInteger(value) || value < 0) {
+      throw new LlmError(
+        `dropMessagesFromSignatureState: indices.${i} must be a non-negative integer.`,
+        {
+          kind: "bad_request",
+          retryable: false,
+          issues: [{ path: `indices.${i}`, message: "must be a non-negative integer" }]
+        }
+      );
+    }
+    if (removed.has(value)) {
+      throw new LlmError(
+        `dropMessagesFromSignatureState: indices.${i} repeats message ${value}.`,
+        {
+          kind: "bad_request",
+          retryable: false,
+          issues: [{ path: `indices.${i}`, message: "is a duplicate" }]
+        }
+      );
+    }
+    removed.add(value);
+  }
+  const sorted = [...removed].sort((a, b) => a - b);
+  const signatures = [];
+  for (const entry of parseSignatureState(state)) {
+    if (removed.has(entry.messageIndex)) continue;
+    const shift = sorted.filter((index) => index < entry.messageIndex).length;
+    signatures.push({ ...entry, messageIndex: entry.messageIndex - shift });
+  }
+  return signatures.length > 0 ? { google: { signatures } } : void 0;
+}
+
 // src/adapter.ts
 var ALLOWED_GOOGLE_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "allowSchemaWithSearch",
   "cachedContent",
   "flexFallback",
   "httpOptions",
+  "requireGrounding",
   "safetySettings",
   "tools"
 ]);
@@ -241,6 +1020,8 @@ function parseGoogleTool(tool, model) {
       );
   }
 }
+var SAFETY_CATEGORY_SET = new Set(GOOGLE_SAFETY_CATEGORIES);
+var SAFETY_THRESHOLD_SET = new Set(GOOGLE_SAFETY_THRESHOLDS);
 function parseGoogleSafetySetting(setting, index, model) {
   if (!isPlainRecord(setting)) {
     throw badGoogleProviderOptions(
@@ -256,14 +1037,14 @@ function parseGoogleSafetySetting(setting, index, model) {
       )}] for model "${model}". Allowed keys: category, threshold.`
     );
   }
-  if (typeof setting["category"] !== "string" || setting["category"].length === 0) {
+  if (typeof setting["category"] !== "string" || !SAFETY_CATEGORY_SET.has(setting["category"])) {
     throw badGoogleProviderOptions(
-      `providerOptions.google.safetySettings[${index}].category must be a non-empty string for model "${model}".`
+      `providerOptions.google.safetySettings[${index}].category must be one of ${GOOGLE_SAFETY_CATEGORIES.join(", ")} for model "${model}".`
     );
   }
-  if (typeof setting["threshold"] !== "string" || setting["threshold"].length === 0) {
+  if (typeof setting["threshold"] !== "string" || !SAFETY_THRESHOLD_SET.has(setting["threshold"])) {
     throw badGoogleProviderOptions(
-      `providerOptions.google.safetySettings[${index}].threshold must be a non-empty string for model "${model}".`
+      `providerOptions.google.safetySettings[${index}].threshold must be one of ${GOOGLE_SAFETY_THRESHOLDS.join(", ")} for model "${model}".`
     );
   }
   return {
@@ -271,11 +1052,28 @@ function parseGoogleSafetySetting(setting, index, model) {
     threshold: setting["threshold"]
   };
 }
+function describeType(value) {
+  return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+function noSchemaWithSearchEvidence(model) {
+  return `Structured output with googleSearch is not supported for model "${model}": no live capture shows Search running when a response schema is attached to this model (the captures cover Gemini 3.x only), so there is no measured behaviour to opt into and providerOptions.google.allowSchemaWithSearch does not apply. Make two calls instead: grounded research without a schema, then structured synthesis (the two-call recipe in docs/grounded-structured.md).`;
+}
+function assertSchemaWithSearchAllowed(model, structuredOutputWithTools, allowSchemaWithSearch, declaredBy) {
+  if (structuredOutputWithTools === void 0) {
+    throw badGoogleProviderOptions(noSchemaWithSearchEvidence(model));
+  }
+  if (allowSchemaWithSearch !== true) {
+    throw badGoogleProviderOptions(
+      `Structured output with googleSearch is not enabled for model "${model}" (Search is declared by ${declaredBy}): the provider accepts the request but Search does not reliably run when a response schema is attached. Make two calls instead: grounded research without a schema, then structured synthesis (the two-call recipe in docs/grounded-structured.md). To send both in one call anyway, set providerOptions.google.allowSchemaWithSearch: true; the call then fails unless the response proves Search ran (requireGrounding), and that failure is not retryable because the same call keeps missing.`
+    );
+  }
+}
 function mapGoogleProviderOptions({
   googleOpts,
   model,
   structuredOutputRequested,
   descriptorGrounding,
+  descriptorCaching,
   structuredOutputWithTools
 }) {
   if (googleOpts === void 0) {
@@ -297,23 +1095,43 @@ function mapGoogleProviderOptions({
     );
   }
   const unknownKeys = Object.keys(googleOpts).filter(
-    (key) => !ALLOWED_GOOGLE_PROVIDER_OPTION_KEYS.has(key) && !RESERVED_GOOGLE_PROVIDER_OPTION_KEYS.has(key)
+    (key) => !ALLOWED_GOOGLE_PROVIDER_OPTION_KEYS.has(key)
   );
   if (unknownKeys.length > 0) {
     throw badGoogleProviderOptions(
       `providerOptions.google contains unsupported keys [${unknownKeys.join(
         ", "
-      )}] for model "${model}". Allowed keys: cachedContent, flexFallback, httpOptions, safetySettings, tools.`
+      )}] for model "${model}". Allowed keys: allowSchemaWithSearch, cachedContent, flexFallback, httpOptions, requireGrounding, safetySettings, tools.`
     );
   }
   const mapped = {};
   if (googleOpts["cachedContent"] !== void 0) {
-    if (typeof googleOpts["cachedContent"] !== "string" || googleOpts["cachedContent"].length === 0) {
+    if (!descriptorCaching) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.cachedContent is not supported for model "${model}": the model has no explicit-caching capability.`
+      );
+    }
+    const cached = googleOpts["cachedContent"];
+    if (typeof cached === "string" && cached.length > 0) {
+      mapped.cachedContent = cached;
+    } else if (isPlainRecord(cached)) {
+      const extraKeys = Object.keys(cached).filter(
+        (key) => key !== "cacheName" && key !== "toolKinds"
+      );
+      const cacheName = cached["cacheName"];
+      const toolKinds = cached["toolKinds"];
+      if (extraKeys.length > 0 || typeof cacheName !== "string" || cacheName.length === 0 || toolKinds !== void 0 && (!Array.isArray(toolKinds) || !toolKinds.every((kind) => typeof kind === "string"))) {
+        throw badGoogleProviderOptions(
+          `providerOptions.google.cachedContent must be a non-empty cache name, or { cacheName: non-empty string, toolKinds?: string[] } and nothing else (pass handle.cacheName and handle.toolKinds, not the whole handle), for model "${model}".`
+        );
+      }
+      mapped.cachedContent = cacheName;
+      if (toolKinds !== void 0) mapped.cachedToolKinds = toolKinds;
+    } else {
       throw badGoogleProviderOptions(
-        `providerOptions.google.cachedContent must be a non-empty string for model "${model}".`
+        `providerOptions.google.cachedContent must be a non-empty cache name, or { cacheName: non-empty string, toolKinds?: string[] }, for model "${model}".`
       );
     }
-    mapped.cachedContent = googleOpts["cachedContent"];
   }
   if (googleOpts["flexFallback"] !== void 0) {
     if (typeof googleOpts["flexFallback"] !== "boolean") {
@@ -341,9 +1159,9 @@ function mapGoogleProviderOptions({
     }
     const timeout = googleOpts["httpOptions"]["timeout"];
     if (timeout !== void 0) {
-      if (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout <= 0) {
+      if (typeof timeout !== "number" || !Number.isInteger(timeout) || timeout <= 0 || timeout > MAX_TIMER_MS) {
         throw badGoogleProviderOptions(
-          `providerOptions.google.httpOptions.timeout must be a positive integer for model "${model}".`
+          `providerOptions.google.httpOptions.timeout must be a positive integer of at most ${MAX_TIMER_MS} ms (the longest delay a Node timer holds; a larger one aborts the call after 1 ms) for model "${model}".`
         );
       }
       mapped.httpOptions = { timeout };
@@ -361,6 +1179,18 @@ function mapGoogleProviderOptions({
       (setting, index) => parseGoogleSafetySetting(setting, index, model)
     );
   }
+  const allowSchemaWithSearch = googleOpts["allowSchemaWithSearch"];
+  if (allowSchemaWithSearch !== void 0 && typeof allowSchemaWithSearch !== "boolean") {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.allowSchemaWithSearch must be a boolean for model "${model}", received ${describeType(allowSchemaWithSearch)}.`
+    );
+  }
+  const requireGrounding = googleOpts["requireGrounding"];
+  if (requireGrounding !== void 0 && typeof requireGrounding !== "boolean") {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.requireGrounding must be a boolean for model "${model}", received ${describeType(requireGrounding)}.`
+    );
+  }
   if (googleOpts["tools"] !== void 0) {
     if (!Array.isArray(googleOpts["tools"])) {
       throw badGoogleProviderOptions(
@@ -374,12 +1204,54 @@ function mapGoogleProviderOptions({
       );
     }
     if (structuredOutputRequested && structuredOutputWithTools !== true) {
-      throw badGoogleProviderOptions(
-        `Structured output with googleSearch is not supported for model "${model}".`
+      assertSchemaWithSearchAllowed(
+        model,
+        structuredOutputWithTools,
+        allowSchemaWithSearch,
+        "providerOptions.google.tools"
       );
     }
     mapped.tools = tools;
   }
+  const searchInCache = mapped.cachedToolKinds?.includes("googleSearch") === true;
+  if (searchInCache) {
+    if (descriptorGrounding !== true) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.cachedContent.toolKinds lists googleSearch, which is not supported for model "${model}": the model does not support grounding.`
+      );
+    }
+    if (structuredOutputRequested && structuredOutputWithTools !== true) {
+      assertSchemaWithSearchAllowed(
+        model,
+        structuredOutputWithTools,
+        allowSchemaWithSearch,
+        "the cache handle (cachedContent.toolKinds)"
+      );
+    }
+  }
+  const searchSent = searchInCache || mapped.tools?.some((tool) => "googleSearch" in tool) === true;
+  if (allowSchemaWithSearch === true) {
+    if (descriptorGrounding !== true) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.allowSchemaWithSearch is not supported for model "${model}": the model does not support grounding.`
+      );
+    }
+    if (!searchSent || !structuredOutputRequested) {
+      throw badGoogleProviderOptions(
+        `providerOptions.google.allowSchemaWithSearch requires both Search (providerOptions.google.tools: [{ googleSearch: {} }], or a cachedContent handle whose toolKinds lists googleSearch) and output.jsonSchema for model "${model}".`
+      );
+    }
+    if (structuredOutputWithTools === void 0) {
+      throw badGoogleProviderOptions(noSchemaWithSearchEvidence(model));
+    }
+  }
+  if (requireGrounding === true && !searchSent) {
+    throw badGoogleProviderOptions(
+      `providerOptions.google.requireGrounding requires Search: providerOptions.google.tools: [{ googleSearch: {} }], or a cachedContent handle whose toolKinds lists googleSearch, for model "${model}".`
+    );
+  }
+  const effectiveRequireGrounding = requireGrounding ?? allowSchemaWithSearch === true;
+  if (effectiveRequireGrounding) mapped.requireGrounding = true;
   return mapped;
 }
 function assertSamplingAllowed(config, model, sampling) {
@@ -403,6 +1275,99 @@ function assertSamplingAllowed(config, model, sampling) {
     );
   }
 }
+var MAX_INLINE_REQUEST_BYTES = 100 * 1024 * 1024;
+var MAX_INLINE_PDF_BYTES = 50 * 1024 * 1024;
+var PDF_MEDIA_TYPES = ["application/pdf"];
+function assertInlinePayloadWithinLimits(contents, system) {
+  let total = system === void 0 ? 0 : utf8ByteLength(system);
+  contents.forEach((content, mi) => {
+    content.parts.forEach((part, pi) => {
+      if ("text" in part) total += utf8ByteLength(part.text);
+      if (!("inlineData" in part)) return;
+      const { mimeType, data } = part.inlineData;
+      total += data.length;
+      if (isMediaTypeAdmitted(mimeType, PDF_MEDIA_TYPES)) {
+        const decoded = Math.floor(data.length * 3 / 4);
+        if (decoded > MAX_INLINE_PDF_BYTES) {
+          throw new LlmError(
+            `messages[${mi}].parts[${pi}] is an inline PDF of about ${decoded} bytes, over Google's 50 MB inline PDF limit. Upload it with GoogleFileStore and send a file-uri part.`,
+            {
+              kind: "bad_request",
+              retryable: false,
+              provider: "google",
+              issues: [
+                {
+                  path: `messages[${mi}].parts[${pi}]`,
+                  message: "inline PDF over 50 MB"
+                }
+              ]
+            }
+          );
+        }
+      }
+    });
+  });
+  if (total > MAX_INLINE_REQUEST_BYTES) {
+    throw new LlmError(
+      `The request carries at least ${total} bytes of inline data and text, over Google's 100 MB request limit. Upload large media with GoogleFileStore and send file-uri parts.`,
+      {
+        kind: "bad_request",
+        retryable: false,
+        provider: "google",
+        issues: [{ path: "messages", message: "request over 100 MB" }]
+      }
+    );
+  }
+}
+var CANDIDATE_METADATA_KEYS = [
+  "finishReason",
+  "finishMessage",
+  "safetyRatings",
+  "citationMetadata",
+  "urlContextMetadata"
+];
+var MAX_FINISH_MESSAGE_CHARS = 512;
+var MAX_METADATA_ARRAY = 50;
+var MAX_METADATA_STRING = 2048;
+var MAX_METADATA_DEPTH = 8;
+var MAX_RATINGS_IN_MESSAGE = 12;
+function truncateText(text, max) {
+  return text.length > max ? `${text.slice(0, max)}\u2026` : text;
+}
+function boundMetadata(value, state, depth = 0) {
+  if (typeof value === "string") {
+    if (value.length > MAX_METADATA_STRING) state.truncated = true;
+    return truncateText(value, MAX_METADATA_STRING);
+  }
+  if (value === null || typeof value !== "object") return value;
+  if (depth >= MAX_METADATA_DEPTH) {
+    state.truncated = true;
+    return null;
+  }
+  if (Array.isArray(value)) {
+    if (value.length > MAX_METADATA_ARRAY) state.truncated = true;
+    return value.slice(0, MAX_METADATA_ARRAY).map((item) => boundMetadata(item, state, depth + 1));
+  }
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (item !== void 0) out[key] = boundMetadata(item, state, depth + 1);
+  }
+  return out;
+}
+function describeSafetyRatings(ratings) {
+  if (!Array.isArray(ratings) || ratings.length === 0) return "";
+  const parts = ratings.slice(0, MAX_RATINGS_IN_MESSAGE).flatMap((rating) => {
+    if (typeof rating !== "object" || rating === null) return [];
+    const { category, probability, blocked } = rating;
+    if (typeof category !== "string") return [];
+    return [
+      `${truncateText(category, 80)}=${typeof probability === "string" ? truncateText(probability, 40) : "unknown"}${blocked === true ? " (blocked)" : ""}`
+    ];
+  });
+  if (parts.length === 0) return "";
+  const more = ratings.length > MAX_RATINGS_IN_MESSAGE ? ` and ${ratings.length - MAX_RATINGS_IN_MESSAGE} more` : "";
+  return `${parts.join(", ")}${more}`;
+}
 function mapFinishReason(raw) {
   if (raw === void 0) return void 0;
   switch (raw) {
@@ -414,7 +1379,10 @@ function mapFinishReason(raw) {
     case "RECITATION":
     case "BLOCKLIST":
     case "PROHIBITED_CONTENT":
+    case "SPII":
     case "IMAGE_SAFETY":
+    case "IMAGE_PROHIBITED_CONTENT":
+    case "IMAGE_RECITATION":
       return "content_filter";
     default:
       return "other";
@@ -437,6 +1405,7 @@ function mapUsage(meta) {
   const candidatesTokenCount = meta?.candidatesTokenCount ?? 0;
   const cachedContentTokenCount = meta?.cachedContentTokenCount;
   const thoughtsTokenCount = meta?.thoughtsTokenCount;
+  const toolUsePromptTokenCount = meta?.toolUsePromptTokenCount;
   const outputTokens = candidatesTokenCount + (thoughtsTokenCount ?? 0);
   const inputTokens = promptTokenCount;
   const totalTokens = meta?.totalTokenCount;
@@ -444,8 +1413,36 @@ function mapUsage(meta) {
     input: inputTokens,
     output: outputTokens,
     ...cachedContentTokenCount !== void 0 ? { cached: cachedContentTokenCount } : {},
-    ...thoughtsTokenCount !== void 0 ? { thinking: thoughtsTokenCount } : {}
+    ...thoughtsTokenCount !== void 0 ? { thinking: thoughtsTokenCount } : {},
+    // Tokens of Search results fed back to the model. They sit in
+    // `totalTokenCount` but outside `promptTokenCount`. Google's pricing page
+    // (read 2026-10) says retrieved search results are not charged
+    // as input tokens, so they are recorded and not priced; no live billing
+    // reconciliation has confirmed it, so the total mismatch still marks the
+    // cost `estimated`.
+    ...toolUsePromptTokenCount !== void 0 ? { tool_use_prompt: toolUsePromptTokenCount } : {}
   };
+  let cachedSplitTokens;
+  for (const [prefix, entries] of [
+    ["input", meta?.promptTokensDetails],
+    ["cached", meta?.cacheTokensDetails]
+  ]) {
+    if (!Array.isArray(entries)) continue;
+    if (prefix === "cached") cachedSplitTokens = 0;
+    for (const entry of entries) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const { modality, tokenCount: count } = entry;
+      if (typeof modality !== "string" || modality === "" || typeof count !== "number" || !Number.isFinite(count) || count < 0) {
+        continue;
+      }
+      const key = `${prefix}_${modality.toLowerCase()}`;
+      details[key] = (details[key] ?? 0) + count;
+      if (prefix === "cached") cachedSplitTokens = (cachedSplitTokens ?? 0) + count;
+    }
+  }
+  if (cachedSplitTokens !== void 0 && cachedContentTokenCount !== void 0 && cachedContentTokenCount > 0 && cachedSplitTokens >= cachedContentTokenCount && details["cached_audio"] === void 0) {
+    details["cached_audio"] = 0;
+  }
   const raw = meta !== void 0 ? meta : null;
   const usage = {
     inputTokens,
@@ -464,10 +1461,20 @@ function mapGoogleToolChoice(choice) {
   if (choice === "none") return { mode: "NONE" };
   return { mode: "ANY", allowedFunctionNames: [choice.name] };
 }
-function mapPart(p) {
+function toFunctionResponseObject(p) {
+  if (p.isError === true) return { error: p.result };
+  if (typeof p.result === "object" && p.result !== null && !Array.isArray(p.result)) {
+    return p.result;
+  }
+  return { output: p.result };
+}
+function mapPart(p, signature) {
   switch (p.kind) {
     case "text":
-      return { text: p.text };
+      return {
+        text: p.text,
+        ...signature !== void 0 ? { thoughtSignature: signature } : {}
+      };
     case "inline-media": {
       return {
         inlineData: {
@@ -494,30 +1501,35 @@ function mapPart(p) {
     case "tool-call":
       return {
         functionCall: {
-          id: p.toolCallId,
+          // A synthesized id never reached Gemini; sending it would only be noise.
+          ...isSynthesizedToolCallId(p.toolCallId) ? {} : { id: p.toolCallId },
           name: p.toolName,
           args: p.args
-        }
+        },
+        ...signature !== void 0 ? { thoughtSignature: signature } : {}
       };
     case "tool-result":
       return {
         functionResponse: {
-          id: p.toolCallId,
+          ...isSynthesizedToolCallId(p.toolCallId) ? {} : { id: p.toolCallId },
           name: p.toolName,
-          response: p.isError === true ? { error: p.result } : p.result
+          response: toFunctionResponseObject(p)
         }
       };
     default:
       return assertNever(p);
   }
 }
-function mapMessagesToGeminiContents(messages) {
-  return messages.map((msg) => ({
+function mapMessagesToGeminiContents(messages, signatures) {
+  return messages.map((msg, mi) => ({
     role: msg.role === "assistant" ? "model" : "user",
-    parts: msg.parts.map(mapPart)
+    parts: msg.parts.map((part, pi) => mapPart(part, signatures?.get(`${mi}:${pi}`)))
   }));
 }
 function geminiAdapter(opts) {
+  return geminiAdapterWithClientFactory(opts?.client, buildGoogleClient);
+}
+function geminiAdapterWithClientFactory(injectedClient, buildClient) {
   return {
     id: "google",
     async run(req, ctx) {
@@ -530,23 +1542,37 @@ function geminiAdapter(opts) {
       const warnings = [];
       const model = req.model;
       const descriptor = req.modelDescriptor;
-      if (descriptor?.model !== model || descriptor.provider !== "google") {
-        throw new LlmError(`No matching Google model descriptor for "${model}".`, {
+      assertModelMatchesDescriptor(req, descriptor, "google");
+      assertInputMimeTypesAdmitted(req.messages, descriptor, "google");
+      const signsHistory = descriptor.capabilities?.providerState === true;
+      if (req.transientProviderState !== void 0 && !signsHistory) {
+        throw new LlmError(`Model "${model}" does not admit transientProviderState.`, {
           kind: "bad_request",
           retryable: false
         });
       }
-      if (req.transientProviderState !== void 0) {
-        throw new LlmError(`Model "${model}" does not admit transientProviderState.`, {
-          kind: "bad_request",
-          retryable: false
+      const resolved = signsHistory ? resolveSignatures(
+        parseSignatureState(req.transientProviderState),
+        req.messages,
+        model
+      ) : void 0;
+      const incomingSignatures = resolved?.kept ?? [];
+      if (resolved !== void 0 && resolved.dropped.length > 0) {
+        warnings.push({
+          type: "other",
+          message: `google: dropped ${resolved.dropped.length} stale text signature(s) from transientProviderState (${resolved.dropped.join("; ")}); Google treats text signatures as optional, so nothing required was lost.`
         });
       }
-      const contents = mapMessagesToGeminiContents(req.messages);
+      const contents = mapMessagesToGeminiContents(
+        req.messages,
+        resolved?.bySlot
+      );
+      const system = req.system !== void 0 && req.system !== "" ? req.system : void 0;
+      assertInlinePayloadWithinLimits(contents, system);
       const genConfig = req.config;
       const config = {};
-      if (req.system !== void 0) {
-        config.systemInstruction = { parts: [{ text: req.system }] };
+      if (system !== void 0) {
+        config.systemInstruction = { parts: [{ text: system }] };
       }
       if (genConfig.temperature !== void 0) {
         config.temperature = genConfig.temperature;
@@ -603,6 +1629,12 @@ function geminiAdapter(opts) {
             );
           }
           const budget = reasoning.budgetTokens !== void 0 ? reasoning.budgetTokens : reasoning.effort !== void 0 ? GOOGLE_REASONING_EFFORT_BUDGET[reasoning.effort] : void 0;
+          if (budget !== void 0 && budget > 0 && genConfig.maxOutputTokens !== void 0 && budget >= genConfig.maxOutputTokens) {
+            warnings.push({
+              type: "other",
+              message: `google: thinkingBudget (${budget}) is not below maxOutputTokens (${genConfig.maxOutputTokens}); thinking may consume the whole cap and leave no answer. Raise maxOutputTokens or lower the reasoning budget.`
+            });
+          }
           config.thinkingConfig = {
             ...budget !== void 0 ? { thinkingBudget: budget } : {},
             ...reasoning.includeThoughts === true ? { includeThoughts: true } : {}
@@ -646,6 +1678,12 @@ function geminiAdapter(opts) {
                 assertNever(reasoning.effort);
             }
           }
+          if (thinkingLevel === "HIGH" && genConfig.maxOutputTokens !== void 0 && genConfig.maxOutputTokens < GOOGLE_HIGH_EFFORT_MIN_OUTPUT_TOKENS) {
+            warnings.push({
+              type: "other",
+              message: `google: reasoning.effort "high" can spend several thousand thinking tokens (measured up to 8,859) and maxOutputTokens is ${genConfig.maxOutputTokens}, below ${GOOGLE_HIGH_EFFORT_MIN_OUTPUT_TOKENS}; thinking may consume the whole cap and leave no answer. Raise maxOutputTokens or lower the effort.`
+            });
+          }
           config.thinkingConfig = {
             ...thinkingLevel !== void 0 ? { thinkingLevel } : {},
             ...reasoning.includeThoughts === true ? { includeThoughts: true } : {}
@@ -659,24 +1697,148 @@ function geminiAdapter(opts) {
       }
       const structuredOutputRequested = req.outputJsonSchema !== void 0;
       if (structuredOutputRequested) {
-        const nativeStructuredOutput = descriptor.capabilities?.nativeStructuredOutput !== false;
-        if (nativeStructuredOutput) {
-          config.responseMimeType = "application/json";
-          config.responseSchema = req.outputJsonSchema;
+        if (descriptor.capabilities?.nativeStructuredOutput === false) {
+          throw new LlmError(
+            `output.jsonSchema is not supported for model "${model}": the model has no native structured output and the Google adapter has no other path.`,
+            {
+              kind: "bad_request",
+              retryable: false,
+              provider: "google",
+              issues: [
+                {
+                  path: "output.jsonSchema",
+                  message: "model has no native structured output"
+                }
+              ]
+            }
+          );
         }
+        assertJsonSchemaProfile(
+          req.outputJsonSchema,
+          "output.jsonSchema",
+          googleJsonSchemaProfile(descriptor.model)
+        );
+        config.responseMimeType = "application/json";
+        config.responseJsonSchema = req.outputJsonSchema;
       }
       const googleProviderConfig = mapGoogleProviderOptions({
         googleOpts: genConfig.providerOptions?.["google"],
         model,
         structuredOutputRequested,
         descriptorGrounding: descriptor.capabilities?.grounding,
+        descriptorCaching: descriptor.capabilities?.caching !== void 0,
         structuredOutputWithTools: descriptor.capabilities?.structuredOutputWithTools
       });
+      const googleSearchSent = googleProviderConfig.tools?.some((tool) => "googleSearch" in tool) === true;
+      const searchDeclared = googleSearchSent || googleProviderConfig.cachedToolKinds?.includes("googleSearch") === true;
+      const requireGrounding = googleProviderConfig.requireGrounding === true;
+      const schemaSearchUndeclared = structuredOutputRequested && !searchDeclared && descriptor.capabilities?.structuredOutputWithTools !== true;
+      const audioRequested = req.messages.some(
+        (message) => message.parts.some(
+          (part) => (part.kind === "inline-media" || part.kind === "file-uri") && part.mimeType.toLowerCase().startsWith("audio/")
+        )
+      );
+      const mapUsageWithAudioMarker = (meta) => {
+        const mapped = mapUsage(meta);
+        if (audioRequested) mapped.details["audio_input_requested"] = 1;
+        return mapped;
+      };
+      const usageFor = (meta, groundingMetadata2) => {
+        const mapped = mapUsageWithAudioMarker(meta);
+        const queries = countWebSearchQueries(groundingMetadata2);
+        if (searchDeclared) {
+          mapped.details["web_search_requested"] = 1;
+          if (queries !== void 0) mapped.details["web_search_calls"] = queries;
+        } else if (groundingMetadata2 !== void 0) {
+          mapped.details["web_search_requested"] = 1;
+          if (queries !== void 0 && queries > 0) {
+            mapped.details["web_search_calls"] = queries;
+          }
+        }
+        return mapped;
+      };
+      const groundingWarnings = (groundingMetadata2) => {
+        if (!searchDeclared) {
+          if (groundingMetadata2 === void 0) return [];
+          const queries = countWebSearchQueries(groundingMetadata2);
+          const undeclaredSearchWarnings = schemaSearchUndeclared && queries !== void 0 && queries > 0 ? [
+            {
+              type: "other",
+              message: `google: this call attached a response schema and the response reports search queries, so Search ran from the cache named in cachedContent. Schema plus Search is not admitted by default for model "${model}" (Search does not reliably run when a schema is attached) and no googleSearch was declared, so nothing checked that it would run or opted in; the result is returned, the Search fee is priced from the observed queries (cost.confidence is "estimated"), and this pattern is unreliable. Declare Search with cachedContent: { cacheName, toolKinds: ['googleSearch'] } together with allowSchemaWithSearch: true (the call then fails unless the response proves Search ran), or use the two-call recipe in docs/grounded-structured.md.`
+            }
+          ] : [];
+          return [
+            ...undeclaredSearchWarnings,
+            {
+              type: "other",
+              message: queries !== void 0 && queries > 0 ? `google: the response reports ${queries} search quer${queries === 1 ? "y" : "ies"} but the request did not declare googleSearch (a cachedContent cache can hold the tool); the Search fee was priced from the observed queries, and cost.confidence is "estimated" because the free allowance is unknowable per call.` : 'google: the response carries groundingMetadata but the request did not declare googleSearch and the metadata names no query, so the number of searches is unknown; grounding fees are not included in cost, so cost.confidence is "estimated".'
+            }
+          ];
+        }
+        if (groundingMetadata2 === void 0) {
+          return [
+            {
+              type: "other",
+              message: 'google: googleSearch was requested (sent, or held by the cache named in cachedContent) but the response carries no groundingMetadata, so Search may not have run, or may have run without being reported; grounding fees are not included in cost, so cost.confidence is "estimated".'
+            }
+          ];
+        }
+        if (countWebSearchQueries(groundingMetadata2) === void 0) {
+          return [
+            {
+              type: "other",
+              message: 'google: groundingMetadata has no webSearchQueries, so the number of searches is unknown; grounding fees are not included in cost, so cost.confidence is "estimated".'
+            }
+          ];
+        }
+        return [];
+      };
+      const modalityWarnings = (meta) => {
+        if (meta === void 0) return [];
+        const warnings2 = [];
+        const { gaps } = promptLanes(mapUsageWithAudioMarker(meta));
+        if (gaps.includes("audio-unreported")) {
+          warnings2.push({
+            type: "other",
+            message: 'google: the request carries audio but usageMetadata.promptTokensDetails reports no AUDIO tokens, so the audio input rate could not be applied; on a model that prices audio apart from text, cost.confidence is "estimated" and the amount can understate.'
+          });
+        }
+        if (gaps.includes("cached-audio-unknown")) {
+          warnings2.push({
+            type: "other",
+            message: 'google: usageMetadata reports cached tokens without showing how many are audio (no AUDIO entry in cacheTokensDetails, and no per-modality prompt split that rules audio out), so audio in the cached content cannot be ruled out; on a model that prices audio apart from text, cost.confidence is "estimated" and the amount can understate.'
+          });
+        }
+        if (gaps.includes("inconsistent")) {
+          warnings2.push({
+            type: "other",
+            message: 'google: the per-modality token counts in usageMetadata contradict each other (audio above the prompt or the cache, or lanes that exceed the prompt); the counts were clamped, and on a model that prices audio apart from text, cost.confidence is "estimated".'
+          });
+        }
+        return warnings2;
+      };
+      const billedFailure = (meta, groundingMetadata2) => {
+        if (meta === void 0) return {};
+        const failureWarnings = [
+          ...groundingWarnings(groundingMetadata2),
+          ...modalityWarnings(meta)
+        ];
+        return {
+          usage: usageFor(meta, groundingMetadata2),
+          ...failureWarnings.length > 0 ? { warnings: failureWarnings } : {}
+        };
+      };
       if (googleProviderConfig.cachedContent !== void 0) {
         config.cachedContent = googleProviderConfig.cachedContent;
       }
       if (googleProviderConfig.httpOptions !== void 0) {
         config.httpOptions = googleProviderConfig.httpOptions;
+        const sdkTimeout = googleProviderConfig.httpOptions.timeout;
+        if (sdkTimeout !== void 0 && genConfig.timeoutMs !== void 0 && sdkTimeout < genConfig.timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS) {
+          throw badGoogleProviderOptions(
+            `providerOptions.google.httpOptions.timeout (${sdkTimeout} ms) must be at least timeoutMs + ${TRANSPORT_TIMEOUT_BUFFER_MS} ms (${genConfig.timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS} ms) for model "${model}": a shorter SDK timer would abort the call before the engine's own timeout and surface a raw SDK abort.`
+          );
+        }
       }
       if (googleProviderConfig.safetySettings !== void 0) {
         config.safetySettings = googleProviderConfig.safetySettings;
@@ -685,7 +1847,7 @@ function geminiAdapter(opts) {
         config.tools = googleProviderConfig.tools;
       }
       if (req.tools !== void 0 && req.tools.length > 0) {
-        if (req.modelDescriptor?.capabilities?.functionCalling !== true) {
+        if (descriptor.capabilities?.functionCalling !== true) {
           throw new LlmError(
             `tools is not supported for google model "${model}" (capabilities.functionCalling is not true).`,
             { kind: "bad_request", retryable: false, provider: "google" }
@@ -693,16 +1855,24 @@ function geminiAdapter(opts) {
         }
         if (googleProviderConfig.tools !== void 0) {
           throw new LlmError(
-            "tools cannot be combined with providerOptions.google.tools (googleSearch) in this iteration.",
+            "tools cannot be combined with providerOptions.google.tools (googleSearch): this adapter does not send function declarations and Search in one request.",
             { kind: "bad_request", retryable: false, provider: "google" }
           );
         }
+        const toolProfile = googleJsonSchemaProfile(descriptor.model);
+        req.tools.forEach((tool, index) => {
+          assertJsonSchemaProfile(
+            tool.inputJsonSchema,
+            `tools[${index}].inputJsonSchema`,
+            toolProfile
+          );
+        });
         config.tools = [
           {
             functionDeclarations: req.tools.map((tool) => ({
               name: tool.name,
               description: tool.description,
-              parameters: tool.inputJsonSchema
+              parametersJsonSchema: tool.inputJsonSchema
             }))
           }
         ];
@@ -712,11 +1882,37 @@ function geminiAdapter(opts) {
           };
         }
       }
-      assertSamplingAllowed(config, model, req.modelDescriptor?.capabilities?.sampling);
+      if (config.cachedContent !== void 0) {
+        const conflicts = [
+          ...system !== void 0 ? ["system"] : [],
+          ...req.tools !== void 0 && req.tools.length > 0 ? ["tools"] : [],
+          ...googleProviderConfig.tools !== void 0 ? ["providerOptions.google.tools"] : []
+        ];
+        if (conflicts.length > 0) {
+          throw new LlmError(
+            `providerOptions.google.cachedContent cannot be combined with ${conflicts.join(
+              " or "
+            )} for model "${model}": Gemini requires the system instruction and tools to be stored in the cache. Put them in GoogleCacheStore.create and omit them from the request.`,
+            {
+              kind: "bad_request",
+              retryable: false,
+              provider: "google",
+              issues: conflicts.map((path) => ({
+                path,
+                message: "cannot be sent with cachedContent"
+              }))
+            }
+          );
+        }
+      }
+      assertSamplingAllowed(config, model, descriptor.capabilities?.sampling);
+      const timers = ctx.scheduler ?? PLATFORM_SCHEDULER;
       let tierTimeoutHandle;
+      let ceilingFiredMs;
       const clearTierTimeout = () => {
+        ceilingFiredMs = void 0;
         if (tierTimeoutHandle !== void 0) {
-          clearTimeout(tierTimeoutHandle);
+          timers.clearTimeout(tierTimeoutHandle);
           tierTimeoutHandle = void 0;
         }
       };
@@ -731,7 +1927,8 @@ function geminiAdapter(opts) {
             `${tierLabel} timeout: call exceeded ${defaultTimeoutMs}ms client-side ceiling (@google/genai #1277 belt-and-suspenders)`,
             "TimeoutError"
           );
-          tierTimeoutHandle = setTimeout(() => {
+          tierTimeoutHandle = timers.setTimeout(() => {
+            ceilingFiredMs = defaultTimeoutMs;
             tierController.abort(timeoutReason);
           }, defaultTimeoutMs);
           config.abortSignal = ctx.signal !== void 0 ? AbortSignal.any([tierController.signal, ctx.signal]) : tierController.signal;
@@ -761,8 +1958,7 @@ function geminiAdapter(opts) {
           contents,
           config: dispatchConfig
         };
-        const buildClient = opts?._clientFactory ?? buildGoogleClient;
-        const client = opts?.client !== void 0 ? opts.client : await buildClient(ctx.auth);
+        const client = injectedClient !== void 0 ? injectedClient : await buildClient(ctx.auth);
         ctx.logger.debug(
           {
             model,
@@ -773,16 +1969,32 @@ function geminiAdapter(opts) {
         );
         return client.models.generateContent(params);
       };
+      const transportTimeoutOf = (rawErr) => {
+        if (ctx.signal?.aborted === true) return void 0;
+        if (ceilingFiredMs !== void 0) {
+          return `Google call hit the ${ceilingFiredMs}ms client-side ceiling`;
+        }
+        const sdkTimeoutMs = config.httpOptions?.timeout;
+        if (sdkTimeoutMs !== void 0 && rawErr instanceof Error && rawErr.name === "AbortError") {
+          return `Google call hit the SDK transport timeout of ${sdkTimeoutMs}ms`;
+        }
+        return void 0;
+      };
       try {
         response = await dispatch();
       } catch (rawErr) {
-        const typed = classifyGoogleError(
-          rawErr,
-          servedServiceTier !== void 0 ? { servedServiceTier } : void 0
-        );
+        const transportTimeout = transportTimeoutOf(rawErr);
+        const typed = classifyGoogleError(rawErr, {
+          ...servedServiceTier !== void 0 ? { servedServiceTier } : {},
+          ...transportTimeout !== void 0 ? { transportTimeout } : {}
+        });
         if (config.serviceTier === "flex" && googleProviderConfig.flexFallback !== false && isGeminiCapacityError(typed)) {
           config.serviceTier = "standard";
           servedServiceTier = "standard";
+          warnings.push({
+            type: "other",
+            message: `google: the flex call hit a capacity error (${typed.httpStatus ?? "no status"}) and was sent again at the standard tier, billed at standard rates.${genConfig.timeoutMs === void 0 ? ` Without timeoutMs the standard attempt runs under the ${STANDARD_DEFAULT_TIMEOUT_MS} ms client-side ceiling, not the flex ${FLEX_DEFAULT_TIMEOUT_MS} ms one.` : ""}`
+          });
           const fallbackTimeout = genConfig.timeoutMs !== void 0 ? genConfig.timeoutMs + TRANSPORT_TIMEOUT_BUFFER_MS : STANDARD_DEFAULT_TIMEOUT_MS;
           config.httpOptions = {
             timeout: fallbackTimeout,
@@ -792,7 +2004,11 @@ function geminiAdapter(opts) {
           try {
             response = await dispatch();
           } catch (fallbackRawErr) {
-            throw classifyGoogleError(fallbackRawErr, { servedServiceTier: "standard" });
+            const fallbackTransportTimeout = transportTimeoutOf(fallbackRawErr);
+            throw classifyGoogleError(fallbackRawErr, {
+              servedServiceTier: "standard",
+              ...fallbackTransportTimeout !== void 0 ? { transportTimeout: fallbackTransportTimeout } : {}
+            });
           }
         } else {
           throw typed;
@@ -811,49 +2027,105 @@ function geminiAdapter(opts) {
         servedServiceTier = echoedTier;
       }
       const hasBlockReason = response.promptFeedback?.blockReason !== void 0;
-      const hasCandidates = response.candidates !== void 0 && response.candidates.length > 0;
-      if (hasBlockReason || !hasCandidates) {
+      const candidate = response.candidates?.[0];
+      if (hasBlockReason || candidate === void 0) {
         const reason = response.promptFeedback?.blockReason ?? "NO_CANDIDATES";
-        throw new LlmError(`Gemini response has no usable candidate: ${reason}`, {
-          kind: hasBlockReason ? "content_filter" : "server",
-          retryable: !hasBlockReason,
-          provider: "google",
-          ...response.usageMetadata !== void 0 ? { usage: mapUsage(response.usageMetadata) } : {},
-          ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
-        });
+        const thoughtTokens = response.usageMetadata?.thoughtsTokenCount ?? 0;
+        const reasoningHint = !hasBlockReason && thoughtTokens > 0 ? `. The call billed ${thoughtTokens} reasoning tokens, and maxOutputTokens (${config.maxOutputTokens ?? "the provider default"}) includes reasoning tokens, so a low cap can be used up by reasoning before any answer is produced` : "";
+        const promptRatings = hasBlockReason ? describeSafetyRatings(response.promptFeedback?.safetyRatings) : "";
+        throw new LlmError(
+          `Gemini response has no usable candidate: ${reason}${promptRatings !== "" ? ` (safetyRatings: ${promptRatings})` : ""}${reasoningHint}`,
+          {
+            kind: hasBlockReason ? "content_filter" : "server",
+            retryable: !hasBlockReason && thoughtTokens === 0,
+            provider: "google",
+            ...billedFailure(response.usageMetadata),
+            ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
+          }
+        );
       }
-      const candidates = response.candidates;
-      if (candidates === void 0 || candidates.length === 0) {
-        throw new LlmError("Gemini response has no usable candidate: NO_CANDIDATES", {
-          kind: "server",
-          retryable: true,
-          provider: "google",
-          ...response.usageMetadata !== void 0 ? { usage: mapUsage(response.usageMetadata) } : {},
-          ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
-        });
+      const groundingMetadata = candidate.groundingMetadata;
+      const parts = candidate.content?.parts ?? [];
+      const callsComplete = candidate.finishReason === void 0 || candidate.finishReason === "STOP";
+      const isFunctionCall = (part) => part.functionCall !== void 0 && typeof part.functionCall.name === "string";
+      const hasAnswer = parts.some(
+        (part) => part.thought !== true && typeof part.text === "string" && part.text.length > 0 || callsComplete && isFunctionCall(part)
+      );
+      const filteredCandidateError = (note) => {
+        const finishMessage = candidate.finishMessage !== void 0 ? truncateText(candidate.finishMessage, MAX_FINISH_MESSAGE_CHARS) : void 0;
+        const ratings = describeSafetyRatings(candidate.safetyRatings);
+        const bounded = { truncated: false };
+        return new LlmError(
+          `Gemini candidate was filtered (finishReason ${candidate.finishReason}${finishMessage !== void 0 ? `: ${finishMessage}` : ""}${ratings !== "" ? `; safetyRatings: ${ratings}` : ""}); ${note}. The attempt was billed.`,
+          {
+            kind: "content_filter",
+            retryable: false,
+            provider: "google",
+            // The raw evidence, bounded: which category blocked, and why.
+            cause: {
+              finishReason: candidate.finishReason ?? null,
+              ...finishMessage !== void 0 ? { finishMessage } : {},
+              ...candidate.safetyRatings !== void 0 ? { safetyRatings: boundMetadata(candidate.safetyRatings, bounded) } : {}
+            },
+            ...billedFailure(response.usageMetadata, groundingMetadata),
+            ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
+          }
+        );
+      };
+      if (mapFinishReason(candidate.finishReason) === "content_filter" && !hasAnswer) {
+        throw filteredCandidateError(
+          "it carries no answer text and no complete tool call"
+        );
       }
-      const candidate = candidates[0];
-      if (candidate === void 0) {
-        throw new LlmError("Gemini response has no usable candidate: NO_CANDIDATES", {
-          kind: "server",
-          retryable: true,
-          provider: "google",
-          ...response.usageMetadata !== void 0 ? { usage: mapUsage(response.usageMetadata) } : {},
-          ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
-        });
+      if (requireGrounding) {
+        const queries = countWebSearchQueries(groundingMetadata);
+        if (groundingMetadata === void 0 || queries === void 0 || queries < 1) {
+          const finishReason2 = mapFinishReason(candidate.finishReason);
+          if (finishReason2 === "content_filter") {
+            throw filteredCandidateError("the grounding check was not applied");
+          }
+          if (candidate.finishReason === void 0 || candidate.finishReason === "STOP") {
+            const why = groundingMetadata === void 0 ? "the response has no groundingMetadata" : queries === void 0 ? "groundingMetadata has no webSearchQueries" : "groundingMetadata reports zero webSearchQueries";
+            const retryable = !structuredOutputRequested;
+            throw new LlmError(
+              `google: requireGrounding is set but there is no evidence that Search ran: ${why}. The attempt was billed for its tokens${retryable ? "; a retry may ground." : "; it is not retryable, because a call with a response schema attached keeps missing (use the two-call recipe in docs/grounded-structured.md)."}`,
+              {
+                kind: "server",
+                retryable,
+                reason: "grounding_missing",
+                provider: "google",
+                ...billedFailure(response.usageMetadata, groundingMetadata),
+                ...servedServiceTier !== void 0 ? { servedServiceTier } : {}
+              }
+            );
+          }
+        }
       }
-      const parts = candidate.content?.parts ?? [];
       const textParts = [];
       const thoughtParts = [];
       const toolCalls = [];
+      const messageParts = [];
+      const issuedSignatures = [];
+      let droppedSignatures = 0;
+      const droppedCalls = [];
       const nameCounts = /* @__PURE__ */ new Map();
-      const reservedIds = reserveProviderToolCallIds(
-        parts.map((part) => part.functionCall?.id)
-      );
+      const reservedIds = reserveProviderToolCallIds([
+        ...parts.map((part) => part.functionCall?.id),
+        ...req.messages.flatMap(
+          (message) => message.parts.flatMap(
+            (part) => part.kind === "tool-call" || part.kind === "tool-result" ? [part.toolCallId] : []
+          )
+        )
+      ]);
       for (const part of parts) {
-        if (part.functionCall !== void 0 && typeof part.functionCall.name === "string") {
+        const signature = typeof part.thoughtSignature === "string" && part.thoughtSignature.length > 0 ? part.thoughtSignature : void 0;
+        let represented = false;
+        if (isFunctionCall(part) && !callsComplete) {
+          droppedCalls.push(part.functionCall?.name ?? "");
+          represented = true;
+        } else if (part.functionCall !== void 0 && typeof part.functionCall.name === "string") {
           const toolName = part.functionCall.name;
-          toolCalls.push({
+          const call = {
             toolCallId: resolveToolCallId(
               part.functionCall.id,
               toolName,
@@ -862,31 +2134,115 @@ function geminiAdapter(opts) {
             ),
             toolName,
             args: part.functionCall.args ?? {}
-          });
+          };
+          toolCalls.push(call);
+          if (signature !== void 0) {
+            issuedSignatures.push({ partIndex: messageParts.length, signature });
+          }
+          messageParts.push({ kind: "tool-call", ...call });
+          represented = true;
         }
         if (part.text !== void 0) {
           if (part.thought === true) {
             thoughtParts.push(part.text);
           } else {
             textParts.push(part.text);
+            if (part.text.length > 0) {
+              if (signature !== void 0 && !represented) {
+                issuedSignatures.push({ partIndex: messageParts.length, signature });
+              }
+              messageParts.push({ kind: "text", text: part.text });
+              represented = true;
+            }
           }
         }
+        if (signature !== void 0 && !represented) droppedSignatures += 1;
+      }
+      if (droppedCalls.length > 0) {
+        const named = droppedCalls.map((name) => `"${name}"`).join(", ");
+        warnings.push({
+          type: "other",
+          message: `google: dropped ${droppedCalls.length} function call(s) (${named}) because the candidate ended with finishReason ${candidate.finishReason ?? "unspecified"}, not STOP: ${candidate.finishReason === "MAX_TOKENS" ? "the call was cut by the output cap and is incomplete" : "a call beside an abnormal stop is not a call to run"}. The result carries no tool call; finishReason is "${mapFinishReason(candidate.finishReason) ?? "other"}".`
+        });
       }
       const text = textParts.join("");
       const reasoningText = thoughtParts.length > 0 ? thoughtParts.join("") : void 0;
+      let transientProviderState;
+      if (signsHistory) {
+        const issued = [];
+        for (const { partIndex, signature } of issuedSignatures) {
+          const part = messageParts[partIndex];
+          try {
+            issued.push(
+              signatureEntry(req.messages.length, partIndex, model, part, signature)
+            );
+          } catch (error) {
+            if (!(error instanceof LlmError)) throw error;
+            warnings.push({
+              type: "other",
+              message: `google: no signature entry for messages.${req.messages.length}.parts.${partIndex} (a "${part.kind}" part): ${error.message} The result is returned without it; ${part.kind === "tool-call" ? "replaying this function call on the next turn will be rejected" : "a text signature is optional, so nothing required is lost"}.`
+            });
+          }
+        }
+        const signatures = [...incomingSignatures, ...issued];
+        if (signatures.length > 0) {
+          transientProviderState = { google: { signatures } };
+        }
+        if (droppedSignatures > 0) {
+          warnings.push({
+            type: "other",
+            message: `google: dropped ${droppedSignatures} thoughtSignature(s) on parts that have no message representation (thought or empty parts); Gemini requires only the function-call ones.`
+          });
+        }
+        const firstCall = messageParts.findIndex((part) => part.kind === "tool-call");
+        if (firstCall !== -1 && !issuedSignatures.some((entry) => entry.partIndex === firstCall)) {
+          warnings.push({
+            type: "other",
+            message: "google: the first function call in this response carries no thoughtSignature; replaying it on the next turn will be rejected."
+          });
+        }
+      }
       let rawStructured;
       if (structuredOutputRequested && text.length > 0) {
         try {
           rawStructured = JSON.parse(text);
         } catch {
+          if (descriptor.model.startsWith("gemma-") && /^\s*```/.test(text)) {
+            warnings.push({
+              type: "other",
+              message: `google: gemma_fenced_json: the answer from "${model}" is wrapped in a markdown code fence, so it is not parseable JSON and outputParsed is false. Gemma 4 fenced 67 of 162 schema answers (41%) in a live probe (2026-10-03) although the schema is native. The text is returned as the model sent it; call again, or unwrap the fence on the host side.`
+            });
+          }
         }
       }
-      const usage = mapUsage(response.usageMetadata);
+      const usage = usageFor(response.usageMetadata, groundingMetadata);
+      if (response.usageMetadata === void 0) {
+        usage.details["usage_missing"] = 1;
+        warnings.push({
+          type: "other",
+          message: 'google: the response carries no usageMetadata, so token usage is unknown; the call is recorded with zero tokens and is not priced (cost.microUsd is null, cost.confidence is "estimated").'
+        });
+      }
       const finishReason = mapFinishReason(candidate.finishReason);
+      warnings.push(...groundingWarnings(groundingMetadata));
+      warnings.push(...modalityWarnings(response.usageMetadata));
+      const answerParts = [];
+      let answerOffset = 0;
+      for (const part of parts) {
+        if (part.thought === true) continue;
+        if (typeof part.text === "string") {
+          answerParts.push({ text: part.text, offset: answerOffset });
+          answerOffset += part.text.length;
+        } else {
+          answerParts.push(void 0);
+        }
+      }
       const result = {
         model,
+        message: { role: "assistant", parts: messageParts },
         usage,
         warnings,
+        ...transientProviderState !== void 0 ? { transientProviderState } : {},
         ...servedServiceTier !== void 0 ? { servedServiceTier } : {},
         ...text.length > 0 ? { text } : {},
         ...reasoningText !== void 0 ? { reasoningText } : {},
@@ -894,24 +2250,59 @@ function geminiAdapter(opts) {
         ...toolCalls.length > 0 ? { toolCalls, finishReason: "tool_calls" } : finishReason !== void 0 ? { finishReason } : {},
         ...response.modelVersion !== void 0 ? { modelVersion: response.modelVersion } : {},
         ...response.responseId !== void 0 ? { responseId: response.responseId } : {},
-        // Build providerMetadata — merge promptFeedback + groundingMetadata when present.
+        // Build providerMetadata — merge promptFeedback + groundingMetadata when
+        // present. `google.searchEntryPoint` is the Search Suggestions widget
+        // Google requires a grounded answer to display.
         ...(() => {
           const pf = response.promptFeedback;
-          const gm = candidate.groundingMetadata;
-          if (pf === void 0 && gm === void 0) return {};
+          const gm = groundingMetadata;
+          const candidateFields = {};
+          const bounded = { truncated: false };
+          for (const key of CANDIDATE_METADATA_KEYS) {
+            const value = candidate[key];
+            if (value === void 0) continue;
+            candidateFields[key] = key === "finishMessage" && typeof value === "string" ? (() => {
+              if (value.length > MAX_FINISH_MESSAGE_CHARS) bounded.truncated = true;
+              return truncateText(value, MAX_FINISH_MESSAGE_CHARS);
+            })() : boundMetadata(value, bounded);
+          }
+          const googleMeta = {};
+          if (Object.keys(candidateFields).length > 0) {
+            googleMeta["candidate"] = candidateFields;
+          }
+          if (pf === void 0 && gm === void 0 && Object.keys(googleMeta).length === 0) {
+            return {};
+          }
           const meta = {};
           if (pf !== void 0) {
-            meta["promptFeedback"] = pf;
+            meta["promptFeedback"] = boundMetadata(pf, bounded);
           }
           if (gm !== void 0) {
-            meta["groundingMetadata"] = gm;
+            const searchEntryPoint = readSearchEntryPoint(gm);
+            if (searchEntryPoint !== void 0) {
+              const { searchEntryPoint: _widget, ...rest } = gm;
+              meta["groundingMetadata"] = boundMetadata(rest, bounded);
+              googleMeta["searchEntryPoint"] = searchEntryPoint;
+            } else {
+              meta["groundingMetadata"] = boundMetadata(gm, bounded);
+            }
           }
+          if (bounded.truncated) {
+            warnings.push({
+              type: "other",
+              message: `google: providerMetadata was truncated (finishMessage over ${MAX_FINISH_MESSAGE_CHARS} characters, a string over ${MAX_METADATA_STRING}, a list over ${MAX_METADATA_ARRAY} entries or nesting over ${MAX_METADATA_DEPTH} levels, in the candidate fields, promptFeedback or groundingMetadata); the citations are built from the full response.`
+            });
+          }
+          if (Object.keys(googleMeta).length > 0) meta["google"] = googleMeta;
           return { providerMetadata: meta };
         })(),
         ...(() => {
-          const gm = candidate.groundingMetadata;
-          if (gm === void 0) return {};
-          const citations = normalizeGroundingCitations(gm);
+          if (groundingMetadata === void 0) return {};
+          const citations = normalizeGroundingCitations(
+            groundingMetadata,
+            answerParts,
+            (message) => warnings.push({ type: "other", message })
+          );
           return citations.length > 0 ? { citations } : {};
         })()
       };
@@ -924,30 +2315,49 @@ function geminiAdapter(opts) {
           { kind: "bad_request", retryable: false }
         );
       }
-      const contents = mapMessagesToGeminiContents(req.messages);
-      const countTools = req.tools !== void 0 && req.tools.length > 0 ? [
-        {
-          functionDeclarations: req.tools.map((tool) => ({
-            name: tool.name,
-            description: tool.description,
-            parameters: tool.inputJsonSchema
-          }))
+      const system = req.system !== void 0 && req.system !== "" ? req.system : void 0;
+      const tools = req.tools !== void 0 && req.tools.length > 0 ? req.tools : void 0;
+      if (tools !== void 0) {
+        const descriptor = ctx.modelDescriptor;
+        if (descriptor !== void 0 && descriptor.capabilities?.functionCalling !== true) {
+          throw new LlmError(
+            `tools is not supported for google model "${req.model}" (capabilities.functionCalling is not true).`,
+            { kind: "bad_request", retryable: false, provider: "google" }
+          );
         }
-      ] : void 0;
+        const toolProfile = googleJsonSchemaProfile(descriptor?.model ?? req.model);
+        tools.forEach((tool, index) => {
+          assertJsonSchemaProfile(
+            tool.inputJsonSchema,
+            `tools[${index}].inputJsonSchema`,
+            toolProfile
+          );
+        });
+      }
+      if (ctx.modelDescriptor !== void 0) {
+        assertInputMimeTypesAdmitted(req.messages, ctx.modelDescriptor, "google");
+      }
+      const contents = mapMessagesToGeminiContents(req.messages);
+      assertInlinePayloadWithinLimits(contents, system);
       const params = {
         model: req.model,
         contents,
-        ...req.system !== void 0 || ctx.signal !== void 0 || countTools !== void 0 ? {
-          config: {
-            ...req.system !== void 0 ? { systemInstruction: { parts: [{ text: req.system }] } } : {},
-            ...ctx.signal !== void 0 ? { abortSignal: ctx.signal } : {},
-            ...countTools !== void 0 ? { tools: countTools } : {}
-          }
-        } : {}
+        ...system !== void 0 ? { systemInstruction: { parts: [{ text: system }] } } : {},
+        ...tools !== void 0 ? {
+          tools: [
+            {
+              functionDeclarations: tools.map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                parametersJsonSchema: tool.inputJsonSchema
+              }))
+            }
+          ]
+        } : {},
+        ...ctx.signal !== void 0 ? { config: { abortSignal: ctx.signal } } : {}
       };
       try {
-        const buildClient = opts?._clientFactory ?? buildGoogleClient;
-        const client = opts?.client !== void 0 ? opts.client : await buildClient(ctx.auth);
+        const client = injectedClient !== void 0 ? injectedClient : await buildClient(ctx.auth);
         const response = await client.models.countTokens(params);
         if (response.totalTokens === void 0) {
           throw new LlmError(
@@ -956,9 +2366,12 @@ function geminiAdapter(opts) {
           );
         }
         const details = response.cachedContentTokenCount !== void 0 ? { cached: response.cachedContentTokenCount } : void 0;
+        const omitsSignatures = ctx.modelDescriptor?.capabilities?.providerState === true && req.messages.some(
+          (message) => message.role === "assistant" && message.parts.some((part) => part.kind === "tool-call")
+        );
         return {
           totalTokens: response.totalTokens,
-          accuracy: "exact",
+          accuracy: omitsSignatures ? "estimated" : "exact",
           ...details !== void 0 ? { details } : {},
           raw: response
         };
@@ -968,129 +2381,52 @@ function geminiAdapter(opts) {
     }
   };
 }
-
-// src/pricing.ts
-var pricingVersion = "gemini-2026-09-25";
-var GEMINI_PRICED_TIERS = ["standard", "flex", "batch"];
-function tiers(standard, flex, batch) {
-  return Object.freeze({ standard, flex, batch });
-}
-var GEMINI_PRICING = Object.freeze({
-  // Gemini 2.5 Pro. Flex/batch cached equals standard on both context bands.
-  "gemini-2.5-pro": tiers(
-    {
-      inputPerM: 125e4,
-      cachedPerM: 125e3,
-      outputPerM: 1e7,
-      gt200k: { inputPerM: 25e5, cachedPerM: 25e4, outputPerM: 15e6 }
-    },
-    {
-      inputPerM: 625e3,
-      cachedPerM: 125e3,
-      outputPerM: 5e6,
-      gt200k: { inputPerM: 125e4, cachedPerM: 25e4, outputPerM: 75e5 }
-    },
-    {
-      inputPerM: 625e3,
-      cachedPerM: 125e3,
-      outputPerM: 5e6,
-      gt200k: { inputPerM: 125e4, cachedPerM: 25e4, outputPerM: 75e5 }
-    }
-  ),
-  // Gemini 2.5 Flash. Flex/batch cached stays $0.03.
-  "gemini-2.5-flash": tiers(
-    { inputPerM: 3e5, cachedPerM: 3e4, outputPerM: 25e5 },
-    { inputPerM: 15e4, cachedPerM: 3e4, outputPerM: 125e4 },
-    { inputPerM: 15e4, cachedPerM: 3e4, outputPerM: 125e4 }
-  ),
-  // Gemini 2.5 Flash-Lite. Flex/batch cached stays $0.01.
-  "gemini-2.5-flash-lite": tiers(
-    { inputPerM: 1e5, cachedPerM: 1e4, outputPerM: 4e5 },
-    { inputPerM: 5e4, cachedPerM: 1e4, outputPerM: 2e5 },
-    { inputPerM: 5e4, cachedPerM: 1e4, outputPerM: 2e5 }
-  ),
-  // Gemini 3.1 Flash-Lite. Flex/batch cached is the published $0.0125.
-  "gemini-3.1-flash-lite": tiers(
-    { inputPerM: 25e4, cachedPerM: 25e3, outputPerM: 15e5 },
-    { inputPerM: 125e3, cachedPerM: 12500, outputPerM: 75e4 },
-    { inputPerM: 125e3, cachedPerM: 12500, outputPerM: 75e4 }
-  ),
-  // Gemini 3.8 / 3.7 / 3.6 Flash intro rates (2026-09-25). Flex/batch cached
-  // is half of the intro cached rate. Re-snapshot on 2027-01-01.
-  "gemini-3.8-flash": tiers(
-    { inputPerM: 75e4, cachedPerM: 75e3, outputPerM: 375e4 },
-    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 },
-    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 }
-  ),
-  "gemini-3.7-flash": tiers(
-    { inputPerM: 75e4, cachedPerM: 75e3, outputPerM: 375e4 },
-    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 },
-    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 }
-  ),
-  "gemini-3.6-flash": tiers(
-    { inputPerM: 75e4, cachedPerM: 75e3, outputPerM: 375e4 },
-    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 },
-    { inputPerM: 375e3, cachedPerM: 37500, outputPerM: 1875e3 }
-  ),
-  // Gemini 3.5 Flash-Lite. Flex/batch cached is the published $0.02, not half of $0.03.
-  "gemini-3.5-flash-lite": tiers(
-    { inputPerM: 3e5, cachedPerM: 3e4, outputPerM: 25e5 },
-    { inputPerM: 15e4, cachedPerM: 2e4, outputPerM: 125e4 },
-    { inputPerM: 15e4, cachedPerM: 2e4, outputPerM: 125e4 }
-  ),
-  // Gemini 3.1 Pro Preview. Flex/batch cached equals standard on both bands.
-  "gemini-3.1-pro-preview": tiers(
-    {
-      inputPerM: 2e6,
-      cachedPerM: 2e5,
-      outputPerM: 12e6,
-      gt200k: { inputPerM: 4e6, cachedPerM: 4e5, outputPerM: 18e6 }
-    },
-    {
-      inputPerM: 1e6,
-      cachedPerM: 2e5,
-      outputPerM: 6e6,
-      gt200k: { inputPerM: 2e6, cachedPerM: 4e5, outputPerM: 9e6 }
-    },
-    {
-      inputPerM: 1e6,
-      cachedPerM: 2e5,
-      outputPerM: 6e6,
-      gt200k: { inputPerM: 2e6, cachedPerM: 4e5, outputPerM: 9e6 }
-    }
-  )
+var cachedContentSchema = z.union([
+  z.string().min(1),
+  z.strictObject({
+    cacheName: z.string().min(1).meta({
+      title: "Cache Name",
+      description: "Google cached content resource name."
+    }),
+    toolKinds: z.array(z.string().min(1)).optional().meta({
+      title: "Tool Kinds",
+      description: "The tool kinds the cache holds (`GoogleCacheHandle.toolKinds`), e.g. googleSearch."
+    })
+  })
+]).optional().meta({
+  title: "Cached Content",
+  description: "Google cached content: the resource name, or { cacheName, toolKinds } from a cache handle."
 });
-function isPricedGeminiTier(tier) {
-  return GEMINI_PRICED_TIERS.includes(tier);
-}
-function lookupGeminiTierRates(model, tier) {
-  const entry = Object.hasOwn(GEMINI_PRICING, model) ? GEMINI_PRICING[model] : void 0;
-  if (entry === void 0) return void 0;
-  if (tier !== void 0 && !isPricedGeminiTier(tier)) return void 0;
-  return entry;
-}
-function resolveGeminiRates(model, tier) {
-  const entry = lookupGeminiTierRates(model, tier);
-  if (entry === void 0) return void 0;
-  const key = tier ?? "standard";
-  return entry[key];
-}
 
-// src/cost.ts
-function geminiPricingSource() {
-  return {
-    version: pricingVersion,
-    price(model, usage, tier) {
-      return computeCost(model, usage, tier, resolveGeminiRates, pricingVersion);
-    },
-    hasModel(model) {
-      return resolveGeminiRates(model, void 0) !== void 0;
-    },
-    listModels() {
-      return Object.keys(GEMINI_PRICING);
-    }
-  };
-}
+// src/model-limits.ts
+var geminiLimits = () => Object.freeze({ contextWindow: 1048576, maxOutputTokens: 65536 });
+var gemma4Limits = () => Object.freeze({ contextWindow: 262144, maxOutputTokens: null });
+var GOOGLE_MODEL_LIMITS = {
+  "gemini-2.5-pro": geminiLimits(),
+  "gemini-2.5-flash": geminiLimits(),
+  "gemini-2.5-flash-lite": geminiLimits(),
+  "gemini-3.1-flash-lite": geminiLimits(),
+  "gemini-3.1-pro-preview": geminiLimits(),
+  "gemini-3.8-flash": geminiLimits(),
+  "gemini-3.7-flash": geminiLimits(),
+  "gemini-3.6-flash": geminiLimits(),
+  "gemini-3.5-flash-lite": geminiLimits(),
+  "gemma-4-31b-it": gemma4Limits(),
+  "gemma-4-26b-a4b-it": gemma4Limits()
+};
+var GEMINI_INPUT_MIME_TYPES = Object.freeze([
+  "application/pdf",
+  "text/*",
+  "image/*",
+  "audio/*",
+  "video/*"
+]);
+var GEMMA_INPUT_MIME_TYPES = Object.freeze([
+  "image/*",
+  "video/*"
+]);
+
+// src/model-config/gemini-2.5-pro.ts
 var Gemini25ProConfigSchema = z.union([
   z.strictObject({
     temperature: z.number().min(0).max(2).optional().meta({
@@ -1106,7 +2442,7 @@ var Gemini25ProConfigSchema = z.union([
       title: "Top K",
       description: "Top-k sampling limit for gemini-2.5-pro."
     }),
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-2.5-pro"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-2.5-pro."
     }),
@@ -1149,25 +2485,26 @@ var Gemini25ProConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 2.5 Pro thinkingBudget configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1186,9 +2523,9 @@ var Gemini25ProConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-2.5-pro."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1221,7 +2558,7 @@ var Gemini25ProConfigSchema = z.union([
       title: "Top K",
       description: "Top-k sampling limit for gemini-2.5-pro."
     }),
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-2.5-pro"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-2.5-pro."
     }),
@@ -1264,25 +2601,26 @@ var Gemini25ProConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 2.5 Pro thinkingBudget configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1301,9 +2639,9 @@ var Gemini25ProConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-2.5-pro."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1338,7 +2676,7 @@ var Gemini25FlashConfigSchema = z.union([
       title: "Top K",
       description: "Top-k sampling limit for gemini-2.5-flash."
     }),
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-2.5-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-2.5-flash."
     }),
@@ -1381,25 +2719,26 @@ var Gemini25FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 2.5 Flash thinkingBudget configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1418,9 +2757,9 @@ var Gemini25FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-2.5-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1453,7 +2792,7 @@ var Gemini25FlashConfigSchema = z.union([
       title: "Top K",
       description: "Top-k sampling limit for gemini-2.5-flash."
     }),
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-2.5-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-2.5-flash."
     }),
@@ -1496,25 +2835,26 @@ var Gemini25FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 2.5 Flash thinkingBudget configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1533,9 +2873,9 @@ var Gemini25FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-2.5-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1570,7 +2910,7 @@ var Gemini25FlashLiteConfigSchema = z.union([
       title: "Top K",
       description: "Top-k sampling limit for gemini-2.5-flash-lite."
     }),
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-2.5-flash-lite"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-2.5-flash-lite."
     }),
@@ -1613,25 +2953,26 @@ var Gemini25FlashLiteConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 2.5 Flash-Lite thinkingBudget configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1650,9 +2991,9 @@ var Gemini25FlashLiteConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-2.5-flash-lite."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1685,7 +3026,7 @@ var Gemini25FlashLiteConfigSchema = z.union([
       title: "Top K",
       description: "Top-k sampling limit for gemini-2.5-flash-lite."
     }),
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-2.5-flash-lite"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-2.5-flash-lite."
     }),
@@ -1728,25 +3069,26 @@ var Gemini25FlashLiteConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 2.5 Flash-Lite thinkingBudget configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1765,9 +3107,9 @@ var Gemini25FlashLiteConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-2.5-flash-lite."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1789,7 +3131,7 @@ var Gemini25FlashLiteConfigSchema = z.union([
 });
 var Gemini31FlashLiteConfigSchema = z.union([
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.1-flash-lite"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.1-flash-lite."
     }),
@@ -1822,25 +3164,30 @@ var Gemini31FlashLiteConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.1 Flash-Lite thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
         }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
+        }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1859,9 +3206,9 @@ var Gemini31FlashLiteConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.1-flash-lite."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1881,7 +3228,7 @@ var Gemini31FlashLiteConfigSchema = z.union([
     })
   }),
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.1-flash-lite"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.1-flash-lite."
     }),
@@ -1914,25 +3261,30 @@ var Gemini31FlashLiteConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.1 Flash-Lite thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
+        }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -1951,9 +3303,9 @@ var Gemini31FlashLiteConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.1-flash-lite."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -1975,7 +3327,9 @@ var Gemini31FlashLiteConfigSchema = z.union([
 });
 var Gemini31ProPreviewConfigSchema = z.union([
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(
+      GOOGLE_MODEL_LIMITS["gemini-3.1-pro-preview"]
+    ).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.1-pro-preview."
     }),
@@ -2008,25 +3362,30 @@ var Gemini31ProPreviewConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.1 Pro Preview thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
         }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
+        }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2045,9 +3404,9 @@ var Gemini31ProPreviewConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.1-pro-preview."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2067,7 +3426,9 @@ var Gemini31ProPreviewConfigSchema = z.union([
     })
   }),
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(
+      GOOGLE_MODEL_LIMITS["gemini-3.1-pro-preview"]
+    ).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.1-pro-preview."
     }),
@@ -2100,25 +3461,30 @@ var Gemini31ProPreviewConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.1 Pro Preview thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
+        }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2137,9 +3503,9 @@ var Gemini31ProPreviewConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.1-pro-preview."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2161,7 +3527,7 @@ var Gemini31ProPreviewConfigSchema = z.union([
 });
 var Gemini35FlashLiteConfigSchema = z.union([
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.5-flash-lite"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.5-flash-lite."
     }),
@@ -2194,25 +3560,30 @@ var Gemini35FlashLiteConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.5 Flash-Lite thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
         }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
+        }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2231,9 +3602,9 @@ var Gemini35FlashLiteConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.5-flash-lite."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2253,7 +3624,7 @@ var Gemini35FlashLiteConfigSchema = z.union([
     })
   }),
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.5-flash-lite"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.5-flash-lite."
     }),
@@ -2286,25 +3657,30 @@ var Gemini35FlashLiteConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.5 Flash-Lite thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
+        }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2323,9 +3699,9 @@ var Gemini35FlashLiteConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.5-flash-lite."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2347,7 +3723,7 @@ var Gemini35FlashLiteConfigSchema = z.union([
 });
 var Gemini36FlashConfigSchema = z.union([
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.6-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.6-flash."
     }),
@@ -2380,25 +3756,30 @@ var Gemini36FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.6 Flash thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
         }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
+        }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2417,9 +3798,9 @@ var Gemini36FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.6-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2439,7 +3820,7 @@ var Gemini36FlashConfigSchema = z.union([
     })
   }),
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.6-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.6-flash."
     }),
@@ -2472,25 +3853,30 @@ var Gemini36FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.6 Flash thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
+        }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2509,9 +3895,9 @@ var Gemini36FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.6-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2533,7 +3919,7 @@ var Gemini36FlashConfigSchema = z.union([
 });
 var Gemini37FlashConfigSchema = z.union([
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.7-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.7-flash."
     }),
@@ -2566,25 +3952,30 @@ var Gemini37FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.7 Flash thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
         }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
+        }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2603,9 +3994,9 @@ var Gemini37FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.7-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2625,7 +4016,7 @@ var Gemini37FlashConfigSchema = z.union([
     })
   }),
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.7-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.7-flash."
     }),
@@ -2658,25 +4049,30 @@ var Gemini37FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.7 Flash thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
+        }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2695,9 +4091,9 @@ var Gemini37FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.7-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2719,7 +4115,7 @@ var Gemini37FlashConfigSchema = z.union([
 });
 var Gemini38FlashConfigSchema = z.union([
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.8-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.8-flash."
     }),
@@ -2752,25 +4148,30 @@ var Gemini38FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.8 Flash thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
         }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
+        }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2789,9 +4190,9 @@ var Gemini38FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.8-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2811,7 +4212,7 @@ var Gemini38FlashConfigSchema = z.union([
     })
   }),
   z.strictObject({
-    maxOutputTokens: z.number().int().positive().optional().meta({
+    maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemini-3.8-flash"]).optional().meta({
       title: "Max Output Tokens",
       description: "Maximum output token cap for gemini-3.8-flash."
     }),
@@ -2844,25 +4245,30 @@ var Gemini38FlashConfigSchema = z.union([
       title: "Reasoning",
       description: "Gemini 3.8 Flash thinkingLevel configuration."
     }),
-    timeoutMs: z.number().int().positive().optional().meta({
+    timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
       title: "Timeout",
       description: "Logical request timeout in milliseconds."
     }),
     providerOptions: z.strictObject({
       google: z.strictObject({
-        cachedContent: z.string().min(1).optional().meta({
-          title: "Cached Content",
-          description: "Google cached content resource name."
+        allowSchemaWithSearch: z.boolean().optional().meta({
+          title: "Allow Schema With Search",
+          description: "Admit googleSearch together with a response schema. Turns requireGrounding on unless it is false."
+        }),
+        requireGrounding: z.boolean().optional().meta({
+          title: "Require Grounding",
+          description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
         }),
+        cachedContent: cachedContentSchema,
         safetySettings: z.array(
           z.strictObject({
-            category: z.string().min(1).meta({
+            category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
               title: "Safety Category",
-              description: "Google safety category identifier."
+              description: "Documented Google safety category."
             }),
-            threshold: z.string().min(1).meta({
+            threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
               title: "Safety Threshold",
-              description: "Google safety threshold identifier."
+              description: "Documented Google safety threshold."
             })
           })
         ).optional().meta({
@@ -2881,9 +4287,9 @@ var Gemini38FlashConfigSchema = z.union([
           description: "Allowlisted Google tools for gemini-3.8-flash."
         }),
         httpOptions: z.strictObject({
-          timeout: z.number().int().positive().optional().meta({
+          timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
             title: "HTTP Timeout",
-            description: "Per-request Google transport timeout in milliseconds."
+            description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
           })
         }).optional().meta({
           title: "HTTP Options",
@@ -2917,7 +4323,7 @@ var Gemma431bItConfigSchema = z.strictObject({
     title: "Top K",
     description: "Top-k sampling limit for gemma-4-31b-it."
   }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
+  maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemma-4-31b-it"]).optional().meta({
     title: "Max Output Tokens",
     description: "Maximum output token cap for gemma-4-31b-it."
   }),
@@ -2946,25 +4352,25 @@ var Gemma431bItConfigSchema = z.strictObject({
     title: "Reasoning",
     description: "Gemma 4 31B IT thinkingLevel configuration."
   }),
-  timeoutMs: z.number().int().positive().optional().meta({
+  timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
     title: "Timeout",
     description: "Logical request timeout in milliseconds."
   }),
   providerOptions: z.strictObject({
     google: z.strictObject({
-      cachedContent: z.string().min(1).optional().meta({
-        title: "Cached Content",
-        description: "Google cached content resource name."
+      requireGrounding: z.boolean().optional().meta({
+        title: "Require Grounding",
+        description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
       }),
       safetySettings: z.array(
         z.strictObject({
-          category: z.string().min(1).meta({
+          category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
             title: "Safety Category",
-            description: "Google safety category identifier."
+            description: "Documented Google safety category."
           }),
-          threshold: z.string().min(1).meta({
+          threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
             title: "Safety Threshold",
-            description: "Google safety threshold identifier."
+            description: "Documented Google safety threshold."
           })
         })
       ).optional().meta({
@@ -2983,9 +4389,9 @@ var Gemma431bItConfigSchema = z.strictObject({
         description: "Allowlisted Google tools for gemma-4-31b-it."
       }),
       httpOptions: z.strictObject({
-        timeout: z.number().int().positive().optional().meta({
+        timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
           title: "HTTP Timeout",
-          description: "Per-request Google transport timeout in milliseconds."
+          description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
         })
       }).optional().meta({
         title: "HTTP Options",
@@ -3018,7 +4424,7 @@ var Gemma426bA4bItConfigSchema = z.strictObject({
     title: "Top K",
     description: "Top-k sampling limit for gemma-4-26b-a4b-it."
   }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
+  maxOutputTokens: maxOutputTokensSchema(GOOGLE_MODEL_LIMITS["gemma-4-26b-a4b-it"]).optional().meta({
     title: "Max Output Tokens",
     description: "Maximum output token cap for gemma-4-26b-a4b-it."
   }),
@@ -3047,25 +4453,25 @@ var Gemma426bA4bItConfigSchema = z.strictObject({
     title: "Reasoning",
     description: "Gemma 4 26B A4B IT thinkingLevel configuration."
   }),
-  timeoutMs: z.number().int().positive().optional().meta({
+  timeoutMs: z.number().int().positive().max(GOOGLE_MAX_TIMEOUT_MS).optional().meta({
     title: "Timeout",
     description: "Logical request timeout in milliseconds."
   }),
   providerOptions: z.strictObject({
     google: z.strictObject({
-      cachedContent: z.string().min(1).optional().meta({
-        title: "Cached Content",
-        description: "Google cached content resource name."
+      requireGrounding: z.boolean().optional().meta({
+        title: "Require Grounding",
+        description: "Fail the call unless the response proves Google Search ran (grounding metadata with at least one query). Judged only on a candidate that finished with STOP: a MAX_TOKENS or other abnormal finish returns with its own finish reason, a filtered one throws content_filter. The error is retryable only when no response schema is attached."
       }),
       safetySettings: z.array(
         z.strictObject({
-          category: z.string().min(1).meta({
+          category: z.enum(GOOGLE_SAFETY_CATEGORIES).meta({
             title: "Safety Category",
-            description: "Google safety category identifier."
+            description: "Documented Google safety category."
           }),
-          threshold: z.string().min(1).meta({
+          threshold: z.enum(GOOGLE_SAFETY_THRESHOLDS).meta({
             title: "Safety Threshold",
-            description: "Google safety threshold identifier."
+            description: "Documented Google safety threshold."
           })
         })
       ).optional().meta({
@@ -3084,9 +4490,9 @@ var Gemma426bA4bItConfigSchema = z.strictObject({
         description: "Allowlisted Google tools for gemma-4-26b-a4b-it."
       }),
       httpOptions: z.strictObject({
-        timeout: z.number().int().positive().optional().meta({
+        timeout: z.number().int().positive().max(MAX_TIMER_MS).optional().meta({
           title: "HTTP Timeout",
-          description: "Per-request Google transport timeout in milliseconds."
+          description: "Per-request Google transport timeout in milliseconds, at most 2147483647; with timeoutMs set, at least timeoutMs + 5000."
         })
       }).optional().meta({
         title: "HTTP Options",
@@ -3124,12 +4530,13 @@ var geminiModelDescriptors = [
   {
     model: "gemini-2.5-pro",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-2.5-pro"],
     pricingFamily: "gemini-2.5-pro",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "budget",
       admittedReasoningEfforts: GEMINI_STANDARD_REASONING_EFFORTS,
       sampling: "tunable",
@@ -3139,18 +4546,20 @@ var geminiModelDescriptors = [
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini25ProConfigSchema,
+    configKeys: toConfigKeys(Gemini25ProConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini25ProConfigSchema),
     validateConfig: zodToStandardSchema(Gemini25ProConfigSchema)
   },
   {
     model: "gemini-2.5-flash",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-2.5-flash"],
     pricingFamily: "gemini-2.5-flash",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "budget",
       admittedReasoningEfforts: GEMINI_LEVEL_WITH_NONE_REASONING_EFFORTS,
       sampling: "tunable",
@@ -3160,18 +4569,20 @@ var geminiModelDescriptors = [
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini25FlashConfigSchema,
+    configKeys: toConfigKeys(Gemini25FlashConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini25FlashConfigSchema),
     validateConfig: zodToStandardSchema(Gemini25FlashConfigSchema)
   },
   {
     model: "gemini-2.5-flash-lite",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-2.5-flash-lite"],
     pricingFamily: "gemini-2.5-flash-lite",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "budget",
       admittedReasoningEfforts: GEMINI_LEVEL_WITH_NONE_REASONING_EFFORTS,
       sampling: "tunable",
@@ -3181,138 +4592,167 @@ var geminiModelDescriptors = [
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini25FlashLiteConfigSchema,
+    configKeys: toConfigKeys(Gemini25FlashLiteConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini25FlashLiteConfigSchema),
     validateConfig: zodToStandardSchema(Gemini25FlashLiteConfigSchema)
   },
   {
     model: "gemini-3.1-flash-lite",
     provider: "google",
+    // Google's deprecations page (https://ai.google.dev/gemini-api/docs/deprecations,
+    // "Page last updated" 2026-10-01, read 2026-10-03) lists a May 7, 2027
+    // shutdown, replacement gemini-3.5-flash-lite.
+    shutdownDate: "2027-05-07",
+    limits: GOOGLE_MODEL_LIMITS["gemini-3.1-flash-lite"],
     pricingFamily: "gemini-3.1-flash-lite",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMINI_LEVEL_WITH_NONE_REASONING_EFFORTS,
       sampling: "fixed",
       caching: { explicit: true, minTokens: 1024 },
       grounding: true,
       functionCalling: true,
-      structuredOutputWithTools: true,
+      structuredOutputWithTools: false,
+      continuation: "history",
+      providerState: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini31FlashLiteConfigSchema,
+    configKeys: toConfigKeys(Gemini31FlashLiteConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini31FlashLiteConfigSchema),
     validateConfig: zodToStandardSchema(Gemini31FlashLiteConfigSchema)
   },
   {
     model: "gemini-3.1-pro-preview",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-3.1-pro-preview"],
     pricingFamily: "gemini-3.1-pro-preview",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMINI_STANDARD_REASONING_EFFORTS,
       sampling: "fixed",
       caching: { explicit: true, minTokens: 1024 },
       grounding: true,
       functionCalling: true,
-      structuredOutputWithTools: true,
+      structuredOutputWithTools: false,
+      continuation: "history",
+      providerState: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini31ProPreviewConfigSchema,
+    configKeys: toConfigKeys(Gemini31ProPreviewConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini31ProPreviewConfigSchema),
     validateConfig: zodToStandardSchema(Gemini31ProPreviewConfigSchema)
   },
   {
     model: "gemini-3.8-flash",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-3.8-flash"],
     pricingFamily: "gemini-3.8-flash",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMINI_STANDARD_REASONING_EFFORTS,
       sampling: "fixed",
       caching: { explicit: true, minTokens: 1024 },
       grounding: true,
       functionCalling: true,
-      structuredOutputWithTools: true,
+      structuredOutputWithTools: false,
+      continuation: "history",
+      providerState: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini38FlashConfigSchema,
+    configKeys: toConfigKeys(Gemini38FlashConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini38FlashConfigSchema),
     validateConfig: zodToStandardSchema(Gemini38FlashConfigSchema)
   },
   {
     model: "gemini-3.7-flash",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-3.7-flash"],
     pricingFamily: "gemini-3.7-flash",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMINI_STANDARD_REASONING_EFFORTS,
       sampling: "fixed",
       caching: { explicit: true, minTokens: 1024 },
       grounding: true,
       functionCalling: true,
-      structuredOutputWithTools: true,
+      structuredOutputWithTools: false,
+      continuation: "history",
+      providerState: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini37FlashConfigSchema,
+    configKeys: toConfigKeys(Gemini37FlashConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini37FlashConfigSchema),
     validateConfig: zodToStandardSchema(Gemini37FlashConfigSchema)
   },
   {
     model: "gemini-3.6-flash",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-3.6-flash"],
     pricingFamily: "gemini-3.6-flash",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMINI_LEVEL_WITH_NONE_REASONING_EFFORTS,
       sampling: "fixed",
       caching: { explicit: true, minTokens: 1024 },
       grounding: true,
       functionCalling: true,
-      structuredOutputWithTools: true,
+      structuredOutputWithTools: false,
+      continuation: "history",
+      providerState: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini36FlashConfigSchema,
+    configKeys: toConfigKeys(Gemini36FlashConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini36FlashConfigSchema),
     validateConfig: zodToStandardSchema(Gemini36FlashConfigSchema)
   },
   {
     model: "gemini-3.5-flash-lite",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemini-3.5-flash-lite"],
     pricingFamily: "gemini-3.5-flash-lite",
     capabilities: {
+      inputMimeTypes: GEMINI_INPUT_MIME_TYPES,
       reasoning: true,
       structuredOutput: true,
       nativeStructuredOutput: true,
-      vision: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMINI_LEVEL_WITH_NONE_REASONING_EFFORTS,
       sampling: "fixed",
       caching: { explicit: true, minTokens: 1024 },
       grounding: true,
       functionCalling: true,
-      structuredOutputWithTools: true,
+      structuredOutputWithTools: false,
+      continuation: "history",
+      providerState: true,
       serviceTiers: ["flex", "standard"]
     },
     configSchema: Gemini35FlashLiteConfigSchema,
+    configKeys: toConfigKeys(Gemini35FlashLiteConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemini35FlashLiteConfigSchema),
     validateConfig: zodToStandardSchema(Gemini35FlashLiteConfigSchema)
   }
@@ -3321,34 +4761,38 @@ var gemmaModelDescriptors = [
   {
     model: "gemma-4-31b-it",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemma-4-31b-it"],
     capabilities: {
+      inputMimeTypes: GEMMA_INPUT_MIME_TYPES,
       reasoning: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMMA_REASONING_EFFORTS,
       structuredOutput: true,
       nativeStructuredOutput: true,
       grounding: true,
-      vision: true,
       sampling: "tunable"
     },
     configSchema: Gemma431bItConfigSchema,
+    configKeys: toConfigKeys(Gemma431bItConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemma431bItConfigSchema),
     validateConfig: zodToStandardSchema(Gemma431bItConfigSchema)
   },
   {
     model: "gemma-4-26b-a4b-it",
     provider: "google",
+    limits: GOOGLE_MODEL_LIMITS["gemma-4-26b-a4b-it"],
     capabilities: {
+      inputMimeTypes: GEMMA_INPUT_MIME_TYPES,
       reasoning: true,
       reasoningApi: "level",
       admittedReasoningEfforts: GEMMA_REASONING_EFFORTS,
       structuredOutput: true,
       nativeStructuredOutput: true,
       grounding: true,
-      vision: true,
       sampling: "tunable"
     },
     configSchema: Gemma426bA4bItConfigSchema,
+    configKeys: toConfigKeys(Gemma426bA4bItConfigSchema),
     configJsonSchema: toConfigJsonSchema(Gemma426bA4bItConfigSchema),
     validateConfig: zodToStandardSchema(Gemma426bA4bItConfigSchema)
   }
@@ -3368,16 +4812,32 @@ function googleProvider(opts) {
 }
 var DEFAULT_INTERVAL_MS = 3e3;
 var DEFAULT_TIMEOUT_MS = 3e5;
-var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var waitOn = (scheduler) => (ms) => {
+  let timer;
+  const promise = new Promise((resolve) => {
+    timer = scheduler.setTimeout(resolve, ms);
+  });
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== void 0) scheduler.clearTimeout(timer);
+    }
+  };
+};
+function pollTimeoutError(name) {
+  return new LlmError(`Timed out waiting for uploaded file "${name}" to become ACTIVE`, {
+    kind: "server",
+    retryable: false,
+    provider: "google"
+  });
+}
 async function buildFilesClient(auth) {
-  const { GoogleGenAI } = await import('@google/genai');
-  const ai = new GoogleGenAI({ apiKey: requireApiKey(auth) });
+  const ai = await newGoogleGenAI(auth);
   return {
     async upload(params) {
-      const fileArg = params.file instanceof Uint8Array ? new Blob(
-        [Uint8Array.from(params.file)],
-        params.config?.mimeType !== void 0 && params.config.mimeType.length > 0 ? { type: params.config.mimeType } : {}
-      ) : params.file;
+      const fileArg = params.file instanceof Uint8Array ? new Blob([Uint8Array.from(params.file)], {
+        ...params.config?.mimeType !== void 0 ? { type: params.config.mimeType } : {}
+      }) : params.file;
       const result = await ai.files.upload({
         file: fileArg,
         ...params.config !== void 0 ? { config: params.config } : {}
@@ -3409,7 +4869,8 @@ var GoogleFileStore = class {
   logger;
   intervalMs;
   timeoutMs;
-  sleep;
+  startWait;
+  scheduler;
   now;
   /** Memoised client promise — built at most once per store instance. */
   clientPromise;
@@ -3420,19 +4881,22 @@ var GoogleFileStore = class {
     this.onDeleteError = opts.onDeleteError ?? ((name, err) => {
       if (this.logger !== void 0) {
         this.logger.error(
-          { name, error: redactSecrets(classifyError(err).message) },
+          { name, error: redactSecrets(classifyGoogleError(err).message) },
           "gemini.file.delete.failed"
         );
       } else {
         console.error(
           `[GoogleFileStore] delete failed for "${name}":`,
-          redactSecrets(classifyError(err).message)
+          redactSecrets(classifyGoogleError(err).message)
         );
       }
     });
     this.intervalMs = opts.poll?.intervalMs ?? DEFAULT_INTERVAL_MS;
     this.timeoutMs = opts.poll?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-    this.sleep = opts.sleep ?? realSleep;
+    this.scheduler = opts.scheduler ?? PLATFORM_SCHEDULER;
+    const customSleep = opts.sleep;
+    this.startWait = customSleep !== void 0 ? (ms) => ({ promise: customSleep(ms), cancel: () => {
+    } }) : waitOn(this.scheduler);
     this.now = opts.now ?? (() => Date.now());
   }
   getClient() {
@@ -3446,23 +4910,41 @@ var GoogleFileStore = class {
    * Upload bytes to the Gemini File API and wait until the file is ACTIVE.
    *
    * @param source  - Raw bytes or Blob.
-   * @param mimeType - IANA media type, e.g. `"image/png"`.
+   * @param mimeType - IANA media type, e.g. `"image/png"`. It must pass the same
+   *   admission rule `generate` applies to a Gemini model's parts (one shared
+   *   function, so a file that uploads can be used): an empty or unadmitted type
+   *   is `bad_request` before any bytes are sent. The string is sent to Google
+   *   unchanged.
    * @param opts    - Optional display name.
    */
   async upload(source, mimeType, opts) {
     const signal = opts?.signal;
+    assertMediaTypeAdmitted(
+      mimeType,
+      GEMINI_INPUT_MIME_TYPES,
+      "mimeType",
+      "google",
+      "a Google file upload"
+    );
     const client = await this.getClient();
+    if (signal?.aborted === true) {
+      throw new LlmError("File upload aborted", { kind: "aborted", retryable: false });
+    }
     let uploadResp;
     try {
-      uploadResp = await client.upload({
-        file: source,
-        config: {
-          mimeType,
-          ...opts?.displayName !== void 0 ? { displayName: opts.displayName } : {}
-        }
-      });
+      uploadResp = await abortable(
+        client.upload({
+          file: source,
+          config: {
+            mimeType,
+            ...opts?.displayName !== void 0 ? { displayName: opts.displayName } : {},
+            ...signal !== void 0 ? { abortSignal: signal } : {}
+          }
+        }),
+        signal
+      );
     } catch (e) {
-      throw classifyError(e);
+      throw classifyGoogleError(e);
     }
     const { name, uri } = uploadResp;
     if (name === void 0 || name.length === 0 || uri === void 0 || uri.length === 0) {
@@ -3477,10 +4959,7 @@ var GoogleFileStore = class {
       return makeHandle(uploadResp, fallback);
     }
     if (uploadResp.state === "FAILED") {
-      throw new LlmError("File processing failed immediately after upload", {
-        kind: "bad_request",
-        retryable: false
-      });
+      throw failedFile("File processing failed immediately after upload", uploadResp);
     }
     const deadline = this.now() + this.timeoutMs;
     if (signal?.aborted === true) {
@@ -3489,49 +4968,102 @@ var GoogleFileStore = class {
         retryable: false
       });
     }
+    let onAbort;
     const abortRacePromise = signal !== void 0 ? new Promise((_, reject) => {
-      signal.addEventListener(
-        "abort",
+      onAbort = () => {
+        reject(
+          new LlmError("File upload polling aborted", {
+            kind: "aborted",
+            retryable: false
+          })
+        );
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }) : void 0;
+    abortRacePromise?.catch(() => {
+    });
+    try {
+      return await this.pollUntilActive(
+        client,
+        name,
+        fallback,
+        deadline,
+        signal,
+        abortRacePromise
+      );
+    } finally {
+      if (signal !== void 0 && onAbort !== void 0) {
+        signal.removeEventListener("abort", onAbort);
+      }
+    }
+  }
+  /**
+   * `work` raced against the abort promise and the time left until `deadline`
+   * (the deadline is a non-retryable `server` error). `work` is observed, so a
+   * late rejection after the race is lost is not unhandled; the deadline timer
+   * is always cleared.
+   */
+  async raceDeadline(work, name, deadline, abortRacePromise) {
+    work.catch(() => {
+    });
+    const remainingMs = deadline - this.now();
+    let deadlineTimer;
+    const deadlineRace = new Promise((_, reject) => {
+      if (remainingMs > MAX_TIMER_MS) return;
+      deadlineTimer = this.scheduler.setTimeout(
         () => {
-          reject(
-            new LlmError("File upload polling aborted", {
-              kind: "aborted",
-              retryable: false
-            })
-          );
+          reject(pollTimeoutError(name));
         },
-        { once: true }
+        Math.max(remainingMs, 0)
       );
-    }) : void 0;
+    });
+    deadlineRace.catch(() => {
+    });
+    try {
+      return await Promise.race(
+        abortRacePromise !== void 0 ? [work, deadlineRace, abortRacePromise] : [work, deadlineRace]
+      );
+    } finally {
+      if (deadlineTimer !== void 0) this.scheduler.clearTimeout(deadlineTimer);
+    }
+  }
+  /** Polls `name` until ACTIVE; see {@link GoogleFileStore.upload}. */
+  async pollUntilActive(client, name, fallback, deadline, signal, abortRacePromise) {
     for (; ; ) {
       if (this.now() >= deadline) {
-        throw new LlmError("Timed out waiting for uploaded file to become ACTIVE", {
-          kind: "timeout",
-          retryable: true
-        });
+        throw pollTimeoutError(name);
       }
-      const sleepCall = this.sleep(this.intervalMs);
-      await (abortRacePromise !== void 0 ? Promise.race([sleepCall, abortRacePromise]) : sleepCall);
-      let pollResp;
+      const wait = this.startWait(this.intervalMs);
       try {
-        pollResp = await client.get({ name });
-      } catch (e) {
-        throw classifyError(e);
+        await this.raceDeadline(wait.promise, name, deadline, abortRacePromise);
+      } finally {
+        wait.cancel();
+      }
+      if (this.now() >= deadline) {
+        throw pollTimeoutError(name);
       }
+      const pollCall = (async () => {
+        try {
+          return await client.get({ name });
+        } catch (e) {
+          throw classifyGoogleError(e);
+        }
+      })();
+      const pollResp = await this.raceDeadline(pollCall, name, deadline, abortRacePromise);
       if (signal?.aborted === true) {
         throw new LlmError("File upload polling aborted", {
           kind: "aborted",
           retryable: false
         });
       }
+      if (this.now() >= deadline) {
+        throw pollTimeoutError(name);
+      }
       if (pollResp.state === "ACTIVE") {
         return makeHandle(pollResp, fallback);
       }
       if (pollResp.state === "FAILED") {
-        throw new LlmError("File processing failed during polling", {
-          kind: "bad_request",
-          retryable: false
-        });
+        throw failedFile("File processing failed during polling", pollResp);
       }
     }
   }
@@ -3568,15 +5100,7 @@ var GoogleFileStore = class {
       if (isGoogleNotFoundError(err)) {
         return;
       }
-      const classified = err instanceof LlmError ? err : classifyError(err);
-      const withProvider = classified.provider === void 0 ? new LlmError(classified.message, {
-        kind: classified.kind,
-        retryable: classified.retryable,
-        ...classified.httpStatus !== void 0 ? { httpStatus: classified.httpStatus } : {},
-        ...classified.retryAfterMs !== void 0 ? { retryAfterMs: classified.retryAfterMs } : {},
-        provider: "google",
-        cause: classified.cause ?? err
-      }) : classified;
+      const withProvider = classifyGoogleError(err);
       if (failClosed) {
         throw withProvider;
       }
@@ -3598,31 +5122,58 @@ var GoogleFileStore = class {
     await Promise.allSettled(handles.map((h) => this.delete(h, opts)));
   }
 };
-function isGoogleNotFoundError(err) {
-  if (err instanceof LlmError && err.httpStatus === 404) {
-    return true;
-  }
-  if (typeof err !== "object" || err === null) {
-    return false;
-  }
-  const obj = err;
-  if (obj["status"] === 404 || obj["httpStatus"] === 404 || obj["code"] === 404) {
-    return true;
-  }
-  if (obj["status"] === "NOT_FOUND" || obj["code"] === "NOT_FOUND") {
-    return true;
-  }
-  const msg = typeof obj["message"] === "string" ? obj["message"] : "";
-  if (/not\s*found|404/i.test(msg) && /file/i.test(msg)) {
-    return true;
+var TRANSIENT_FILE_STATUS_CODES = /* @__PURE__ */ new Set([4, 13, 14]);
+function failedFile(prefix, resp) {
+  const providerMessage = resp.error?.message;
+  const transient = typeof resp.error?.code === "number" && TRANSIENT_FILE_STATUS_CODES.has(resp.error.code);
+  return new LlmError(
+    providerMessage !== void 0 && providerMessage.length > 0 ? `${prefix}: ${providerMessage}` : prefix,
+    {
+      kind: transient ? "server" : "bad_request",
+      retryable: transient,
+      provider: "google",
+      ...resp.error !== void 0 ? { cause: resp.error } : {}
+    }
+  );
+}
+async function abortable(promise, signal) {
+  if (signal === void 0) return promise;
+  promise.catch(() => {
+  });
+  let onAbort;
+  const aborted = new Promise((_, reject) => {
+    onAbort = () => {
+      reject(new LlmError("File upload aborted", { kind: "aborted", retryable: false }));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+  try {
+    return await Promise.race([promise, aborted]);
+  } finally {
+    if (onAbort !== void 0) signal.removeEventListener("abort", onAbort);
   }
-  return false;
 }
 var DEFAULT_SKEW_SECONDS = 30;
 var DEFAULT_EXTENSION_SECONDS = 3600;
+function toolKindsOf(tools) {
+  const kinds = /* @__PURE__ */ new Set();
+  for (const tool of tools ?? []) {
+    for (const [kind, value] of Object.entries(tool)) {
+      if (value !== void 0) kinds.add(kind);
+    }
+  }
+  return [...kinds];
+}
+function expiryOf(expireTime, fallbackMs) {
+  if (expireTime !== void 0 && expireTime.length > 0) {
+    const parsed = new Date(expireTime);
+    if (!Number.isNaN(parsed.getTime())) return parsed;
+  }
+  return new Date(fallbackMs);
+}
 async function buildCachesClient(auth) {
-  const { GoogleGenAI } = await import('@google/genai');
-  const ai = new GoogleGenAI({ apiKey: requireApiKey(auth) });
+  const ai = await newGoogleGenAI(auth);
   return {
     async create(params) {
       const result = await ai.caches.create(params);
@@ -3661,13 +5212,13 @@ var GoogleCacheStore = class {
     this.onDeleteError = opts.onDeleteError ?? ((cacheName, err) => {
       if (this.logger !== void 0) {
         this.logger.error(
-          { name: cacheName, error: redactSecrets(classifyError(err).message) },
+          { name: cacheName, error: redactSecrets(classifyGoogleError(err).message) },
           "gemini.cache.delete.failed"
         );
       } else {
         console.error(
           `[GoogleCacheStore] delete failed for "${cacheName}":`,
-          redactSecrets(classifyError(err).message)
+          redactSecrets(classifyGoogleError(err).message)
         );
       }
     });
@@ -3692,11 +5243,18 @@ var GoogleCacheStore = class {
    * `now + ttlSeconds * 1000`.
    */
   async create(input) {
+    if (!Number.isInteger(input.ttlSeconds) || input.ttlSeconds <= 0) {
+      throw new LlmError(
+        `GoogleCacheStore.create: ttlSeconds must be a positive integer, got ${String(input.ttlSeconds)}.`,
+        { kind: "bad_request", retryable: false, provider: "google" }
+      );
+    }
     if (this.preflight !== void 0) {
       const counted = await this.preflight.countTokens({
         model: input.model,
         ...input.contents !== void 0 ? { contents: input.contents } : {},
-        ...input.systemInstruction !== void 0 ? { systemInstruction: input.systemInstruction } : {}
+        ...input.systemInstruction !== void 0 ? { systemInstruction: input.systemInstruction } : {},
+        ...input.tools !== void 0 ? { tools: input.tools } : {}
       });
       if (counted < this.preflight.minTokens) {
         throw new LlmError(
@@ -3710,12 +5268,14 @@ var GoogleCacheStore = class {
     if (input.contents !== void 0) config.contents = input.contents;
     if (input.systemInstruction !== void 0)
       config.systemInstruction = input.systemInstruction;
+    if (input.tools !== void 0) config.tools = input.tools;
+    if (input.toolConfig !== void 0) config.toolConfig = input.toolConfig;
     if (input.displayName !== void 0) config.displayName = input.displayName;
     let resp;
     try {
       resp = await client.create({ model: input.model, config });
     } catch (e) {
-      throw classifyError(e);
+      throw classifyGoogleError(e);
     }
     if (resp.name === void 0 || resp.name.length === 0) {
       throw new LlmError("Cache create response missing required field: name", {
@@ -3724,12 +5284,14 @@ var GoogleCacheStore = class {
         provider: "google"
       });
     }
-    const fallbackExpiry = new Date(this.now() + input.ttlSeconds * 1e3);
-    const expiresAt = resp.expireTime !== void 0 && resp.expireTime.length > 0 ? new Date(resp.expireTime) : fallbackExpiry;
+    const expiresAt = expiryOf(resp.expireTime, this.now() + input.ttlSeconds * 1e3);
+    const totalTokenCount = resp.usageMetadata?.totalTokenCount;
     return {
       cacheName: resp.name,
       model: resp.model ?? input.model,
-      expiresAt
+      expiresAt,
+      ...typeof totalTokenCount === "number" && Number.isFinite(totalTokenCount) ? { totalTokenCount } : {},
+      toolKinds: toolKindsOf(input.tools)
     };
   }
   /**
@@ -3744,8 +5306,9 @@ var GoogleCacheStore = class {
   async getOrCreate(key, factory) {
     const mapKey = `${key.model}:${key.stableKey}`;
     const existing = this.entries.get(mapKey);
-    if (existing !== void 0 && this.isLive(existing.handle)) {
-      return existing.handle;
+    if (existing !== void 0) {
+      if (this.isLive(existing.handle)) return existing.handle;
+      this.entries.delete(mapKey);
     }
     if (this.coalesce) {
       const inFlight = this.inflight.get(mapKey);
@@ -3759,7 +5322,9 @@ var GoogleCacheStore = class {
         model: key.model,
         ttlSeconds: factoryResult.ttlSeconds,
         ...factoryResult.contents !== void 0 ? { contents: factoryResult.contents } : {},
-        ...factoryResult.systemInstruction !== void 0 ? { systemInstruction: factoryResult.systemInstruction } : {}
+        ...factoryResult.systemInstruction !== void 0 ? { systemInstruction: factoryResult.systemInstruction } : {},
+        ...factoryResult.tools !== void 0 ? { tools: factoryResult.tools } : {},
+        ...factoryResult.toolConfig !== void 0 ? { toolConfig: factoryResult.toolConfig } : {}
       });
       this.entries.set(mapKey, { handle, ttlSeconds: factoryResult.ttlSeconds });
       return handle;
@@ -3806,12 +5371,13 @@ var GoogleCacheStore = class {
         name: handle.cacheName,
         config: { ttl: `${extensionSeconds}s` }
       });
-      const fallbackExpiry = new Date(this.now() + extensionSeconds * 1e3);
-      const newExpiresAt = resp.expireTime !== void 0 && resp.expireTime.length > 0 ? new Date(resp.expireTime) : fallbackExpiry;
+      const newExpiresAt = expiryOf(resp.expireTime, this.now() + extensionSeconds * 1e3);
       const newHandle = {
         cacheName: handle.cacheName,
         model: handle.model,
-        expiresAt: newExpiresAt
+        expiresAt: newExpiresAt,
+        ...handle.totalTokenCount !== void 0 ? { totalTokenCount: handle.totalTokenCount } : {},
+        ...handle.toolKinds !== void 0 ? { toolKinds: handle.toolKinds } : {}
       };
       for (const [k, entry] of this.entries.entries()) {
         if (entry.handle.cacheName === handle.cacheName) {
@@ -3825,9 +5391,11 @@ var GoogleCacheStore = class {
     }
   }
   /**
-   * Delete a cached content resource.
+   * Delete a cached content resource. Idempotent: a cache that is already gone
+   * (HTTP 404, or the 403 `CachedContent not found` Google sends for an expired
+   * one) is success, not an error.
    *
-   * Errors are forwarded to `onDeleteError` and NOT rethrown.
+   * Any other error is forwarded to `onDeleteError` and NOT rethrown.
    * The handle is removed from the in-process entries map regardless.
    */
   async delete(handle) {
@@ -3841,6 +5409,7 @@ var GoogleCacheStore = class {
       const client = await this.getClient();
       await client.delete({ name: handle.cacheName });
     } catch (err) {
+      if (isGoogleNotFoundError(err)) return;
       this.onDeleteError(handle.cacheName, err);
     }
   }
@@ -3882,7 +5451,7 @@ function convertMediaResolution(mediaResolution, location) {
   return mapMediaResolutionLevel(mediaResolution.level, location);
 }
 function convertPart(part, location, nameCounts, reservedIds) {
-  const keys = definedKeys(part);
+  const keys = definedKeys(part).filter((key) => key !== "thoughtSignature");
   const baseKeys = keys.filter(
     (key) => key === "text" || key === "inlineData" || key === "fileData"
   );
@@ -3991,6 +5560,20 @@ function convertPart(part, location, nameCounts, reservedIds) {
   }
   throw badRequest(`${location}: Part has no recognized fields set.`);
 }
+function convertPartWithSignature(part, location, role, nameCounts, reservedIds) {
+  const converted = convertPart(part, location, nameCounts, reservedIds);
+  const signature = part.thoughtSignature;
+  if (signature === void 0) return { part: converted };
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw badRequest(`${location}: Part.thoughtSignature must be a non-empty string.`);
+  }
+  if (role !== "assistant" || converted.kind !== "text" && converted.kind !== "tool-call") {
+    throw badRequest(
+      `${location}: Part.thoughtSignature can only be imported from a model text or functionCall part.`
+    );
+  }
+  return { part: converted, signature };
+}
 function convertRole(role, location) {
   if (role === "user") return "user";
   if (role === "model") return "assistant";
@@ -4036,6 +5619,7 @@ function geminiContentToMessages(input) {
       })
     )
   );
+  const signatures = [];
   const messages = input.contents.map((content, contentIndex) => {
     const location = `contents[${contentIndex}]`;
     const envelopeExtraKeys = definedKeys(content).filter(
@@ -4047,14 +5631,42 @@ function geminiContentToMessages(input) {
       );
     }
     const role = convertRole(content.role, location);
-    const parts = (content.parts ?? []).map(
-      (part, partIndex) => convertPart(part, `${location}.parts[${partIndex}]`, nameCounts, reservedIds)
-    );
+    const parts = (content.parts ?? []).map((part, partIndex) => {
+      const partLocation = `${location}.parts[${partIndex}]`;
+      const converted = convertPartWithSignature(
+        part,
+        partLocation,
+        role,
+        nameCounts,
+        reservedIds
+      );
+      if (converted.signature !== void 0) {
+        if (input.model === void 0) {
+          throw badRequest(
+            `${partLocation}: Part.thoughtSignature requires the \`model\` input; a signature is bound to the model that issued it.`
+          );
+        }
+        signatures.push(
+          signatureEntry(
+            contentIndex,
+            partIndex,
+            input.model,
+            converted.part,
+            converted.signature
+          )
+        );
+      }
+      return converted.part;
+    });
     return { role, parts };
   });
-  return { ...system !== void 0 ? { system } : {}, messages };
+  return {
+    ...system !== void 0 ? { system } : {},
+    messages,
+    ...signatures.length > 0 ? { transientProviderState: { google: { signatures } } } : {}
+  };
 }
 
-export { FLEX_DEFAULT_TIMEOUT_MS, GEMINI_PRICED_TIERS, GEMINI_PRICING, GoogleCacheStore, GoogleFileStore, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey, resolveGeminiRates };
+export { FLEX_DEFAULT_TIMEOUT_MS, GEMINI_GROUNDING_PRICING, GEMINI_INPUT_MIME_TYPES, GEMINI_PRICED_TIERS, GEMINI_PRICING, GoogleCacheStore, GoogleFileStore, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, classifyGoogleError, defaultGeminiRegistry, dropMessagesFromSignatureState, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey, resolveGeminiRates };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map