@framers/agentos 0.10.20 → 0.10.22

package/dist/core/llm/providers/implementations/GeminiProvider.js

@@ -4,29 +4,296 @@ import { GeminiProviderError } from '../errors/GeminiProviderError.js';
 import { ApiKeyPool } from '../../../providers/ApiKeyPool.js';
 import { computeRetryBackoffMs } from './retry-backoff.js';
 import { sanitizeGeminiResponseSchema } from './geminiResponseSchema.js';
+/**
+ * Most requests `models/{model}:batchEmbedContents` accepts in one call. The
+ * API returns HTTP 400 "at most 100 requests can be in one batch" above this
+ * (probed 2026-09-29 on gemini-embedding-001).
+ */
+const GEMINI_EMBED_BATCH_LIMIT = 100;
+/**
+ * Placeholder signature Google documents for replaying a function call whose
+ * real signature is unavailable, such as a call made by another provider in a
+ * fallback chain. Gemini 3 returns HTTP 400 for a replayed call with no
+ * signature and accepts this value, and Gemini 2.5 accepts it too (probed
+ * 2026-09-29).
+ */
+const GEMINI_SKIP_THOUGHT_SIGNATURE = 'skip_thought_signature_validator';
+/**
+ * The credentials part of a base URL, read from the raw string: the text
+ * between the authority start (after a leading `scheme://` or `//`, else the
+ * start of a scheme-less URL) and the last `@`. The last `@` is used because an email-style username
+ * carries its own `@`, and the raw string because a URL that fails to parse
+ * (for example with a `/` in the password) still appears verbatim in fetch's
+ * error.
+ *
+ * @param baseURL Configured base URL.
+ * @returns The credentials substring, or undefined when there is none.
+ */
+function baseUrlCredentials(baseURL) {
+    if (!baseURL)
+        return undefined;
+    // Only a leading scheme or `//` opens the authority; a `//` later in the
+    // path must not move the start past the credentials.
+    const scheme = /^[a-z][a-z\d+.-]*:\/\//i.exec(baseURL);
+    const start = scheme ? scheme[0].length : baseURL.startsWith('//') ? 2 : 0;
+    const at = baseURL.lastIndexOf('@');
+    return at > start ? baseURL.slice(start, at) : undefined;
+}
+/**
+ * Masks the secrets a request URL carries out of an error message: the API
+ * key the request sent as `key=` and any credentials in the base URL. The
+ * known values are replaced literally, since a pattern cannot tell where
+ * arbitrary credentials end. A fetch that rejects its URL (relative,
+ * scheme-less or credential-bearing) names the whole URL in its error.
+ *
+ * @param message Error message that may contain the request URL.
+ * @param apiKey The key the request carried.
+ * @param baseURL Configured base URL.
+ * @returns The message with those secrets replaced by `[redacted]`.
+ */
+function redactUrlSecrets(message, apiKey, baseURL) {
+    // Longest first, so a key that also appears inside the credentials cannot
+    // split them before the whole credentials string is replaced.
+    const secrets = [baseUrlCredentials(baseURL), apiKey]
+        .filter((secret) => Boolean(secret))
+        .sort((a, b) => b.length - a.length);
+    let out = message;
+    for (const secret of secrets)
+        out = out.split(secret).join('[redacted]');
+    // Backstops for any other key= value or //user:password@ credentials.
+    return out
+        .replace(/([?&]key=)[^&\s"')]+/g, '$1[redacted]')
+        .replace(/(\/\/)[^/\s@"')]+@/g, '$1[redacted]@');
+}
+/**
+ * Thinking levels each model accepts, keyed by exact model id and limited to
+ * what was verified against the live API (2026-09-30). The set differs per
+ * model, not per family: the 3.x image models take `minimal` | `high`, the
+ * 2.5 family rejects any level with 400 INVALID_ARGUMENT, and an alias can
+ * move to a model with a different set. A model missing here never receives
+ * a level, which is always accepted.
+ */
+const GEMINI_THINKING_LEVELS = {
+    'gemini-3.1-pro-preview': new Set(['low', 'medium', 'high']),
+};
+/**
+ * The thinking level to send for the provider-neutral `effort` on `modelId`,
+ * or `undefined` when the API default should stand: no effort, an effort
+ * with no Gemini equivalent, or a model that does not take that level.
+ */
+function geminiThinkingLevelFor(modelId, effort) {
+    const level = effort === 'low' || effort === 'medium'
+        ? effort
+        : effort === 'high' || effort === 'xhigh' || effort === 'max'
+            ? 'high'
+            : undefined;
+    if (!level)
+        return undefined;
+    return GEMINI_THINKING_LEVELS[modelId]?.has(level) ? level : undefined;
+}
+/**
+ * Pinned model ids and the alias that keeps serving their tier once Google
+ * retires them. Preview ids are retired without a redirect (the retired id
+ * answers HTTP 404); when a request for a key here fails that way, the
+ * provider retries it once on the alias.
+ */
+const GEMINI_RETIRED_MODEL_ALIAS = {
+    'gemini-3.1-pro-preview': 'gemini-pro-latest',
+};
+/** Pinned ids already reported as retired, so the warning prints once each. */
+const warnedRetiredGeminiModels = new Set();
+/**
+ * Long-context price tier: above `abovePromptTokens` prompt tokens the whole
+ * request bills at these per-1M rates instead of the catalog's.
+ */
+const GEMINI_LONG_CONTEXT_PRICING = {
+    'gemini-3.1-pro-preview': { abovePromptTokens: 200000, input: 4.00, output: 18.00 },
+    'gemini-pro-latest': { abovePromptTokens: 200000, input: 4.00, output: 18.00 },
+    'gemini-2.5-pro': { abovePromptTokens: 200000, input: 2.50, output: 15.00 },
+};
 // ---------------------------------------------------------------------------
 // Known model catalog
 // ---------------------------------------------------------------------------
-/** Static catalog of well-known Gemini models and their metadata. */
+/**
+ * Static catalog of well-known Gemini models and their metadata.
+ *
+ * Ids and token limits come from a live GET /v1beta/models probe and rates from
+ * ai.google.dev/gemini-api/docs/pricing, both on 2026-09-29. `getModelInfo` is
+ * an exact-id lookup over this array, so a model missing here resolves to
+ * undefined and its calls carry no context limit and no price.
+ *
+ * Tiers advance independently. Flash has reached 3.8 while Pro is at
+ * 3.1-preview, the only Pro id served. `gemini-3-pro-preview` appears in
+ * Google's doc index and is absent from the live listing.
+ *
+ * Rates are the standard tier. Prompts over 200K tokens on 3.1 Pro and 2.5
+ * Pro bill at the tier in GEMINI_LONG_CONTEXT_PRICING, and Gemini 3.6 / 3.7 /
+ * 3.8 Flash list at promotional rates through 2026-12-31 and meter at the
+ * post-promotion rate.
+ */
 const GEMINI_MODELS = [
+    // --- Pro ---
     {
-        modelId: 'gemini-2.5-flash',
+        modelId: 'gemini-3.1-pro-preview',
         providerId: 'gemini',
-        displayName: 'Gemini 2.5 Flash',
-        description: 'Fast, cost-effective model with strong reasoning and multimodal capabilities.',
+        displayName: 'Gemini 3.1 Pro Preview',
+        description: 'Top pro-tier Gemini model. Always thinks; thinking tokens bill as output.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        // Prompts up to 200k tokens; see GEMINI_LONG_CONTEXT_PRICING above that.
+        pricePer1MTokensInput: 2.00,
+        pricePer1MTokensOutput: 12.00,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    // --- Flash. 3.6, 3.7 and 3.8 list at $0.75 / $3.75 through 2026-12-31 and
+    // $1.50 / $7.50 from 2027-01-01. They meter at $1.50 / $7.50, as
+    // claude-sonnet-5 meters at its sticker rate in the Anthropic catalog, so
+    // cost rollups stay conservative and stay right after the promotion. ---
+    {
+        modelId: 'gemini-3.8-flash',
+        providerId: 'gemini',
+        displayName: 'Gemini 3.8 Flash',
+        description: 'Newest Flash model. Fast and low-cost, with reasoning and multimodal input.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 1.50,
+        pricePer1MTokensOutput: 7.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-3.7-flash',
+        providerId: 'gemini',
+        displayName: 'Gemini 3.7 Flash',
+        description: 'Flash model with reasoning and multimodal input.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 1.50,
+        pricePer1MTokensOutput: 7.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-3.6-flash',
+        providerId: 'gemini',
+        displayName: 'Gemini 3.6 Flash',
+        description: 'Flash model with reasoning and multimodal input.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 1.50,
+        pricePer1MTokensOutput: 7.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-3.5-flash',
+        providerId: 'gemini',
+        displayName: 'Gemini 3.5 Flash',
+        description: 'Flash model with reasoning and multimodal input, at standard pricing.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 1.50,
+        pricePer1MTokensOutput: 9.00,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-3-flash-preview',
+        providerId: 'gemini',
+        displayName: 'Gemini 3 Flash Preview',
+        description: 'First Gemini 3 Flash preview.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 0.50,
+        pricePer1MTokensOutput: 3.00,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    // --- Flash-Lite ---
+    {
+        modelId: 'gemini-3.5-flash-lite',
+        providerId: 'gemini',
+        displayName: 'Gemini 3.5 Flash-Lite',
+        description: 'Lowest-cost Gemini 3.5 tier, for high-volume and latency-sensitive work.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 0.30,
+        pricePer1MTokensOutput: 2.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-3.1-flash-lite',
+        providerId: 'gemini',
+        displayName: 'Gemini 3.1 Flash-Lite',
+        description: 'Lowest-cost Gemini 3.1 tier. Google lists a shutdown date of 2027-05-07.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 0.25,
+        pricePer1MTokensOutput: 1.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    // --- Floating aliases. Google can repoint these without changing the id, so
+    // a price here can go stale unnoticed. They are listed because an unlisted id
+    // resolves to undefined and meters at zero. generateContent reported these
+    // targets on 2026-09-29 (response modelVersion): pro-latest to 3.1 Pro,
+    // flash-latest to 3.8 Flash, flash-lite-latest to 3.5 Flash-Lite. ---
+    {
+        modelId: 'gemini-pro-latest',
+        providerId: 'gemini',
+        displayName: 'Gemini Pro (latest alias)',
+        description: 'Alias of the current pro-tier model (gemini-3.1-pro-preview as of 2026-09-30).',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        // Priced as the model the alias resolves to today.
+        pricePer1MTokensInput: 2.00,
+        pricePer1MTokensOutput: 12.00,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-flash-latest',
+        providerId: 'gemini',
+        displayName: 'Gemini Flash (latest)',
+        description: 'Floating alias for the current Gemini Flash tier.',
         capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
         contextWindowSize: 1048576,
         outputTokenLimit: 65536,
-        pricePer1MTokensInput: 0.15,
-        pricePer1MTokensOutput: 0.60,
+        pricePer1MTokensInput: 1.50,
+        pricePer1MTokensOutput: 7.50,
         supportsStreaming: true,
         status: 'active',
     },
+    {
+        modelId: 'gemini-flash-lite-latest',
+        providerId: 'gemini',
+        displayName: 'Gemini Flash-Lite (latest)',
+        description: 'Floating alias for the current Gemini Flash-Lite tier.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 0.30,
+        pricePer1MTokensOutput: 2.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    // --- Gemini 2.5 ---
     {
         modelId: 'gemini-2.5-pro',
         providerId: 'gemini',
         displayName: 'Gemini 2.5 Pro',
-        description: 'Most capable Gemini model for complex reasoning and analysis.',
+        description: 'Previous-generation Pro model.',
         capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
         contextWindowSize: 1048576,
         outputTokenLimit: 65536,
@@ -35,31 +302,93 @@ const GEMINI_MODELS = [
         supportsStreaming: true,
         status: 'active',
     },
+    {
+        modelId: 'gemini-2.5-flash',
+        providerId: 'gemini',
+        displayName: 'Gemini 2.5 Flash',
+        description: 'Previous-generation Flash model with reasoning and multimodal input.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 0.30,
+        pricePer1MTokensOutput: 2.50,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-2.5-flash-lite',
+        providerId: 'gemini',
+        displayName: 'Gemini 2.5 Flash-Lite',
+        description: 'Cheapest Gemini model served.',
+        capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
+        contextWindowSize: 1048576,
+        outputTokenLimit: 65536,
+        pricePer1MTokensInput: 0.10,
+        pricePer1MTokensOutput: 0.40,
+        supportsStreaming: true,
+        status: 'active',
+    },
+    // --- Embeddings. Both ids accept embedContent and batchEmbedContents and
+    // return 3072-dimension vectors (probed 2026-09-29). Google's pricing page
+    // lists gemini-embedding-2 at $0.20 per 1M text tokens and carries no price
+    // for gemini-embedding-001, so that row leaves its price unset: an unset
+    // price reads as unknown to a caller, where 0 would read as free. ---
+    {
+        modelId: 'gemini-embedding-2',
+        providerId: 'gemini',
+        displayName: 'Gemini Embedding 2',
+        description: 'Multimodal embedding model mapping text, images, video, audio and PDFs into one vector space.',
+        capabilities: ['embeddings'],
+        contextWindowSize: 8192,
+        inputTokenLimit: 8192,
+        embeddingDimension: 3072,
+        pricePer1MTokensInput: 0.20,
+        pricePer1MTokensTotal: 0.20,
+        supportsStreaming: false,
+        status: 'active',
+    },
+    {
+        modelId: 'gemini-embedding-001',
+        providerId: 'gemini',
+        displayName: 'Gemini Embedding 001',
+        description: 'Text embedding model. An index built with it needs it for queries too, since vectors from different embedding models are not comparable.',
+        capabilities: ['embeddings'],
+        contextWindowSize: 2048,
+        inputTokenLimit: 2048,
+        embeddingDimension: 3072,
+        supportsStreaming: false,
+        status: 'active',
+    },
+    // --- Retired by Google. generateContent returns HTTP 404 for both ids
+    // ("This model models/gemini-2.0-flash is no longer available" for 2.0
+    // Flash), probed 2026-09-29 with a gemini-2.5-flash-lite control returning
+    // 200. The rows stay as `deprecated` so getModelInfo still answers for a
+    // caller holding either id. ---
     {
         modelId: 'gemini-2.0-flash',
         providerId: 'gemini',
-        displayName: 'Gemini 2.0 Flash',
-        description: 'Previous-generation fast model with strong performance.',
+        displayName: 'Gemini 2.0 Flash (retired)',
+        description: 'Retired by Google and no longer served. Google names gemini-3.8-flash as its replacement.',
         capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
         contextWindowSize: 1048576,
         outputTokenLimit: 8192,
         pricePer1MTokensInput: 0.10,
         pricePer1MTokensOutput: 0.40,
         supportsStreaming: true,
-        status: 'active',
+        status: 'deprecated',
     },
     {
         modelId: 'gemini-1.5-pro',
         providerId: 'gemini',
-        displayName: 'Gemini 1.5 Pro',
-        description: 'Stable model with 2M context window for long-document tasks.',
+        displayName: 'Gemini 1.5 Pro (retired)',
+        description: 'Retired by Google and no longer served. Use gemini-3.1-pro-preview.',
         capabilities: ['chat', 'tool_use', 'vision_input', 'json_mode'],
         contextWindowSize: 2097152,
         outputTokenLimit: 8192,
         pricePer1MTokensInput: 1.25,
         pricePer1MTokensOutput: 5.00,
         supportsStreaming: true,
-        status: 'active',
+        status: 'deprecated',
     },
 ];
 // ---------------------------------------------------------------------------
@@ -152,9 +481,39 @@ export class GeminiProvider {
         const payload = this.buildRequestPayload(modelId, messages, options);
         // Gemini uses model-scoped endpoints: /models/{model}:generateContent
         const endpoint = `/models/${modelId}:generateContent`;
-        const apiResponse = await this.makeApiRequest(endpoint, payload, options.requestTimeout);
+        let apiResponse;
+        try {
+            apiResponse = await this.makeApiRequest(endpoint, payload, options.requestTimeout);
+        }
+        catch (error) {
+            // A retired pinned id: serve the call from its alias, whose response
+            // reports the alias as the model that answered.
+            const alias = this.retiredModelAlias(modelId, error);
+            if (!alias)
+                throw error;
+            return this.generateCompletion(alias, messages, options);
+        }
         return this.mapResponseToCompletion(apiResponse, modelId);
     }
+    /**
+     * The alias to retry on when a request for `modelId` failed because the id
+     * is gone: HTTP 404 on an id listed in {@link GEMINI_RETIRED_MODEL_ALIAS}.
+     * `undefined` for every other error and every other id, which propagate.
+     * Warns once per retired id.
+     */
+    retiredModelAlias(modelId, error) {
+        if (!(error instanceof GeminiProviderError) || error.httpStatus !== 404)
+            return undefined;
+        const alias = GEMINI_RETIRED_MODEL_ALIAS[modelId];
+        if (!alias)
+            return undefined;
+        if (!warnedRetiredGeminiModels.has(modelId)) {
+            warnedRetiredGeminiModels.add(modelId);
+            console.warn(`[GeminiProvider] ${modelId} answered 404 (retired, or not available to this key); ` +
+                `serving ${alias} instead. Update the pin.`);
+        }
+        return alias;
+    }
     // -------------------------------------------------------------------------
     // Chat completions (streaming)
     // -------------------------------------------------------------------------
@@ -186,7 +545,19 @@ export class GeminiProvider {
         }
         // Streaming endpoint uses ?alt=sse and the API key query param
         const endpoint = `/models/${modelId}:streamGenerateContent`;
-        const stream = await this.makeStreamRequest(endpoint, payload, options.requestTimeout);
+        let stream;
+        try {
+            stream = await this.makeStreamRequest(endpoint, payload, options.requestTimeout);
+        }
+        catch (error) {
+            // A retired pinned id fails here, before any chunk: serve the whole
+            // stream from its alias (its chunks carry the alias as modelId).
+            const alias = this.retiredModelAlias(modelId, error);
+            if (!alias)
+                throw error;
+            yield* this.generateCompletionStream(alias, messages, options);
+            return;
+        }
         // Accumulators for building the complete response
         let accumulatedContent = '';
         let lastFinishReason = null;
@@ -240,6 +611,9 @@ export class GeminiProvider {
                 }
                 const parts = candidate.content?.parts ?? [];
                 for (const part of parts) {
+                    // A thought summary is the model's reasoning; it stays out of the answer.
+                    if (part.thought)
+                        continue;
                     if (part.text !== undefined) {
                         // Text delta
                         accumulatedContent += part.text;
@@ -263,6 +637,7 @@ export class GeminiProvider {
                         toolCallAccum.set(idx, {
                             name: part.functionCall.name,
                             args: part.functionCall.args,
+                            thoughtSignature: part.thoughtSignature,
                         });
                         yield {
                             id: responseId,
@@ -283,6 +658,7 @@ export class GeminiProvider {
                                         // Gemini delivers complete args, so emit them as a single delta
                                         arguments_delta: JSON.stringify(part.functionCall.args),
                                     },
+                                    ...(part.thoughtSignature ? { thoughtSignature: part.thoughtSignature } : {}),
                                 }],
                         };
                     }
@@ -347,10 +723,20 @@ export class GeminiProvider {
     /**
      * Generates embeddings using Gemini's embedding models.
      *
-     * Uses the `models/{model}:embedContent` endpoint. Currently Gemini
-     * supports embedding one text at a time, so we batch sequentially.
+     * Sends the texts through `models/{model}:batchEmbedContents` in chunks of
+     * at most {@link GEMINI_EMBED_BATCH_LIMIT}, one request per chunk, and
+     * returns the vectors in input order. gemini-embedding-001 and
+     * gemini-embedding-2 both accept batchEmbedContents (probed 2026-09-29),
+     * although neither lists it in `supportedGenerationMethods`.
+     * `options.dimensions` is sent as `outputDimensionality`, which both models
+     * honor (768 and 1536 probed 2026-09-29); without it they return 3072.
+     * Usage sums each call's `usageMetadata.promptTokenCount`, which
+     * gemini-embedding-2 reports and gemini-embedding-001 omits, so the older
+     * model's calls count zero tokens (probed 2026-09-30). When a later batch
+     * fails, the thrown error carries the earlier batches' usage as
+     * `partialUsage`, since those calls were billed.
      *
-     * @param {string} modelId - Embedding model (e.g., "text-embedding-004").
+     * @param {string} modelId - Embedding model (e.g., "gemini-embedding-001").
      * @param {string[]} texts - Input texts to embed.
      * @param {ProviderEmbeddingOptions} [options] - Optional embedding parameters.
      * @returns {Promise<ProviderEmbeddingResponse>} Embedding vectors.
@@ -358,25 +744,46 @@ export class GeminiProvider {
      */
     async generateEmbeddings(modelId, texts, options) {
         this.ensureInitialized();
-        // Gemini's batch embedding endpoint
         const endpoint = `/models/${modelId}:batchEmbedContents`;
-        const requests = texts.map(text => ({
-            model: `models/${modelId}`,
-            content: { parts: [{ text }] },
-        }));
-        const apiResponse = await this.makeApiRequest(endpoint, { requests });
+        const pricePer1M = GEMINI_MODELS.find(m => m.modelId === modelId)?.pricePer1MTokensInput;
+        const usageFor = (tokens) => ({
+            prompt_tokens: tokens,
+            total_tokens: tokens,
+            ...(pricePer1M !== undefined && tokens > 0 ? { costUSD: (tokens / 1000000) * pricePer1M } : {}),
+        });
+        const vectors = [];
+        let promptTokens = 0;
+        for (let start = 0; start < texts.length; start += GEMINI_EMBED_BATCH_LIMIT) {
+            const requests = texts.slice(start, start + GEMINI_EMBED_BATCH_LIMIT).map(text => ({
+                model: `models/${modelId}`,
+                content: { parts: [{ text }] },
+                ...(options?.dimensions ? { outputDimensionality: options.dimensions } : {}),
+            }));
+            let apiResponse;
+            try {
+                apiResponse = await this.makeApiRequest(endpoint, { requests });
+            }
+            catch (error) {
+                // The batches before this one were billed; keep their usage on the
+                // error so the caller can still record it.
+                if (start > 0 && error instanceof GeminiProviderError) {
+                    error.partialUsage = usageFor(promptTokens);
+                }
+                throw error;
+            }
+            for (const emb of apiResponse.embeddings)
+                vectors.push(emb.values);
+            promptTokens += apiResponse.usageMetadata?.promptTokenCount ?? 0;
+        }
         return {
             object: 'list',
-            data: apiResponse.embeddings.map((emb, index) => ({
+            data: vectors.map((embedding, index) => ({
                 object: 'embedding',
-                embedding: emb.values,
+                embedding,
                 index,
             })),
             model: modelId,
-            usage: {
-                prompt_tokens: 0, // Gemini does not report embedding token counts
-                total_tokens: 0,
-            },
+            usage: usageFor(promptTokens),
         };
     }
     // -------------------------------------------------------------------------
@@ -458,13 +865,13 @@ export class GeminiProvider {
      * 3. Tool messages mapped to `functionResponse` parts within user turns.
      * 4. OpenAI-style tool definitions converted to `functionDeclarations`.
      *
-     * @param {string} _modelId - Target model (used for endpoint, not in body).
+     * @param {string} modelId - Target model (endpoint; also its output ceiling and thinking levels).
      * @param {ChatMessage[]} messages - Conversation messages.
      * @param {ModelCompletionOptions} options - Completion options.
      * @returns {Record<string, unknown>} The request body for Gemini's API.
      * @private
      */
-    buildRequestPayload(_modelId, messages, options) {
+    buildRequestPayload(modelId, messages, options) {
         // --- Extract system messages into systemInstruction ---
         // Gemini treats system instructions as a separate top-level field,
         // similar to Anthropic but with a `parts` array wrapper.
@@ -499,8 +906,15 @@ export class GeminiProvider {
         const generationConfig = {};
         if (options.temperature !== undefined)
             generationConfig.temperature = options.temperature;
-        if (options.maxTokens !== undefined)
-            generationConfig.maxOutputTokens = options.maxTokens;
+        if (options.maxTokens !== undefined) {
+            // Never above the model's output ceiling: the API rejects the whole
+            // request, and a rescue hop's headroom
+            // (FallbackProviderEntry.maxTokensHeadroom) can lift a large budget
+            // past it. Models outside the catalog pass through unclamped.
+            const outputLimit = GEMINI_MODELS.find(m => m.modelId === modelId)?.outputTokenLimit;
+            generationConfig.maxOutputTokens =
+                typeof outputLimit === 'number' ? Math.min(options.maxTokens, outputLimit) : options.maxTokens;
+        }
         if (options.topP !== undefined)
             generationConfig.topP = options.topP;
         if (options.stopSequences?.length)
@@ -530,6 +944,22 @@ export class GeminiProvider {
         if (options.customModelParams?.topK !== undefined) {
             generationConfig.topK = options.customModelParams.topK;
         }
+        // Thinking depth. A caller-supplied thinkingConfig is forwarded as is;
+        // otherwise the provider-neutral `effort` becomes the model's thinking
+        // level when the model is known to take that level. Thinking shares the
+        // maxOutputTokens cap: room for it on a rescue hop comes from
+        // FallbackProviderEntry.maxTokensHeadroom, not from this provider. The
+        // shared `thinking` option is Anthropic's on-switch and is not translated:
+        // on a fallback hop it would turn "thinking on" into a thinking-token cap.
+        const customThinking = options.customModelParams?.thinkingConfig;
+        if (customThinking && typeof customThinking === 'object') {
+            generationConfig.thinkingConfig = customThinking;
+        }
+        else {
+            const thinkingLevel = geminiThinkingLevelFor(modelId, options.effort);
+            if (thinkingLevel)
+                generationConfig.thinkingConfig = { thinkingLevel };
+        }
         if (Object.keys(generationConfig).length > 0) {
             payload.generationConfig = generationConfig;
         }
@@ -542,7 +972,9 @@ export class GeminiProvider {
         // and never OpenRouter's routing controls — Gemini 400s on unknown
         // top-level names like `provider`; see openrouter-only-params).
         if (options.customModelParams) {
-            const { topK, ...rest } = options.customModelParams;
+            // thinkingConfig belongs inside generationConfig (set above); at the
+            // payload root Gemini rejects it as an unknown field.
+            const { topK, thinkingConfig, ...rest } = options.customModelParams;
             const passthrough = stripOpenRouterOnlyParams(rest);
             if (passthrough) {
                 Object.assign(payload, passthrough);
@@ -572,9 +1004,14 @@ export class GeminiProvider {
                 if (typeof msg.content === 'string' && msg.content) {
                     parts.push({ text: msg.content });
                 }
-                // Convert tool_calls to functionCall parts
+                // Convert tool_calls to functionCall parts. Each call's thought
+                // signature is replayed verbatim. A turn with no signature at all (a
+                // call made by another provider, or history that dropped it) gets the
+                // documented placeholder on its first call, which is where Gemini puts
+                // its own; without one Gemini 3 rejects the request with HTTP 400.
                 if (msg.tool_calls?.length) {
-                    for (const tc of msg.tool_calls) {
+                    const turnHasSignature = msg.tool_calls.some(tc => tc.thoughtSignature);
+                    msg.tool_calls.forEach((tc, i) => {
                         let parsedArgs;
                         try {
                             parsedArgs = typeof tc.function.arguments === 'string'
@@ -584,10 +1021,17 @@ export class GeminiProvider {
                         catch {
                             parsedArgs = {};
                         }
-                        parts.push({
+                        const part = {
                             functionCall: { name: tc.function.name, args: parsedArgs },
-                        });
-                    }
+                        };
+                        if (tc.thoughtSignature) {
+                            part.thoughtSignature = tc.thoughtSignature;
+                        }
+                        else if (!turnHasSignature && i === 0) {
+                            part.thoughtSignature = GEMINI_SKIP_THOUGHT_SIGNATURE;
+                        }
+                        parts.push(part);
+                    });
                 }
                 // Ensure at least one part — Gemini requires non-empty parts
                 if (parts.length === 0) {
@@ -692,8 +1136,10 @@ export class GeminiProvider {
         const candidate = apiResponse.candidates?.[0];
         const parts = candidate?.content?.parts ?? [];
         // Collect text from all text parts
+        // Thought-summary parts (present only with includeThoughts) are the
+        // model's reasoning and stay out of the answer.
         const textParts = parts
-            .filter(p => p.text !== undefined)
+            .filter(p => p.text !== undefined && !p.thought)
             .map(p => p.text);
         const fullText = textParts.join('');
         // Collect function calls and convert to OpenAI-style tool_calls
@@ -706,6 +1152,7 @@ export class GeminiProvider {
                 name: p.functionCall.name,
                 arguments: JSON.stringify(p.functionCall.args ?? {}),
             },
+            ...(p.thoughtSignature ? { thoughtSignature: p.thoughtSignature } : {}),
         }));
         const hasToolCalls = toolCalls.length > 0;
         const finishReason = this.mapFinishReason(candidate?.finishReason ?? null);
@@ -768,7 +1215,12 @@ export class GeminiProvider {
      */
     mapUsage(meta, modelId) {
         const promptTokens = meta?.promptTokenCount ?? 0;
-        const completionTokens = meta?.candidatesTokenCount ?? 0;
+        // Thinking tokens are output the model generated and Google bills at the
+        // output rate ("output price, including thinking tokens"), reported apart
+        // from candidatesTokenCount. Counted here so completion tokens and cost
+        // match the bill — the same convention as OpenAI's completion_tokens,
+        // which includes reasoning tokens.
+        const completionTokens = (meta?.candidatesTokenCount ?? 0) + (meta?.thoughtsTokenCount ?? 0);
         const totalTokens = meta?.totalTokenCount ?? (promptTokens + completionTokens);
         // Gemini implicit caching (default-on for 2.5+) reports the cached
         // subset of promptTokenCount in cachedContentTokenCount; normalize it
@@ -805,6 +1257,7 @@ export class GeminiProvider {
                 name: tc.name,
                 arguments: JSON.stringify(tc.args ?? {}),
             },
+            ...(tc.thoughtSignature ? { thoughtSignature: tc.thoughtSignature } : {}),
         }));
     }
     /**
@@ -823,8 +1276,13 @@ export class GeminiProvider {
         const info = GEMINI_MODELS.find(m => m.modelId === modelId);
         if (!info?.pricePer1MTokensInput || !info?.pricePer1MTokensOutput)
             return undefined;
-        return ((inputTokens / 1000000) * info.pricePer1MTokensInput +
-            (outputTokens / 1000000) * info.pricePer1MTokensOutput);
+        // Long prompts bill the whole request at a higher tier on some models.
+        const longContext = GEMINI_LONG_CONTEXT_PRICING[modelId];
+        const isLong = longContext !== undefined && inputTokens > longContext.abovePromptTokens;
+        const inputRate = isLong ? longContext.input : info.pricePer1MTokensInput;
+        const outputRate = isLong ? longContext.output : info.pricePer1MTokensOutput;
+        return ((inputTokens / 1000000) * inputRate +
+            (outputTokens / 1000000) * outputRate);
     }
     /**
      * Builds an abort chunk for early stream termination.
@@ -862,7 +1320,8 @@ export class GeminiProvider {
      */
     async makeApiRequest(endpoint, body, requestTimeoutOverride) {
         // API key is passed as query parameter — Gemini's auth convention
-        const url = `${this.config.baseURL}${endpoint}?key=${this.keyPool?.hasKeys ? this.keyPool.next() : this.config.apiKey}`;
+        const apiKey = this.keyPool?.hasKeys ? this.keyPool.next() : this.config.apiKey;
+        const url = `${this.config.baseURL}${endpoint}?key=${apiKey}`;
         const headers = {
             'Content-Type': 'application/json',
             'User-Agent': 'AgentOS/1.0 (GeminiProvider)',
@@ -922,7 +1381,9 @@ export class GeminiProvider {
                     lastError = new GeminiProviderError(`Request timed out after ${effectiveTimeout}ms.`, 'REQUEST_TIMEOUT');
                 }
                 else {
-                    lastError = new GeminiProviderError(error instanceof Error ? error.message : 'Network or unknown error', 'NETWORK_ERROR');
+                    lastError = new GeminiProviderError(error instanceof Error
+                        ? redactUrlSecrets(error.message, apiKey, this.config.baseURL)
+                        : 'Network or unknown error', 'NETWORK_ERROR');
                 }
                 if (attempt === this.config.maxRetries - 1)
                     break;
@@ -947,7 +1408,8 @@ export class GeminiProvider {
      */
     async makeStreamRequest(endpoint, body, requestTimeoutOverride) {
         // Both alt=sse and key= are query params
-        const url = `${this.config.baseURL}${endpoint}?alt=sse&key=${this.keyPool?.hasKeys ? this.keyPool.next() : this.config.apiKey}`;
+        const apiKey = this.keyPool?.hasKeys ? this.keyPool.next() : this.config.apiKey;
+        const url = `${this.config.baseURL}${endpoint}?alt=sse&key=${apiKey}`;
         const headers = {
             'Content-Type': 'application/json',
             'User-Agent': 'AgentOS/1.0 (GeminiProvider)',
@@ -980,7 +1442,9 @@ export class GeminiProvider {
             clearTimeout(timeoutId);
             if (error instanceof GeminiProviderError)
                 throw error;
-            throw new GeminiProviderError(error instanceof Error ? error.message : 'Failed to connect to Gemini stream.', 'STREAM_CONNECTION_FAILED');
+            throw new GeminiProviderError(error instanceof Error
+                ? redactUrlSecrets(error.message, apiKey, this.config.baseURL)
+                : 'Failed to connect to Gemini stream.', 'STREAM_CONNECTION_FAILED');
         }
     }
     // -------------------------------------------------------------------------