@gullabs/google 0.13.0 → 0.16.0

package/dist/index.d.ts

@@ -1,5 +1,267 @@
-import { AuthMaterial, ProviderAdapter, ProviderPlugin, ModelRegistry, ModelDescriptor, PricingSource, ModelRates, LlmError, Logger, Message } from '@gullabs/core';
-import { Content } from '@google/genai';
+import { AuthMaterial, Logger, ProviderAdapter, LlmError, ProviderPlugin, ModelRegistry, ModelDescriptor, PricingSource, ModelRates, Scheduler, Message, JsonValue } from '@gullabs/core';
+import { Content, Tool, ToolConfig } from '@google/genai';
+
+/**
+ * GoogleCacheStore — thin wrapper over the Gemini Context Cache API.
+ *
+ * Manages create / get-or-create / refresh / delete lifecycle for cached
+ * contents.  In-memory cache entries are PROCESS-SCOPED; they are not shared
+ * across processes, workers, or restarts.
+ *
+ * Injectable client and `now` function keep tests free of network and clock.
+ *
+ * @module
+ */
+
+/**
+ * A handle to a cached content resource in the Gemini Context Cache API.
+ *
+ * Pass `cacheName` as `providerOptions.google.cachedContent` in LlmRequest.
+ */
+interface GoogleCacheHandle {
+    /** Resource name, e.g. "cachedContents/xyz". */
+    cacheName: string;
+    /**
+     * Local view of when the cache expires (server-authoritative; computed from
+     * ttl or parsed from the server response `expireTime`).
+     */
+    expiresAt: Date;
+    /** Caches are model-bound; never use a handle with a different model. */
+    model: string;
+    /**
+     * Tokens the cache holds, from `usageMetadata.totalTokenCount` of the create
+     * response. Cache storage is billed per token-hour (see Google's pricing page)
+     * and no usage record carries it, so a host that prices storage reads this.
+     * Absent when the response had no `usageMetadata`. Kept across a TTL refresh.
+     */
+    totalTokenCount?: number;
+    /**
+     * The kinds of tool the cache holds, from the `tools` given to `create` (the
+     * keys of each `Tool`: `googleSearch`, `functionDeclarations`, ...); empty when
+     * it holds none. Pass it with the name as
+     * `providerOptions.google.cachedContent: { cacheName, toolKinds }` so a cached
+     * `googleSearch` is priced as Search: the request carries no tool, so nothing
+     * else says Search runs. Absent on a handle built by hand, where the content of
+     * the cache is unknown. Kept across a TTL refresh.
+     */
+    toolKinds?: readonly string[];
+}
+/** Key used to look up or create an entry in the in-process cache map. */
+interface CacheKey {
+    model: string;
+    /** Caller-chosen stable identifier, e.g. a hash of the cached content. */
+    stableKey: string;
+}
+/**
+ * Minimal structural interface for the Gemini Caches client surface we use.
+ * Satisfied by the real `ai.caches` object or a test fake.
+ */
+interface GeminiCachesClientLike {
+    create(params: {
+        model: string;
+        config: {
+            contents?: Content[];
+            systemInstruction?: Content | string;
+            tools?: Tool[];
+            toolConfig?: ToolConfig;
+            ttl?: string;
+            displayName?: string;
+        };
+    }): Promise<{
+        name?: string;
+        model?: string;
+        expireTime?: string;
+        usageMetadata?: {
+            totalTokenCount?: number;
+        };
+    }>;
+    update(params: {
+        name: string;
+        config: {
+            ttl?: string;
+            expireTime?: string;
+        };
+    }): Promise<{
+        name?: string;
+        expireTime?: string;
+    }>;
+    delete(params: {
+        name: string;
+    }): Promise<unknown>;
+}
+interface GoogleCacheStoreOptions {
+    auth: AuthMaterial;
+    /** Injectable client for tests; skips SDK import when provided. */
+    client?: GeminiCachesClientLike;
+    /**
+     * When true, concurrent `getOrCreate` calls for the same key share one
+     * in-flight create.  Default false.
+     */
+    coalesce?: boolean;
+    /**
+     * Subtracted from the local expiry so we stop using a cache slightly before
+     * the server evicts it.  Default 30 s.
+     */
+    expirySkewSeconds?: number;
+    /** Called on delete failures instead of rethrowing. */
+    onDeleteError?: (cacheName: string, err: unknown) => void;
+    /** Optional structured logger. When provided, routes delete failures to logger.error. */
+    logger?: Logger;
+    /** Injectable clock for deterministic tests.  Default: `Date.now`. */
+    now?: () => number;
+    /**
+     * Opt-in pre-flight token-count gate applied before every cache create
+     * (both `create()` directly and the `getOrCreate()` path it delegates to,
+     * including the coalesced path — enforced once, inside `create()`, so
+     * there is no separate "in-flight" gap to close).
+     */
+    preflight?: {
+        /** Minimum token count required before a cache create is allowed to proceed. */
+        minTokens: number;
+        /**
+         * Counts tokens for the exact token-bearing payload of the impending
+         * create — `model` + `contents` + `systemInstruction` + `tools` only.
+         * `toolConfig`, `ttl` and `displayName` are excluded: they carry no tokens
+         * and are irrelevant to the pre-flight check.
+         *
+         * This callback receives genai-native `Content[]`/`Content|string` — it
+         * does NOT receive the library's `Message[]` shape and there is no
+         * automatic conversion between the two (explicit seam, by design). Hosts
+         * using genai-native content directly can wire this to a raw
+         * `client.models.countTokens` call; hosts building from the library's
+         * `Message[]` should call `@gullabs/core`'s `client.countTokens` rather
+         * than expecting this callback to convert for them.
+         */
+        countTokens: (payload: {
+            model: string;
+            contents?: Content[];
+            systemInstruction?: Content | string;
+            tools?: Tool[];
+        }) => Promise<number>;
+    };
+}
+/**
+ * Process-scoped helper for the Gemini Context Cache API.
+ *
+ * NOTE: `getOrCreate` reuse is PROCESS-SCOPED only.  Entries survive only for
+ * the lifetime of this `GoogleCacheStore` instance.  Across restarts, new
+ * caches will be created (and old ones will be server-evicted after their TTL).
+ *
+ * **Auth snapshot note:** this store captures the `AuthMaterial` at construction
+ * time and memoizes a single SDK client from it (`clientPromise`).  This is
+ * correct and sufficient for static API keys.  If refreshable credentials
+ * (short-lived OAuth/STS tokens) are added in the future, this memoization is
+ * the seam that will need rework: the cached client would hold stale credentials
+ * for the lifetime of a long-lived store instance.  At that point, the store
+ * will need to either rebuild the client on each operation or accept a
+ * credential-resolver callback rather than a plain `AuthMaterial` value.
+ * See ADR-020 in DECISIONS.md.
+ */
+declare class GoogleCacheStore {
+    private readonly auth;
+    private readonly clientOverride;
+    private readonly coalesce;
+    private readonly skewMs;
+    private readonly onDeleteError;
+    private readonly logger;
+    private readonly now;
+    private readonly preflight;
+    /** Memoised client promise — built at most once per store instance. */
+    private clientPromise;
+    /** In-process cache of live handles, keyed by `${model}:${stableKey}`. */
+    private readonly entries;
+    /** In-flight create promises when coalescing is enabled. */
+    private readonly inflight;
+    constructor(opts: GoogleCacheStoreOptions);
+    private getClient;
+    private isLive;
+    /**
+     * Create a new cached content resource.
+     *
+     * The `expiresAt` on the returned handle is computed from the server's
+     * `expireTime` when available, with a local-clock fallback of
+     * `now + ttlSeconds * 1000`.
+     */
+    create(input: {
+        model: string;
+        ttlSeconds: number;
+        contents?: Content[];
+        systemInstruction?: Content | string;
+        /**
+         * Tool declarations to store in the cache. Gemini rejects a request that
+         * sends `tools` or `toolConfig` together with `cachedContent`, so a cache
+         * used by a tool-calling call must hold them (the adapter rejects the
+         * combination before dispatch).
+         */
+        tools?: Tool[];
+        toolConfig?: ToolConfig;
+        displayName?: string;
+    }): Promise<GoogleCacheHandle>;
+    /**
+     * Return a live cached-content handle, creating one if none exists or the
+     * cached entry has expired (accounting for skew).
+     *
+     * Reuse is PROCESS-SCOPED only — this store instance's in-memory map.
+     *
+     * When `coalesce` is enabled, concurrent calls for the same key share one
+     * in-flight create.
+     */
+    getOrCreate(key: CacheKey, factory: () => Promise<{
+        ttlSeconds: number;
+        contents?: Content[];
+        systemInstruction?: Content | string;
+        tools?: Tool[];
+        toolConfig?: ToolConfig;
+    }>): Promise<GoogleCacheHandle>;
+    /**
+     * Extend the cache TTL if it will expire within `thresholdSeconds`.
+     *
+     * Fail-open: if the update call throws, the original handle is returned
+     * unchanged.  This method NEVER throws.
+     *
+     * @param handle - Handle to potentially refresh.
+     * @param opts.thresholdSeconds - Extend if expiry is within this many seconds.
+     *   Default 300.
+     * @param opts.extensionSeconds - New TTL to set.  Default: original TTL from
+     *   entries map, or 3600 s when the handle was not created via `getOrCreate`.
+     */
+    refreshIfExpiringSoon(handle: GoogleCacheHandle, opts?: {
+        thresholdSeconds?: number;
+        extensionSeconds?: number;
+    }): Promise<GoogleCacheHandle>;
+    /**
+     * 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.
+     *
+     * Any other error is forwarded to `onDeleteError` and NOT rethrown.
+     * The handle is removed from the in-process entries map regardless.
+     */
+    delete(handle: GoogleCacheHandle): Promise<void>;
+}
+
+/**
+ * The `safetySettings` categories and thresholds Gemini documents.
+ *
+ * Sources, read 2026-10-03:
+ *
+ * - Categories: ai.google.dev/api/generate-content (`HarmCategory`: hate speech,
+ *   sexually explicit, dangerous content, harassment, civic integrity,
+ *   jailbreak) and ai.google.dev/gemini-api/docs/safety-settings (page dated
+ *   2026-09-17, the adjustable filters). The SDK's `HARM_CATEGORY_IMAGE_*`
+ *   values are marked "not supported in Gemini API" and are not admitted.
+ * - Thresholds: ai.google.dev/gemini-api/docs/safety-settings (page dated
+ *   2026-09-17), cross-checked against the SDK's `HarmBlockThreshold` enum.
+ *
+ * The adapter and every model's config schema read these lists, so a typo is
+ * rejected before dispatch instead of costing a round trip.
+ *
+ * @module
+ */
+declare const GOOGLE_SAFETY_CATEGORIES: readonly ["HARM_CATEGORY_HARASSMENT", "HARM_CATEGORY_HATE_SPEECH", "HARM_CATEGORY_SEXUALLY_EXPLICIT", "HARM_CATEGORY_DANGEROUS_CONTENT", "HARM_CATEGORY_CIVIC_INTEGRITY", "HARM_CATEGORY_JAILBREAK"];
+declare const GOOGLE_SAFETY_THRESHOLDS: readonly ["HARM_BLOCK_THRESHOLD_UNSPECIFIED", "BLOCK_LOW_AND_ABOVE", "BLOCK_MEDIUM_AND_ABOVE", "BLOCK_ONLY_HIGH", "BLOCK_NONE", "OFF"];
+type GoogleSafetyCategory = (typeof GOOGLE_SAFETY_CATEGORIES)[number];
+type GoogleSafetyThreshold = (typeof GOOGLE_SAFETY_THRESHOLDS)[number];
 
 /**
  * Google-specific provider options for `@gullabs/google`.
@@ -12,16 +274,34 @@ import { Content } from '@google/genai';
  *
  * @module
  */
+
 type GoogleSafetySetting = {
-    category: string;
-    threshold: string;
+    /** A documented `HarmCategory`; see `safety-settings.ts` for the source. */
+    category: GoogleSafetyCategory;
+    /** A documented `HarmBlockThreshold`. */
+    threshold: GoogleSafetyThreshold;
 };
 type GoogleSearchTool = {
     googleSearch: Record<string, never>;
 };
+/**
+ * A cached-content reference: the resource name, or `{ cacheName, toolKinds }`
+ * taken from a `GoogleCacheHandle` (`handle.toolKinds` records which tools the
+ * cache holds). Pass those two fields, not the whole handle: the other fields
+ * are typed `never` here and the schema is strict. The request sent to Google
+ * carries only the name. A bare name says nothing about what the cache holds,
+ * so a Search fee in the response is priced from the observed queries and the
+ * cost is `estimated`; a handle whose `toolKinds` lists `googleSearch` marks the
+ * call as a Search call up front.
+ */
+type GoogleCachedContentRef = string | (Pick<GoogleCacheHandle, 'cacheName' | 'toolKinds'> & {
+    expiresAt?: never;
+    model?: never;
+    totalTokenCount?: never;
+});
 type GoogleProviderOptions = {
-    /** Google cached content resource name. */
-    cachedContent?: string;
+    /** Google cached content: the resource name, or a handle that records the cache's tool kinds. Explicit-caching models only. */
+    cachedContent?: GoogleCachedContentRef;
     /** Allowlisted Google safety settings. */
     safetySettings?: GoogleSafetySetting[];
     /** Exact Google tool declarations admitted by the selected model schema. */
@@ -33,6 +313,32 @@ type GoogleProviderOptions = {
     };
     /** Allow provider fallback from flex when flex was explicitly selected. */
     flexFallback?: boolean;
+    /**
+     * Admit `googleSearch` together with `output.jsonSchema` on a model that does
+     * not admit the pair by default. Opting in turns on {@link requireGrounding}
+     * unless it is set to `false`, because Search can be skipped silently when a
+     * response schema is attached. Requires both Search and a schema; Search is
+     * `googleSearch` in `tools` or a `cachedContent` handle whose `toolKinds` lists
+     * it. A schema call on such a model with a handle that lists `googleSearch`
+     * needs this flag, like an inline `googleSearch`; a bare cache name is not
+     * blocked, and a response of a schema call that reports search queries without
+     * a declared Search carries a warning.
+     */
+    allowSchemaWithSearch?: boolean;
+    /**
+     * Fail the call unless the response proves Search ran: `groundingMetadata`
+     * present with at least one `webSearchQueries` entry. The check judges only a
+     * candidate that finished normally (`STOP`, or no finish reason). Without the
+     * proof it throws a `server` error with reason `grounding_missing` and the
+     * attempt's usage is recorded; the error is retryable when no response schema
+     * is attached and not retryable when one is (the same request keeps missing).
+     * A `MAX_TOKENS` or other abnormal finish with no proof is not judged: it
+     * returns, with its own finish reason (`length`), and a filtered candidate
+     * throws its `content_filter` error. Requires Search (`googleSearch` in `tools`
+     * or a `cachedContent` handle whose `toolKinds` lists it). Defaults to
+     * `true` when {@link allowSchemaWithSearch} is `true`, else `false`.
+     */
+    requireGrounding?: boolean;
 };
 declare module '@gullabs/core' {
     interface ProviderOptionsMap {
@@ -102,6 +408,11 @@ interface GeminiPartShape {
         name?: string;
         args?: unknown;
     };
+    /**
+     * Opaque signature Gemini 3.x attaches to the first function call of a turn
+     * (and sometimes to text parts). Real field: `Part.thoughtSignature`.
+     */
+    thoughtSignature?: string;
 }
 /** A candidate returned by Gemini generateContent. */
 interface GeminiCandidateShape {
@@ -114,6 +425,14 @@ interface GeminiCandidateShape {
      * "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", etc.
      */
     finishReason?: string;
+    /** Human-readable detail Google sends with some finish reasons. */
+    finishMessage?: string;
+    /** Per-category safety ratings of the candidate. */
+    safetyRatings?: unknown[];
+    /** Source-attribution metadata for recited content. */
+    citationMetadata?: unknown;
+    /** Retrieval status of each URL the model was asked to read. */
+    urlContextMetadata?: unknown;
     /**
      * Grounding metadata returned when Google Search grounding is active.
      * Real SDK type: GroundingMetadata. Kept as `unknown` to avoid a hard
@@ -133,9 +452,23 @@ interface GeminiUsageMetadataShape {
     candidatesTokenCount?: number;
     cachedContentTokenCount?: number;
     thoughtsTokenCount?: number;
+    /** Tokens of tool results fed back to the model (Search results on Gemini 2.5). */
+    toolUsePromptTokenCount?: number;
     totalTokenCount?: number;
     /** Provider-echoed actual tier; can differ from the requested tier. */
     serviceTier?: string;
+    /**
+     * Prompt tokens per modality (`TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`);
+     * the counts sum to `promptTokenCount` and include the cached part.
+     */
+    promptTokensDetails?: GeminiModalityTokenCount[];
+    /** The cached part of the prompt per modality, when a cache was used. */
+    cacheTokensDetails?: GeminiModalityTokenCount[];
+}
+/** One entry of `usageMetadata.promptTokensDetails` / `cacheTokensDetails`. */
+interface GeminiModalityTokenCount {
+    modality?: string;
+    tokenCount?: number;
 }
 /**
  * Structural equivalent of @google/genai's GenerateContentResponse.
@@ -172,6 +505,8 @@ interface GeminiPartMediaResolution {
 /** A text part in a content object we construct. */
 interface GeminiTextContentPart {
     text: string;
+    /** Replayed signature for this part (real field: `Part.thoughtSignature`). */
+    thoughtSignature?: string;
 }
 /**
  * An inline binary media part in a content object we construct.
@@ -212,6 +547,8 @@ interface GeminiFunctionCallPart {
         name: string;
         args?: unknown;
     };
+    /** Replayed signature for this call (real field: `Part.thoughtSignature`). */
+    thoughtSignature?: string;
 }
 interface GeminiFunctionResponsePart {
     functionResponse: {
@@ -226,20 +563,6 @@ interface GeminiContent {
     role: string;
     parts: GeminiContentPart[];
 }
-/**
- * Schema shape we pass as responseSchema.
- * Structurally compatible with @google/genai Schema.
- */
-interface GeminiSchema {
-    type?: string;
-    description?: string;
-    properties?: Record<string, GeminiSchema>;
-    required?: string[];
-    items?: GeminiSchema;
-    enum?: string[];
-    nullable?: boolean;
-    format?: string;
-}
 /**
  * Thinking configuration.
  * Real type: ThinkingConfig in @google/genai.
@@ -270,7 +593,12 @@ interface GeminiGenerateConfig {
     maxOutputTokens?: number;
     stopSequences?: string[];
     responseMimeType?: string;
-    responseSchema?: GeminiSchema;
+    /**
+     * Standard JSON Schema for the response, sent verbatim (real field:
+     * `GenerateContentConfig.responseJsonSchema`). Never `responseSchema`, the
+     * OpenAPI-dialect field (ADR-034).
+     */
+    responseJsonSchema?: unknown;
     thinkingConfig?: GeminiThinkingConfig;
     /** Real type: ServiceTier enum. Values: "flex" | "standard". */
     serviceTier?: string;
@@ -281,22 +609,18 @@ interface GeminiGenerateConfig {
      * We use this to set a transport-level timeout that is >= the AbortSignal
      * deadline so the SDK fetch does not preempt the abort.
      *
-     * Real field: GenerateContentConfig.httpOptions.timeout (milliseconds).
-     * Real field: GenerateContentConfig.httpOptions.headers (Record<string,string>).
-     *   (No current use of custom headers here: Vertex AI auth — and the
-     *   Vertex flex-routing header injection this field once supported — was
-     *   removed from this library; see ADR-019 in DECISIONS.md. Only
-     *   API-key auth is supported below.)
+     * Real field: GenerateContentConfig.httpOptions.timeout (milliseconds). No
+     * other `httpOptions` field is admitted.
      */
     httpOptions?: {
         timeout?: number;
-        headers?: Record<string, string>;
     };
     tools?: Array<{
         functionDeclarations?: Array<{
             name: string;
             description: string;
-            parameters?: unknown;
+            /** Standard JSON Schema, verbatim (real field: `parametersJsonSchema`). */
+            parametersJsonSchema?: unknown;
         }>;
         googleSearch?: Record<string, never>;
     }>;
@@ -317,23 +641,28 @@ interface GeminiGenerateParams {
     config?: GeminiGenerateConfig;
 }
 /**
- * Parameters for models.countTokens.
- * Real type: CountTokensParameters.
+ * Parameters for counting tokens.
+ *
+ * With only `model` and `contents` the call is the SDK's `models.countTokens`.
+ * With `systemInstruction` or `tools` the Developer API's SDK method cannot
+ * carry them (it throws), so `buildGoogleClient` sends the REST `countTokens`
+ * with a full `generateContentRequest` instead; the two forms are mutually
+ * exclusive on the wire, so `contents` then travels inside the request.
  */
 interface GeminiCountTokensParams {
     model: string;
     contents: GeminiContent[];
+    systemInstruction?: {
+        parts: GeminiContentPart[];
+    };
+    tools?: NonNullable<GeminiGenerateConfig['tools']>;
     config?: {
-        systemInstruction?: {
-            parts: GeminiContentPart[];
-        };
         /**
          * Real field: CountTokensConfig.abortSignal. countTokens has no
-         * tier-timeout dance (no flex/standard default ceilings) — `ctx.signal`
+         * tier-timeout dance (no flex/standard default ceilings): `ctx.signal`
          * is forwarded here directly, unlike `run()`'s combined timer signal.
          */
         abortSignal?: AbortSignal;
-        tools?: GeminiGenerateConfig['tools'];
     };
 }
 /**
@@ -385,14 +714,6 @@ interface GeminiAdapterOptions {
      * as a typed `LlmError`.
      */
     client?: GeminiClientLike;
-    /**
-     * @internal Testing-only.
-     *
-     * Override the default `buildGoogleClient` factory.  Allows unit tests to
-     * simulate construction failures (e.g. bad credentials) without importing
-     * the real `@google/genai` SDK.  Never set this in production code.
-     */
-    _clientFactory?: (auth: AuthMaterial) => GeminiClientLike | Promise<GeminiClientLike>;
 }
 /**
  * Create a Gemini provider adapter.
@@ -401,6 +722,59 @@ interface GeminiAdapterOptions {
  */
 declare function geminiAdapter(opts?: GeminiAdapterOptions): ProviderAdapter;
 
+/**
+ * classifyGoogleError — reclassify a raw thrown value into a typed
+ * {@link LlmError} for @gullabs/google.
+ *
+ * Thin wrapper around `@gullabs/core`'s `classifyError`, which already routes
+ * by HTTP status first, treats a transport failure (`fetch failed`, an errno on
+ * the cause chain) as a retryable `server` error and maps 404/413 to
+ * `bad_request`. This module adds the overlays Gemini's structured error body
+ * supports (ADR-028 style: only the parsed body, never free text):
+ *
+ * - `RetryInfo.retryDelay` becomes `retryAfterMs` (the SDK's `ApiError` keeps no
+ *   headers, so the body is the only place Google puts the delay).
+ * - A `QuotaFailure` whose quota id contains `PerDay` is a daily quota: it
+ *   cannot recover before the next day, so it is `rate_limited` with
+ *   `retryable: false` and `reason: 'daily_quota'`.
+ * - `ErrorInfo.reason` `API_KEY_INVALID` / `API_KEY_EXPIRED` is `invalid_auth`.
+ *   Google sends the invalid-key case as HTTP 400, which would otherwise read
+ *   as a caller bug (live capture, probe P6, 2026-10-03). `API_KEY_EXPIRED` is
+ *   mapped from Google's documented reason set; an expired key could not be
+ *   produced to capture it.
+ * - A 403 whose body message is `CachedContent not found (or permission
+ *   denied)` is a stale `cachedContent` reference: `bad_request` with
+ *   `reason: 'cache_not_found'` (probe P6). Google sends no structured reason
+ *   for it, so the body's `message` field is the only signal, and a genuine
+ *   permission failure cannot be told apart.
+ *
+ * @module
+ */
+
+/** Optional extra fields threaded onto the returned {@link LlmError}. */
+interface ClassifyGoogleErrorExtra {
+    /** Service tier actually attempted by the provider when known. */
+    servedServiceTier?: string;
+    /**
+     * Set by the adapter when its own client-side ceiling, or the SDK's transport
+     * timer, ended the call (the caller and the engine's deadline had not
+     * aborted): what happened, in words. The error is then a `timeout` that is not
+     * retryable, `reason: 'transport_timeout'`.
+     */
+    transportTimeout?: string;
+}
+/**
+ * Classify a raw error thrown from a `@google/genai` client call into a
+ * typed {@link LlmError} always tagged `provider: 'google'`.
+ *
+ * Delegates to `@gullabs/core`'s `classifyError` (an already-classified
+ * `LlmError` passes through unchanged), applies the structured-body overlays
+ * described in the module header, and rebuilds the result with
+ * `provider: 'google'` forced on, so every error surfaced by this adapter is
+ * tagged even one injected pre-classified.
+ */
+declare function classifyGoogleError(rawErr: unknown, extra?: ClassifyGoogleErrorExtra): LlmError;
+
 /**
  * `googleProvider` — {@link ProviderPlugin} factory for @gullabs/google.
  *
@@ -458,8 +832,8 @@ declare const defaultGeminiRegistry: ModelRegistry;
  * Provides `geminiPricingSource` — a factory returning a `PricingSource` port
  * implementation backed by the frozen Gemini pricing snapshot ({@link
  * GEMINI_PRICING}). Uses exact priced model identifiers,
- * resolves the concrete per-tier rates, and delegates the arithmetic to
- * `@gullabs/core`'s `computeCost`. Core itself carries zero Gemini pricing
+ * resolves the concrete per-tier rates, and delegates the token arithmetic to
+ * `@gullabs/core`'s `computeCost` (audio input and grounding are priced here). Core itself carries zero Gemini pricing
  * knowledge and applies no tier multiplier.
  *
  * @module
@@ -492,12 +866,13 @@ declare function geminiPricingSource(): PricingSource;
  * All rates are in **micro-USD per million tokens** (µUSD/M).
  * To get the cost for N tokens: `cost_µUSD = N * ratePerM / 1_000_000`.
  *
- * **Service tiers.** Each model stores concrete `standard`, `flex`, and
- * `batch` rates transcribed from Google's pricing page. Flex and batch are
- * not a flat 50% of standard: on several models the cached lane stays at the
- * standard cached rate (or a published rate that is not half). A tier that
- * is not one of those three is unpriced (reject-don't-map). `priority` is
- * intentionally absent — it needs downgrade accounting and is a backlog item.
+ * **Service tiers.** Each model stores concrete `standard` and `flex` rates
+ * transcribed from Google's pricing page. Flex is not a flat 50% of standard: on
+ * several models the cached lane stays at the standard cached rate (or a
+ * published rate that is not half). A tier that is not one of those two is
+ * unpriced (reject-don't-map). `priority` is intentionally absent: it needs
+ * downgrade accounting and is a backlog item. The Batch API has no path in this
+ * library (no schema admits a batch tier), so its rates are not carried.
  *
  * **Long-context tier.** Gemini Pro models charge a premium when the GROSS
  * input token count exceeds 200,000. Selected by `inputTokens` (incl. cached),
@@ -506,14 +881,30 @@ declare function geminiPricingSource(): PricingSource;
  * **Thinking tokens.** Already inside `outputTokens` (GROSS convention) and
  * billed at the output rate — no separate thinking lane.
  *
- * **Modality caveat (v1 = text).** Gemini 2.5 Flash / Flash-Lite / 3.1
- * Flash-Lite charge a higher INPUT rate for audio tokens
- * than for text/image/video. v1 is text-only and uses the text/img/vid input
- * rate. Per-modality input pricing is a deferred seam (see DESIGN.md).
+ * **Audio input.** Gemini 2.5 Flash, 2.5 Flash-Lite and 3.1 Flash-Lite charge
+ * more for audio input than for text, image and video tokens ({@link GeminiRates.audio}).
+ * The adapter records the prompt's per-modality token counts
+ * (`usageMetadata.promptTokensDetails` and `cacheTokensDetails`) as
+ * `usage.details.input_<modality>` / `cached_<modality>`, and the pricing source
+ * bills the audio tokens at the audio rates and the rest at the text rate. Every
+ * other model is billed one input rate for all modalities on the page. Models with
+ * an audio rate have no `gt200k` band, so the long-context band never needs the
+ * audio split.
  *
  * Re-verified against https://ai.google.dev/gemini-api/docs/pricing on
  * 2026-09-25. Standard token rates for already-registered models were
- * unchanged from the 2026-08-12 snapshot; flex/batch cached rates were not.
+ * unchanged from the 2026-08-12 snapshot; flex cached rates were not. The audio
+ * input and cached-audio rates (standard and flex) were read from the same page
+ * on 2026-10-03; the page showed "Last Updated 2026-10-01 UTC".
+ *
+ * **Grounding with Google Search** is a tool lane, not a token rate; see
+ * {@link GEMINI_GROUNDING_PRICING}. It was added from the same pricing page
+ * on 2026-10-03. {@link pricingVersion} is `gemini-2026-10-03` because the
+ * snapshot gained the grounding lane and the audio lane that day (a grounded or
+ * audio call prices differently under it). The 2026-10-03 read of the page also
+ * matched the standard text and cached rates of the models it listed (and the
+ * flex text and cached rates of the three audio models); only the models the page
+ * summary did not list keep their 2026-09-25 verification.
  *
  * @module
  */
@@ -525,30 +916,143 @@ declare function geminiPricingSource(): PricingSource;
  * core concept — it lives here (not `@gullabs/core`) alongside the rates it
  * dates.
  */
-declare const pricingVersion: "gemini-2026-09-25";
+declare const pricingVersion: "gemini-2026-10-03";
 /** Tiers this snapshot prices. Anything else is unpriced. */
-declare const GEMINI_PRICED_TIERS: readonly ["standard", "flex", "batch"];
+declare const GEMINI_PRICED_TIERS: readonly ["standard", "flex"];
 type GeminiPricedTier = (typeof GEMINI_PRICED_TIERS)[number];
+/** Audio input rates for a model that prices audio apart from text (µUSD per million tokens). */
+interface GeminiAudioRates {
+    /** Non-cached audio input tokens. */
+    inputPerM: number;
+    /** Cached audio input tokens. */
+    cachedPerM: number;
+}
+/** {@link ModelRates} plus the audio input rates, for models that publish them. */
+interface GeminiRates extends ModelRates {
+    /**
+     * Present only on a model whose pricing page lists a separate audio input
+     * price. Priced on the audio tokens `promptTokensDetails` reports; every other
+     * input token uses the text/image/video rates above.
+     */
+    audio?: GeminiAudioRates;
+}
 /** Concrete per-tier rates for one model. */
 interface GeminiTierRates {
-    standard: ModelRates;
-    flex: ModelRates;
-    batch: ModelRates;
+    standard: GeminiRates;
+    flex: GeminiRates;
 }
 /**
- * Frozen Gemini pricing snapshot (per-1M in µUSD), keyed by model id, then
- * by priced tier. Every number is transcribed from the pricing page.
+ * Deep-frozen Gemini pricing snapshot (per-1M in µUSD), keyed by model id, then
+ * by priced tier; no rate object, `gt200k` band or `audio` rate can be changed.
+ * Every number is transcribed from the pricing page.
  *
  * Keys are exact priced model identifiers. Unlisted variants are unpriced.
  *
- * Source: https://ai.google.dev/gemini-api/docs/pricing (re-verified 2026-09-25).
+ * Source: https://ai.google.dev/gemini-api/docs/pricing (re-verified 2026-09-25;
+ * the audio input and cached-audio rates read 2026-10-03, page last updated
+ * 2026-10-01).
  */
 declare const GEMINI_PRICING: Readonly<Record<string, GeminiTierRates>>;
-/** Resolve the concrete {@link ModelRates} `computeCost` should apply. */
-declare function resolveGeminiRates(model: string, tier: string | undefined): ModelRates | undefined;
+/**
+ * How a model bills grounding with Google Search, in µUSD per unit.
+ *
+ * - `'query'`: Gemini 3 bills each search query the model performed. The unit
+ *   count is `usage.details.web_search_calls`, counted as occurrences in
+ *   `webSearchQueries` (a repeated query counts each time; whether Google bills
+ *   a repeat is not established, so the count is the conservative one).
+ * - `'prompt'`: Gemini 2.5 bills each prompt that was grounded, once however
+ *   many queries it ran. A grounded prompt is one whose response reports at
+ *   least one query.
+ *
+ * Transcribed from https://ai.google.dev/gemini-api/docs/pricing, grounding
+ * with Google Search, read 2026-10-03 (Gemini 3: $14 per 1,000 queries;
+ * Gemini 2.5: $35 per 1,000 grounded prompts). The page also publishes a free
+ * allowance (as read 2026-10: 5,000 requests per month shared
+ * across Gemini 3.x, 1,500 requests per day on Gemini 2.5). It is shared across
+ * a project's calls, so no single call can know whether it was free: every
+ * grounding fee is charged in full here, which is why a call that ran Search is
+ * never reported as exact.
+ *
+ * Keys are exact priced model identifiers. Gemma has no token price in this
+ * snapshot, so it has no grounding price either.
+ */
+interface GeminiGroundingRate {
+    readonly unit: 'query' | 'prompt';
+    readonly microUsdPerUnit: number;
+}
+declare const GEMINI_GROUNDING_PRICING: Readonly<Record<string, GeminiGroundingRate>>;
+/** Resolve the concrete {@link GeminiRates} for `(model, tier)`. */
+declare function resolveGeminiRates(model: string, tier: string | undefined): GeminiRates | undefined;
 
+/**
+ * True when a failed Flex call may be retried once on the Standard tier
+ * because Flex capacity, not the caller's quota, ran out.
+ *
+ * Only HTTP 503 counts. Google's Flex page (ai.google.dev/gemini-api/docs/
+ * flex-inference, read 2026-10-03, page dated 2026-09-23) lists two failures
+ * when capacity is unavailable, 503 "The system is currently at capacity" and
+ * 429 "Rate limits or resource exhaustion", but documents no field that tells
+ * a capacity 429 from a quota 429, and no capture of either 429 exists. A 429
+ * is therefore the ordinary rate-limit path (the provider's `RetryInfo` delay
+ * is honoured, no Standard dispatch, no tier pin): dispatching Standard at once
+ * would undercut the delay, add a call to a rate-limited project and bill the
+ * logical call at the Standard rate. Nothing in the message text is read.
+ *
+ * `err` is the classified error.
+ */
 declare function isGeminiCapacityError(err: LlmError): boolean;
 
+/**
+ * Token limits and admitted input media types for the registered Google
+ * models, read from Google's own documentation (re-read 2026-10-03).
+ *
+ * One table feeds both the descriptors (`limits`, `inputMimeTypes`) and the
+ * per-model config schemas (`maxOutputTokens` is capped only when a number is
+ * documented), so a descriptor and its schema cannot drift.
+ *
+ * Sources, all read 2026-10-03:
+ *
+ * - Gemini: `https://ai.google.dev/gemini-api/docs/models/<model-id>`, one page
+ *   per model. Every registered Gemini model lists "Input token limit
+ *   1,048,576" and "Output token limit 65,536". The output limit includes
+ *   thinking tokens.
+ * - Gemma 4: the model card, `https://ai.google.dev/gemma/docs/core/model_card_4`,
+ *   states a "256K tokens" context window (read as 262,144). Neither it nor
+ *   `https://ai.google.dev/gemma/docs/core/gemma_on_gemini_api` documents an
+ *   output limit, so `maxOutputTokens` is `null` (see
+ *   {@link ModelLimits.maxOutputTokens}): no figure is invented and the schema
+ *   applies no cap.
+ * - Gemini input media: Google publishes lists for images
+ *   (`https://ai.google.dev/gemini-api/docs/image-understanding`: PNG, JPEG,
+ *   WebP, HEIC, HEIF), audio (`.../audio`), and video
+ *   (`.../video-understanding`), but no closed list for documents:
+ *   `.../document-processing` says only that PDF is understood natively and
+ *   "you can pass other MIME types for document understanding, like TXT,
+ *   Markdown, HTML, XML, etc.", extracted as plain text. `.../files` lists no
+ *   types either. The descriptor therefore admits the documented families by
+ *   prefix (`text/*`, `image/*`, `audio/*`, `video/*`) plus `application/pdf`,
+ *   and leaves a type inside a family that Google does not accept to Google's
+ *   own error. `application/json`, `application/xml` and other `application/*`
+ *   types are not in any documented family and stay rejected.
+ * - Gemma 4 input media: the model card lists "Supported Modalities: Text,
+ *   Image" for the 31B and 26B A4B models and says "All models support image
+ *   inputs and can process videos as frames", with video "a maximum of 60
+ *   seconds" at one frame per second; audio input is E2B/E4B/12B only. No Gemma
+ *   page names image or video media types, so `image/*` and `video/*` are
+ *   admitted and nothing else. That the Gemini API's Gemma endpoint takes a
+ *   video part (rather than frames sent as images) has not been probed.
+ *
+ * @module
+ */
+
+/**
+ * Media types every Gemini model in the registry accepts as input parts: the
+ * documented families (text, image, audio, video) and PDF. See the module
+ * comment for why the families are not closed lists. One rule serves
+ * `generate` and `GoogleFileStore.upload`.
+ */
+declare const GEMINI_INPUT_MIME_TYPES: readonly string[];
+
 /**
  * GoogleFileStore — thin wrapper over the Gemini File API.
  *
@@ -568,6 +1072,20 @@ interface GoogleFileHandle {
     /** Provider auto-deletes ~48 h after upload. Absent when not returned. */
     expiresAt?: Date;
 }
+/** The `File` resource fields the store reads. */
+type FileResp = {
+    name?: string;
+    uri?: string;
+    mimeType?: string;
+    state?: string;
+    expirationTime?: string;
+    /** Real field `File.error` (`FileStatus`): why processing failed. */
+    error?: {
+        code?: number;
+        message?: string;
+        details?: Record<string, unknown>[];
+    };
+};
 /**
  * Minimal structural interface for the Gemini Files client surface we use.
  * Satisfied by the real ai.files object or a test fake.
@@ -578,23 +1096,12 @@ interface GeminiFilesClientLike {
         config?: {
             mimeType?: string;
             displayName?: string;
+            abortSignal?: AbortSignal;
         };
-    }): Promise<{
-        name?: string;
-        uri?: string;
-        mimeType?: string;
-        state?: string;
-        expirationTime?: string;
-    }>;
+    }): Promise<FileResp>;
     get(params: {
         name: string;
-    }): Promise<{
-        name?: string;
-        uri?: string;
-        mimeType?: string;
-        state?: string;
-        expirationTime?: string;
-    }>;
+    }): Promise<FileResp>;
     delete(params: {
         name: string;
     }): Promise<void>;
@@ -629,7 +1136,18 @@ interface GoogleFileStoreOptions {
         /** Max time to wait for ACTIVE. Default: 300 000 ms (5 min). */
         timeoutMs?: number;
     };
-    /** Injectable sleep for tests. Default: real setTimeout. */
+    /**
+     * Timer source for the poll wait; pass the client's `FakeClock` in tests so
+     * one `advance` fires the wait. Default: the platform's timers. (`now` is the
+     * poll timeout's clock; pass `() => clock.now()` with it.)
+     */
+    scheduler?: Scheduler;
+    /**
+     * Replaces the poll wait wholesale (instant polling in tests). When given,
+     * `scheduler` is not used for the wait, and the wait cannot be cancelled: if
+     * the deadline or an abort ends the upload first, a timer your `sleep` set
+     * stays pending until it fires. The default wait is cleared at once.
+     */
     sleep?: (ms: number) => Promise<void>;
     /** Injectable clock for deterministic tests. Default: `Date.now`. */
     now?: () => number;
@@ -652,7 +1170,8 @@ declare class GoogleFileStore {
     private readonly logger;
     private readonly intervalMs;
     private readonly timeoutMs;
-    private readonly sleep;
+    private readonly startWait;
+    private readonly scheduler;
     private readonly now;
     /** Memoised client promise — built at most once per store instance. */
     private clientPromise;
@@ -662,13 +1181,26 @@ declare class GoogleFileStore {
      * 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.
      */
     upload(source: Uint8Array | Blob, mimeType: string, opts?: {
         displayName?: string;
         signal?: AbortSignal;
     }): Promise<GoogleFileHandle>;
+    /**
+     * `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.
+     */
+    private raceDeadline;
+    /** Polls `name` until ACTIVE; see {@link GoogleFileStore.upload}. */
+    private pollUntilActive;
     /**
      * Delete a single uploaded file. Idempotent: not-found → success.
      *
@@ -690,208 +1222,62 @@ declare class GoogleFileStore {
 }
 
 /**
- * GoogleCacheStore — thin wrapper over the Gemini Context Cache API.
+ * Gemini 3 thought signatures as an overlay on the host's actual history.
  *
- * Manages create / get-or-create / refresh / delete lifecycle for cached
- * contents.  In-memory cache entries are PROCESS-SCOPED; they are not shared
- * across processes, workers, or restarts.
+ * Gemini 3.x returns an opaque `thoughtSignature` on the first function call of
+ * each model turn (and sometimes on text parts) and rejects a replayed turn
+ * whose function call has lost it. The library never keeps a copy of the
+ * history. `result.transientProviderState` is only an overlay saying which part
+ * of the host's own messages gets which signature:
  *
- * Injectable client and `now` function keep tests free of network and clock.
+ * ```ts
+ * { google: { signatures: [{ messageIndex, partIndex, kind, model, partSha256, signature }] } }
+ * ```
+ *
+ * `messageIndex` indexes the messages the adapter receives (`request.messages`
+ * as the engine hands them on, after any middleware), `partIndex` indexes that
+ * message's `parts` (thought parts are never in a message), `kind` is the part
+ * kind that was signed (`'text'` or `'tool-call'`), `model` is the model string
+ * the request named, and `partSha256` is the SHA-256 of the part's RFC 8785
+ * canonical JSON, so an edited argument or text is detected and key order
+ * (Postgres `jsonb`) does not matter.
+ *
+ * A function-call signature is required on replay, so a stale one is
+ * `bad_request`. A text signature is optional (Google accepts the next turn
+ * without it), so a stale one (edited, moved, removed, or issued for another
+ * model) is dropped with a warning and nothing else is lost.
  *
  * @module
  */
 
-/**
- * A handle to a cached content resource in the Gemini Context Cache API.
- *
- * Pass `cacheName` as `providerOptions.google.cachedContent` in LlmRequest.
- */
-interface GoogleCacheHandle {
-    /** Resource name, e.g. "cachedContents/xyz". */
-    cacheName: string;
-    /**
-     * Local view of when the cache expires (server-authoritative; computed from
-     * ttl or parsed from the server response `expireTime`).
-     */
-    expiresAt: Date;
-    /** Caches are model-bound; never use a handle with a different model. */
-    model: string;
-}
-/** Key used to look up or create an entry in the in-process cache map. */
-interface CacheKey {
+/** The part kinds Google signs. */
+type GoogleSignedKind = 'text' | 'tool-call';
+/** One signature, pinned to a part of the host's history. */
+type GoogleSignatureEntry = {
+    messageIndex: number;
+    partIndex: number;
+    /** The kind of part that was signed; decides whether a stale entry is fatal. */
+    kind: GoogleSignedKind;
     model: string;
-    /** Caller-chosen stable identifier, e.g. a hash of the cached content. */
-    stableKey: string;
-}
-/**
- * Minimal structural interface for the Gemini Caches client surface we use.
- * Satisfied by the real `ai.caches` object or a test fake.
- */
-interface GeminiCachesClientLike {
-    create(params: {
-        model: string;
-        config: {
-            contents?: Content[];
-            systemInstruction?: Content | string;
-            ttl?: string;
-            displayName?: string;
-        };
-    }): Promise<{
-        name?: string;
-        model?: string;
-        expireTime?: string;
-    }>;
-    update(params: {
-        name: string;
-        config: {
-            ttl?: string;
-            expireTime?: string;
-        };
-    }): Promise<{
-        name?: string;
-        expireTime?: string;
-    }>;
-    delete(params: {
-        name: string;
-    }): Promise<unknown>;
-}
-interface GoogleCacheStoreOptions {
-    auth: AuthMaterial;
-    /** Injectable client for tests; skips SDK import when provided. */
-    client?: GeminiCachesClientLike;
-    /**
-     * When true, concurrent `getOrCreate` calls for the same key share one
-     * in-flight create.  Default false.
-     */
-    coalesce?: boolean;
-    /**
-     * Subtracted from the local expiry so we stop using a cache slightly before
-     * the server evicts it.  Default 30 s.
-     */
-    expirySkewSeconds?: number;
-    /** Called on delete failures instead of rethrowing. */
-    onDeleteError?: (cacheName: string, err: unknown) => void;
-    /** Optional structured logger. When provided, routes delete failures to logger.error. */
-    logger?: Logger;
-    /** Injectable clock for deterministic tests.  Default: `Date.now`. */
-    now?: () => number;
-    /**
-     * Opt-in pre-flight token-count gate applied before every cache create
-     * (both `create()` directly and the `getOrCreate()` path it delegates to,
-     * including the coalesced path — enforced once, inside `create()`, so
-     * there is no separate "in-flight" gap to close).
-     */
-    preflight?: {
-        /** Minimum token count required before a cache create is allowed to proceed. */
-        minTokens: number;
-        /**
-         * Counts tokens for the exact token-bearing payload of the impending
-         * create — `model` + `contents` + `systemInstruction` only. `ttl` and
-         * `displayName` are excluded: they carry no tokens and are irrelevant to
-         * the pre-flight check.
-         *
-         * This callback receives genai-native `Content[]`/`Content|string` — it
-         * does NOT receive the library's `Message[]` shape and there is no
-         * automatic conversion between the two (explicit seam, by design). Hosts
-         * using genai-native content directly can wire this to a raw
-         * `client.models.countTokens` call; hosts building from the library's
-         * `Message[]` should call `@gullabs/core`'s `client.countTokens` rather
-         * than expecting this callback to convert for them.
-         */
-        countTokens: (payload: {
-            model: string;
-            contents?: Content[];
-            systemInstruction?: Content | string;
-        }) => Promise<number>;
+    partSha256: string;
+    signature: string;
+};
+/** The shape of `transientProviderState` for Gemini 3.x models. */
+type GoogleSignatureState = {
+    google: {
+        signatures: GoogleSignatureEntry[];
     };
-}
+};
 /**
- * Process-scoped helper for the Gemini Context Cache API.
- *
- * NOTE: `getOrCreate` reuse is PROCESS-SCOPED only.  Entries survive only for
- * the lifetime of this `GoogleCacheStore` instance.  Across restarts, new
- * caches will be created (and old ones will be server-evicted after their TTL).
- *
- * **Auth snapshot note:** this store captures the `AuthMaterial` at construction
- * time and memoizes a single SDK client from it (`clientPromise`).  This is
- * correct and sufficient for static API keys.  If refreshable credentials
- * (short-lived OAuth/STS tokens) are added in the future, this memoization is
- * the seam that will need rework: the cached client would hold stale credentials
- * for the lifetime of a long-lived store instance.  At that point, the store
- * will need to either rebuild the client on each operation or accept a
- * credential-resolver callback rather than a plain `AuthMaterial` value.
- * See ADR-020 in DECISIONS.md.
+ * Remove the entries for messages the host removed from its history, and shift
+ * the `messageIndex` of every later entry down so it still points at the same
+ * message. `indices` are positions in the history the state was issued for
+ * (before the removal). Whole turns only: remove a tool-call message together
+ * with its tool-result message, and never keep a tool-call message while
+ * removing its entry. Returns `undefined` when no entry remains, so the result
+ * can be sent as `transientProviderState` or omitted.
  */
-declare class GoogleCacheStore {
-    private readonly auth;
-    private readonly clientOverride;
-    private readonly coalesce;
-    private readonly skewMs;
-    private readonly onDeleteError;
-    private readonly logger;
-    private readonly now;
-    private readonly preflight;
-    /** Memoised client promise — built at most once per store instance. */
-    private clientPromise;
-    /** In-process cache of live handles, keyed by `${model}:${stableKey}`. */
-    private readonly entries;
-    /** In-flight create promises when coalescing is enabled. */
-    private readonly inflight;
-    constructor(opts: GoogleCacheStoreOptions);
-    private getClient;
-    private isLive;
-    /**
-     * Create a new cached content resource.
-     *
-     * The `expiresAt` on the returned handle is computed from the server's
-     * `expireTime` when available, with a local-clock fallback of
-     * `now + ttlSeconds * 1000`.
-     */
-    create(input: {
-        model: string;
-        ttlSeconds: number;
-        contents?: Content[];
-        systemInstruction?: Content | string;
-        displayName?: string;
-    }): Promise<GoogleCacheHandle>;
-    /**
-     * Return a live cached-content handle, creating one if none exists or the
-     * cached entry has expired (accounting for skew).
-     *
-     * Reuse is PROCESS-SCOPED only — this store instance's in-memory map.
-     *
-     * When `coalesce` is enabled, concurrent calls for the same key share one
-     * in-flight create.
-     */
-    getOrCreate(key: CacheKey, factory: () => Promise<{
-        ttlSeconds: number;
-        contents?: Content[];
-        systemInstruction?: Content | string;
-    }>): Promise<GoogleCacheHandle>;
-    /**
-     * Extend the cache TTL if it will expire within `thresholdSeconds`.
-     *
-     * Fail-open: if the update call throws, the original handle is returned
-     * unchanged.  This method NEVER throws.
-     *
-     * @param handle - Handle to potentially refresh.
-     * @param opts.thresholdSeconds - Extend if expiry is within this many seconds.
-     *   Default 300.
-     * @param opts.extensionSeconds - New TTL to set.  Default: original TTL from
-     *   entries map, or 3600 s when the handle was not created via `getOrCreate`.
-     */
-    refreshIfExpiringSoon(handle: GoogleCacheHandle, opts?: {
-        thresholdSeconds?: number;
-        extensionSeconds?: number;
-    }): Promise<GoogleCacheHandle>;
-    /**
-     * Delete a cached content resource.
-     *
-     * Errors are forwarded to `onDeleteError` and NOT rethrown.
-     * The handle is removed from the in-process entries map regardless.
-     */
-    delete(handle: GoogleCacheHandle): Promise<void>;
-}
+declare function dropMessagesFromSignatureState(state: unknown, indices: readonly number[]): GoogleSignatureState | undefined;
 
 /**
  * geminiContentToMessages — migration utility: `@google/genai` `Content[]` →
@@ -910,7 +1296,10 @@ declare class GoogleCacheStore {
  * Validation is an exhaustive own-key scan: the set of defined keys on each
  * `Part` must be EXACTLY one of the recognized combinations (`['text']`,
  * `['inlineData']`, `['inlineData', 'mediaResolution']`, `['fileData']`,
- * `['fileData', 'mediaResolution']`). Any other key — including unknown
+ * `['fileData', 'mediaResolution']`), plus `functionCall` / `functionResponse`.
+ * A `thoughtSignature` on a model text or `functionCall` part is imported into
+ * `transientProviderState` (see {@link GeminiContentToMessagesInput.model});
+ * on any other part it throws. Any other key — including unknown
  * future SDK fields — or any combination outside that set throws. Keys whose
  * value is `undefined` are treated as absent (genai types are all-optional;
  * only defined values count).
@@ -930,6 +1319,12 @@ interface GeminiContentToMessagesInput {
      * non-text part throws).
      */
     systemInstruction?: Content | string;
+    /**
+     * The model string the converted history will be sent to. Required when any
+     * part carries a `thoughtSignature`: signatures are bound to the model that
+     * issued them and are never replayed on another one.
+     */
+    model?: string;
 }
 /**
  * Output produced by {@link geminiContentToMessages}.
@@ -939,6 +1334,13 @@ interface GeminiContentToMessagesResult {
     system?: string;
     /** Normalized any-llm messages, one per input `Content`. */
     messages: Message[];
+    /**
+     * The thought signatures found on model parts, as the overlay a Gemini 3.x
+     * request takes as `transientProviderState`. Present only when at least one
+     * part carried a `thoughtSignature`. Send it with `messages` unedited and the
+     * same `model`.
+     */
+    transientProviderState?: JsonValue;
 }
 /**
  * Convert `@google/genai` `Content[]` / `Part[]` into any-llm's normalized
@@ -974,4 +1376,4 @@ interface GeminiContentToMessagesResult {
  */
 declare function geminiContentToMessages(input: GeminiContentToMessagesInput): GeminiContentToMessagesResult;
 
-export { type CacheKey, FLEX_DEFAULT_TIMEOUT_MS, type FileDeleteOptions, GEMINI_PRICED_TIERS, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GeminiPricedTier, type GeminiTierRates, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, defaultGeminiRegistry, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey, resolveGeminiRates };
+export { type CacheKey, type ClassifyGoogleErrorExtra, FLEX_DEFAULT_TIMEOUT_MS, type FileDeleteOptions, GEMINI_GROUNDING_PRICING, GEMINI_INPUT_MIME_TYPES, GEMINI_PRICED_TIERS, GEMINI_PRICING, type GeminiAdapterOptions, type GeminiCachesClientLike, type GeminiClientLike, type GeminiContentToMessagesInput, type GeminiContentToMessagesResult, type GeminiCountTokensParams, type GeminiCountTokensResponseShape, type GeminiFilesClientLike, type GeminiGroundingRate, type GeminiPricedTier, type GeminiTierRates, type GoogleCacheHandle, GoogleCacheStore, type GoogleCacheStoreOptions, type GoogleCachedContentRef, type GoogleFileHandle, GoogleFileStore, type GoogleFileStoreOptions, type GoogleProviderOptions, type GoogleSafetySetting, type GoogleSearchTool, type GoogleSignatureEntry, type GoogleSignatureState, type GoogleSignedKind, STANDARD_DEFAULT_TIMEOUT_MS, TRANSPORT_TIMEOUT_BUFFER_MS, buildGoogleClient, classifyGoogleError, defaultGeminiRegistry, dropMessagesFromSignatureState, geminiAdapter, geminiContentToMessages, geminiModelDescriptors, geminiPricingSource, gemmaModelDescriptors, googleProvider, isGeminiCapacityError, pricingVersion, requireApiKey, resolveGeminiRates };