@juspay/neurolink 9.82.0 → 9.83.0

package/dist/lib/providers/googleAiStudio.js

@@ -584,6 +584,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let lastStepText = "";
                     let totalInputTokens = 0;
                     let totalOutputTokens = 0;
+                    let totalCacheReadTokens = 0;
                     let step = 0;
                     let completedWithFinalAnswer = false;
                     const failedTools = new Map();
@@ -614,6 +615,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 const chunkResult = await collectStreamChunksIncremental(rawStream, channel);
                                 totalInputTokens += chunkResult.inputTokens;
                                 totalOutputTokens += chunkResult.outputTokens;
+                                totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                                 const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                                 // If no function calls, this was the final step — channel
                                 // already received all text parts incrementally.
@@ -698,13 +700,23 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         span.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, totalInputTokens);
                         span.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, totalOutputTokens);
                         span.setAttribute(ATTR.GEN_AI_FINISH_REASON, hitStepLimitWithoutFinalAnswer ? "max_steps" : "stop");
+                        // Gemini promptTokenCount is OVERLAPPING: it already includes
+                        // cachedContentTokenCount. Subtract once here so calculateCost
+                        // bills the cached portion at the cheaper cacheRead rate without
+                        // double-counting. Total billable tokens are conserved.
+                        const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                         analyticsResolve({
                             provider: this.providerName,
                             model: modelName,
                             tokenUsage: {
-                                input: totalInputTokens,
+                                input: adjustedInputTokens,
                                 output: totalOutputTokens,
-                                total: totalInputTokens + totalOutputTokens,
+                                total: adjustedInputTokens +
+                                    totalCacheReadTokens +
+                                    totalOutputTokens,
+                                ...(totalCacheReadTokens > 0
+                                    ? { cacheReadTokens: totalCacheReadTokens }
+                                    : {}),
                             },
                             requestDuration: responseTime,
                             timestamp: new Date().toISOString(),
@@ -831,6 +843,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 let lastStepText = "";
                 let totalInputTokens = 0;
                 let totalOutputTokens = 0;
+                let totalCacheReadTokens = 0;
                 const allToolCalls = [];
                 const toolExecutions = [];
                 let step = 0;
@@ -856,6 +869,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         const chunkResult = await collectStreamChunks(stream);
                         totalInputTokens += chunkResult.inputTokens;
                         totalOutputTokens += chunkResult.outputTokens;
+                        totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                         const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                         // If no function calls, we're done
                         if (chunkResult.stepFunctionCalls.length === 0) {
@@ -927,14 +941,21 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 // analytics / evaluation / tracing stay attached. The native AI
                 // Studio generate path bypasses BaseProvider.generate(), so
                 // skipping enhanceResult would silently drop those features.
+                // Gemini promptTokenCount is OVERLAPPING (already includes
+                // cachedContentTokenCount). Subtract once so the cached portion is
+                // billed at the cheaper cacheRead rate without double-counting.
+                const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                 const baseResult = {
                     content: finalText,
                     provider: this.providerName,
                     model: modelName,
                     usage: {
-                        input: totalInputTokens,
+                        input: adjustedInputTokens,
                         output: totalOutputTokens,
-                        total: totalInputTokens + totalOutputTokens,
+                        total: adjustedInputTokens + totalCacheReadTokens + totalOutputTokens,
+                        ...(totalCacheReadTokens > 0
+                            ? { cacheReadTokens: totalCacheReadTokens }
+                            : {}),
                     },
                     responseTime,
                     toolsUsed: allToolCalls.map((tc) => tc.toolName),

package/dist/lib/providers/googleNativeGemini3.js

@@ -514,6 +514,7 @@ export async function collectStreamChunks(stream) {
     const stepFunctionCalls = [];
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheReadTokens = 0;
     for await (const chunk of stream) {
         // Extract raw parts from candidates FIRST
         // This avoids using chunk.text which triggers SDK warning when
@@ -533,9 +534,18 @@ export async function collectStreamChunks(stream) {
         if (usage) {
             inputTokens = Math.max(inputTokens, usage.promptTokenCount || 0);
             outputTokens = Math.max(outputTokens, usage.candidatesTokenCount || 0);
+            // cachedContentTokenCount is OVERLAPPING (a subset already inside
+            // promptTokenCount). Surface it so the call site subtracts once.
+            cacheReadTokens = Math.max(cacheReadTokens, usage.cachedContentTokenCount || 0);
         }
     }
-    return { rawResponseParts, stepFunctionCalls, inputTokens, outputTokens };
+    return {
+        rawResponseParts,
+        stepFunctionCalls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+    };
 }
 /**
  * Create a push-based text channel that bridges a background producer
@@ -627,6 +637,7 @@ export async function collectStreamChunksIncremental(stream, channel) {
     const stepFunctionCalls = [];
     let inputTokens = 0;
     let outputTokens = 0;
+    let cacheReadTokens = 0;
     for await (const chunk of stream) {
         const chunkRecord = chunk;
         const candidates = chunkRecord.candidates;
@@ -648,9 +659,18 @@ export async function collectStreamChunksIncremental(stream, channel) {
         if (usage) {
             inputTokens = Math.max(inputTokens, usage.promptTokenCount || 0);
             outputTokens = Math.max(outputTokens, usage.candidatesTokenCount || 0);
+            // cachedContentTokenCount is OVERLAPPING (a subset already inside
+            // promptTokenCount). Surface it so the call site subtracts once.
+            cacheReadTokens = Math.max(cacheReadTokens, usage.cachedContentTokenCount || 0);
         }
     }
-    return { rawResponseParts, stepFunctionCalls, inputTokens, outputTokens };
+    return {
+        rawResponseParts,
+        stepFunctionCalls,
+        inputTokens,
+        outputTokens,
+        cacheReadTokens,
+    };
 }
 /**
  * Extract the thoughtSignature token from raw response parts.

package/dist/lib/providers/googleVertex.js

@@ -1325,6 +1325,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // promptTokenCount is typically in the final chunk, candidatesTokenCount accumulates
         let totalInputTokens = 0;
         let totalOutputTokens = 0;
+        let totalCacheReadTokens = 0;
         // Track text parts as they arrive from the SDK so the returned async
         // iterable yields multiple chunks instead of a single buffered chunk.
         // The CLI's chunk-count smoke test asserts > 1 stream chunks for any
@@ -1440,6 +1441,10 @@ export class GoogleVertexProvider extends BaseProvider {
                                 totalInputTokens = usageMetadata.promptTokenCount;
                                 // Feed the context guard the REAL prompt size of this call.
                                 contextGuard.noteUsage(usageMetadata.promptTokenCount, usageMetadata.candidatesTokenCount ?? 0);
+                                // cachedContentTokenCount is OVERLAPPING (a subset already inside
+                                // promptTokenCount). Clamp to the prompt count so a later uncached
+                                // step resets it to 0 instead of leaving a stale cached value.
+                                totalCacheReadTokens = Math.min(usageMetadata.cachedContentTokenCount ?? 0, usageMetadata.promptTokenCount);
                             }
                             // Take the latest candidatesTokenCount (accumulates through chunks)
                             if (usageMetadata.candidatesTokenCount !== undefined &&
@@ -1891,6 +1896,10 @@ export class GoogleVertexProvider extends BaseProvider {
         // Filter out final_result from tool calls as it's an internal pattern
         const externalToolCalls = allToolCalls.filter((tc) => tc.toolName !== "final_result");
         const externalToolExecutions = toolExecutions.filter((te) => te.name !== "final_result");
+        // Gemini promptTokenCount is OVERLAPPING (already includes
+        // cachedContentTokenCount). Subtract once so the cached portion is billed at
+        // the cheaper cacheRead rate without double-counting; total is conserved.
+        const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
         const result = {
             stream: createTextStream(),
             provider: this.providerName,
@@ -1899,9 +1908,12 @@ export class GoogleVertexProvider extends BaseProvider {
             stopReason,
             rawFinishReason: lastFinishReason,
             usage: {
-                input: totalInputTokens,
+                input: adjustedInputTokens,
                 output: totalOutputTokens,
-                total: totalInputTokens + totalOutputTokens,
+                total: adjustedInputTokens + totalCacheReadTokens + totalOutputTokens,
+                ...(totalCacheReadTokens > 0 && {
+                    cacheReadTokens: totalCacheReadTokens,
+                }),
             },
             toolCalls: externalToolCalls.map((tc) => ({
                 toolName: tc.toolName,
@@ -2254,6 +2266,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // promptTokenCount is typically in the final chunk, candidatesTokenCount accumulates
         let totalInputTokens = 0;
         let totalOutputTokens = 0;
+        let totalCacheReadTokens = 0;
         // Abort scaffolding (mirrors executeNativeAnthropicStream). The native
         // Gemini SDK cancels via config.abortSignal, so drive an internal
         // AbortController: the caller's signal and the turn clock's watchdogs
@@ -2359,6 +2372,10 @@ export class GoogleVertexProvider extends BaseProvider {
                                 totalInputTokens = usageMetadata.promptTokenCount;
                                 // Feed the context guard the REAL prompt size of this call.
                                 contextGuard.noteUsage(usageMetadata.promptTokenCount, usageMetadata.candidatesTokenCount ?? 0);
+                                // cachedContentTokenCount is OVERLAPPING (a subset already inside
+                                // promptTokenCount). Clamp to the prompt count so a later uncached
+                                // step resets it to 0 instead of leaving a stale cached value.
+                                totalCacheReadTokens = Math.min(usageMetadata.cachedContentTokenCount ?? 0, usageMetadata.promptTokenCount);
                             }
                             // Take the latest candidatesTokenCount (accumulates through chunks)
                             if (usageMetadata.candidatesTokenCount !== undefined &&
@@ -2789,6 +2806,10 @@ export class GoogleVertexProvider extends BaseProvider {
         const externalToolCalls = allToolCalls.filter((tc) => tc.toolName !== "final_result");
         const externalToolExecutions = toolExecutions.filter((te) => te.name !== "final_result");
         // Build EnhancedGenerateResult
+        // Gemini promptTokenCount is OVERLAPPING (already includes
+        // cachedContentTokenCount). Subtract once so the cached portion is billed at
+        // the cheaper cacheRead rate without double-counting; total is conserved.
+        const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
         const result = {
             content: finalText,
             provider: this.providerName,
@@ -2798,9 +2819,12 @@ export class GoogleVertexProvider extends BaseProvider {
             rawFinishReason: lastFinishReason,
             stepsUsed: step,
             usage: {
-                input: totalInputTokens,
+                input: adjustedInputTokens,
                 output: totalOutputTokens,
-                total: totalInputTokens + totalOutputTokens,
+                total: adjustedInputTokens + totalCacheReadTokens + totalOutputTokens,
+                ...(totalCacheReadTokens > 0 && {
+                    cacheReadTokens: totalCacheReadTokens,
+                }),
             },
             responseTime,
             toolsUsed: externalToolCalls.map((tc) => tc.toolName),

package/dist/lib/types/common.d.ts

@@ -223,6 +223,9 @@ export type RawUsageObject = {
     cacheReadInputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    prompt_tokens_details?: {
+        cached_tokens?: number;
+    };
     reasoningTokens?: number;
     reasoning?: number;
     reasoning_tokens?: number;

package/dist/lib/types/providers.d.ts

@@ -1597,6 +1597,14 @@ export type CollectedChunkResult = {
     stepFunctionCalls: NativeFunctionCall[];
     inputTokens: number;
     outputTokens: number;
+    /**
+     * Gemini cached-content tokens (overlapping: included in promptTokenCount).
+     * Surfaced so the call site can subtract from input and bill at cacheRead
+     * rate. Subtraction happens at the call site, not in the collector.
+     */
+    cacheReadTokens?: number;
+    /** Cache creation tokens (symmetry; Gemini does not emit this). */
+    cacheCreationTokens?: number;
 };
 /** Push-based text channel for incremental streaming. */
 export type TextChannel = {

package/dist/lib/utils/pricing.js

@@ -87,8 +87,18 @@ const PRICING = {
             cacheRead: 1.5 / 1_000_000,
             cacheCreation: 18.75 / 1_000_000,
         },
-        "claude-3-sonnet": { input: 3.0 / 1_000_000, output: 15.0 / 1_000_000 },
-        "claude-3-haiku": { input: 0.25 / 1_000_000, output: 1.25 / 1_000_000 },
+        "claude-3-sonnet": {
+            input: 3.0 / 1_000_000,
+            output: 15.0 / 1_000_000,
+            cacheRead: 0.3 / 1_000_000,
+            cacheCreation: 3.75 / 1_000_000,
+        },
+        "claude-3-haiku": {
+            input: 0.25 / 1_000_000,
+            output: 1.25 / 1_000_000,
+            cacheRead: 0.025 / 1_000_000,
+            cacheCreation: 0.3125 / 1_000_000,
+        },
     },
     // Google Vertex AI — Claude models on Vertex (same pricing, @ date suffix)
     vertex: {
@@ -138,26 +148,95 @@ const PRICING = {
     // OpenAI — updated March 2026
     openai: {
         // GPT-5.x family
-        "gpt-5.4": { input: 2.5 / 1_000_000, output: 15.0 / 1_000_000 },
-        "gpt-5.2": { input: 1.75 / 1_000_000, output: 14.0 / 1_000_000 },
-        "gpt-5.1": { input: 0.625 / 1_000_000, output: 5.0 / 1_000_000 },
-        "gpt-5.1-codex": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
-        "gpt-5": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
-        "gpt-5-mini": { input: 0.25 / 1_000_000, output: 2.0 / 1_000_000 },
-        "gpt-5-nano": { input: 0.05 / 1_000_000, output: 0.4 / 1_000_000 },
+        // cacheRead = 0.25x input (cached input tokens; no separate cacheCreation).
+        "gpt-5.4": {
+            input: 2.5 / 1_000_000,
+            output: 15.0 / 1_000_000,
+            cacheRead: 0.625 / 1_000_000,
+        },
+        "gpt-5.2": {
+            input: 1.75 / 1_000_000,
+            output: 14.0 / 1_000_000,
+            cacheRead: 0.4375 / 1_000_000,
+        },
+        "gpt-5.1": {
+            input: 0.625 / 1_000_000,
+            output: 5.0 / 1_000_000,
+            cacheRead: 0.15625 / 1_000_000,
+        },
+        "gpt-5.1-codex": {
+            input: 1.25 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
+        "gpt-5": {
+            input: 1.25 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
+        "gpt-5-mini": {
+            input: 0.25 / 1_000_000,
+            output: 2.0 / 1_000_000,
+            cacheRead: 0.0625 / 1_000_000,
+        },
+        "gpt-5-nano": {
+            input: 0.05 / 1_000_000,
+            output: 0.4 / 1_000_000,
+            cacheRead: 0.0125 / 1_000_000,
+        },
         // GPT-4.1 family
-        "gpt-4.1": { input: 2.0 / 1_000_000, output: 8.0 / 1_000_000 },
-        "gpt-4.1-mini": { input: 0.4 / 1_000_000, output: 1.6 / 1_000_000 },
-        "gpt-4.1-nano": { input: 0.1 / 1_000_000, output: 0.4 / 1_000_000 },
+        "gpt-4.1": {
+            input: 2.0 / 1_000_000,
+            output: 8.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+        },
+        "gpt-4.1-mini": {
+            input: 0.4 / 1_000_000,
+            output: 1.6 / 1_000_000,
+            cacheRead: 0.1 / 1_000_000,
+        },
+        "gpt-4.1-nano": {
+            input: 0.1 / 1_000_000,
+            output: 0.4 / 1_000_000,
+            cacheRead: 0.025 / 1_000_000,
+        },
         // GPT-4o family
-        "gpt-4o": { input: 2.5 / 1_000_000, output: 10.0 / 1_000_000 },
-        "gpt-4o-mini": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+        "gpt-4o": {
+            input: 2.5 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.625 / 1_000_000,
+        },
+        "gpt-4o-mini": {
+            input: 0.15 / 1_000_000,
+            output: 0.6 / 1_000_000,
+            cacheRead: 0.0375 / 1_000_000,
+        },
         // o-series reasoning
-        o3: { input: 2.0 / 1_000_000, output: 8.0 / 1_000_000 },
-        "o3-mini": { input: 1.1 / 1_000_000, output: 4.4 / 1_000_000 },
-        "o4-mini": { input: 1.1 / 1_000_000, output: 4.4 / 1_000_000 },
-        o1: { input: 15.0 / 1_000_000, output: 60.0 / 1_000_000 },
-        "o1-mini": { input: 0.55 / 1_000_000, output: 2.2 / 1_000_000 },
+        o3: {
+            input: 2.0 / 1_000_000,
+            output: 8.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+        },
+        "o3-mini": {
+            input: 1.1 / 1_000_000,
+            output: 4.4 / 1_000_000,
+            cacheRead: 0.275 / 1_000_000,
+        },
+        "o4-mini": {
+            input: 1.1 / 1_000_000,
+            output: 4.4 / 1_000_000,
+            cacheRead: 0.275 / 1_000_000,
+        },
+        o1: {
+            input: 15.0 / 1_000_000,
+            output: 60.0 / 1_000_000,
+            cacheRead: 3.75 / 1_000_000,
+        },
+        "o1-mini": {
+            input: 0.55 / 1_000_000,
+            output: 2.2 / 1_000_000,
+            cacheRead: 0.1375 / 1_000_000,
+        },
         // Legacy
         "gpt-4-turbo": { input: 10.0 / 1_000_000, output: 30.0 / 1_000_000 },
         "gpt-4": { input: 30.0 / 1_000_000, output: 60.0 / 1_000_000 },
@@ -166,52 +245,83 @@ const PRICING = {
     // Google (Gemini) — updated March 2026
     google: {
         // Gemini 3.1 family (all require -preview suffix)
+        // cacheRead = 0.25x input (cached content tokens; explicit-cache storage is
+        // billed separately by TTL/time, so no per-token cacheCreation rate here).
         "gemini-3.1-pro-preview": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         "gemini-3.1-flash-lite-preview": {
             input: 0.25 / 1_000_000,
             output: 1.5 / 1_000_000,
+            cacheRead: 0.0625 / 1_000_000,
         },
         "gemini-3.1-flash-image-preview": {
             input: 0.5 / 1_000_000,
             output: 3.0 / 1_000_000,
+            cacheRead: 0.125 / 1_000_000,
         },
         "gemini-3.1-pro-preview-customtools": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         // Gemini 3 family
         "gemini-3-flash-preview": {
             input: 0.5 / 1_000_000,
             output: 3.0 / 1_000_000,
+            cacheRead: 0.125 / 1_000_000,
         },
         "gemini-3-pro-image-preview": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         /** @deprecated SHUT DOWN March 9, 2026. Migrate to gemini-3.1-pro-preview. */
         "gemini-3-pro-preview": {
             input: 2.0 / 1_000_000,
             output: 12.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
         },
         // Gemini 2.5 family
-        "gemini-2.5-flash": { input: 0.3 / 1_000_000, output: 2.5 / 1_000_000 },
-        "gemini-2.5-pro": { input: 1.25 / 1_000_000, output: 10.0 / 1_000_000 },
+        "gemini-2.5-flash": {
+            input: 0.3 / 1_000_000,
+            output: 2.5 / 1_000_000,
+            cacheRead: 0.075 / 1_000_000,
+        },
+        "gemini-2.5-pro": {
+            input: 1.25 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
         "gemini-2.5-flash-lite": {
             input: 0.1 / 1_000_000,
             output: 0.4 / 1_000_000,
+            cacheRead: 0.025 / 1_000_000,
         },
         // Gemini 2.0 family (deprecated June 2026)
-        "gemini-2.0-flash": { input: 0.15 / 1_000_000, output: 0.6 / 1_000_000 },
+        "gemini-2.0-flash": {
+            input: 0.15 / 1_000_000,
+            output: 0.6 / 1_000_000,
+            cacheRead: 0.0375 / 1_000_000,
+        },
         "gemini-2.0-flash-lite": {
             input: 0.075 / 1_000_000,
             output: 0.3 / 1_000_000,
+            cacheRead: 0.01875 / 1_000_000,
         },
         // Gemini 1.5 family
-        "gemini-1.5-pro": { input: 1.25 / 1_000_000, output: 5.0 / 1_000_000 },
-        "gemini-1.5-flash": { input: 0.075 / 1_000_000, output: 0.3 / 1_000_000 },
+        "gemini-1.5-pro": {
+            input: 1.25 / 1_000_000,
+            output: 5.0 / 1_000_000,
+            cacheRead: 0.3125 / 1_000_000,
+        },
+        "gemini-1.5-flash": {
+            input: 0.075 / 1_000_000,
+            output: 0.3 / 1_000_000,
+            cacheRead: 0.01875 / 1_000_000,
+        },
     },
     // Mistral AI
     mistral: {
@@ -594,8 +704,16 @@ export function calculateCost(provider, model, usage) {
     let cost = 0;
     cost += (usage.input || 0) * rates.input;
     cost += (usage.output || 0) * rates.output;
-    if (usage.cacheReadTokens && rates.cacheRead) {
-        cost += usage.cacheReadTokens * rates.cacheRead;
+    if (usage.cacheReadTokens) {
+        // Price cache reads at the discounted cacheRead rate when one exists;
+        // otherwise fall back to the full input rate. The overlapping extractor
+        // (tokenUtils) moves cached tokens out of `input` into `cacheReadTokens`
+        // for OpenAI/Gemini-family providers, so without this fallback a provider
+        // that reports cached tokens but has no cacheRead rate would bill those
+        // tokens at $0 (silent undercharge). Falling back to the input rate keeps
+        // total cost identical to pre-split billing for unpriced providers, while
+        // priced providers still get the cheaper cacheRead rate.
+        cost += usage.cacheReadTokens * (rates.cacheRead ?? rates.input);
     }
     if (usage.cacheCreationTokens && rates.cacheCreation) {
         cost += usage.cacheCreationTokens * rates.cacheCreation;

package/dist/lib/utils/tokenUtils.d.ts

@@ -38,6 +38,17 @@ export declare function extractCacheCreationTokens(usage: RawUsageObject): numbe
  * Supports: cacheReadInputTokens, cacheReadTokens
  */
 export declare function extractCacheReadTokens(usage: RawUsageObject): number | undefined;
+/**
+ * Extract cache read token count from the OVERLAPPING-convention nested path
+ * used by OpenAI / DeepSeek / NIM / OpenAI-compatible providers:
+ * `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Unlike {@link extractCacheReadTokens} (non-overlapping Anthropic/Vertex
+ * convention where cache tokens are reported SEPARATELY from input), the value
+ * returned here is a SUBSET already included in `prompt_tokens`. Callers that
+ * use this value MUST subtract it from `input` to avoid double-counting.
+ */
+export declare function extractCachedInputTokensOverlapping(usage: RawUsageObject): number | undefined;
 /**
  * Calculate cache savings percentage
  *

package/dist/lib/utils/tokenUtils.js

@@ -101,6 +101,23 @@ export function extractCacheReadTokens(usage) {
     }
     return undefined;
 }
+/**
+ * Extract cache read token count from the OVERLAPPING-convention nested path
+ * used by OpenAI / DeepSeek / NIM / OpenAI-compatible providers:
+ * `usage.prompt_tokens_details.cached_tokens`.
+ *
+ * Unlike {@link extractCacheReadTokens} (non-overlapping Anthropic/Vertex
+ * convention where cache tokens are reported SEPARATELY from input), the value
+ * returned here is a SUBSET already included in `prompt_tokens`. Callers that
+ * use this value MUST subtract it from `input` to avoid double-counting.
+ */
+export function extractCachedInputTokensOverlapping(usage) {
+    const cached = usage.prompt_tokens_details?.cached_tokens;
+    if (typeof cached === "number" && cached > 0) {
+        return cached;
+    }
+    return undefined;
+}
 /**
  * Calculate cache savings percentage
  *
@@ -149,13 +166,27 @@ export function extractTokenUsage(result, options = {}) {
     // Handle nested usage object (some providers wrap usage in a usage property)
     const usage = result.usage && typeof result.usage === "object" ? result.usage : result;
     // Extract base token counts
-    const input = extractInputTokens(usage);
+    let input = extractInputTokens(usage);
     const output = extractOutputTokens(usage);
     const total = extractTotalTokens(usage, input, output);
     // Extract optional token fields
     const reasoning = extractReasoningTokens(usage);
     const cacheCreationTokens = extractCacheCreationTokens(usage);
-    const cacheReadTokens = extractCacheReadTokens(usage);
+    let cacheReadTokens = extractCacheReadTokens(usage);
+    // Overlapping-convention fallback (OpenAI/DeepSeek/NIM/OpenAI-compatible):
+    // when no non-overlapping cache-read field was present, look for the nested
+    // `prompt_tokens_details.cached_tokens`. That value is a SUBSET already
+    // included in `input`, so we must subtract it from `input` to avoid
+    // double-counting (and to let calculateCost apply the cheaper cacheRead rate
+    // to the cached portion). Only do this when cached <= input so a malformed
+    // response can never produce negative input or inflate the total.
+    if (cacheReadTokens === undefined) {
+        const overlappingCached = extractCachedInputTokensOverlapping(usage);
+        if (overlappingCached !== undefined && overlappingCached <= input) {
+            cacheReadTokens = overlappingCached;
+            input = Math.max(0, input - overlappingCached);
+        }
+    }
     // Calculate cache savings if enabled
     const cacheSavingsPercent = calculateCacheSavings
         ? calculateCacheSavingsPercent(cacheReadTokens, input)

package/dist/providers/googleAiStudio.js

@@ -584,6 +584,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let lastStepText = "";
                     let totalInputTokens = 0;
                     let totalOutputTokens = 0;
+                    let totalCacheReadTokens = 0;
                     let step = 0;
                     let completedWithFinalAnswer = false;
                     const failedTools = new Map();
@@ -614,6 +615,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 const chunkResult = await collectStreamChunksIncremental(rawStream, channel);
                                 totalInputTokens += chunkResult.inputTokens;
                                 totalOutputTokens += chunkResult.outputTokens;
+                                totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                                 const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                                 // If no function calls, this was the final step — channel
                                 // already received all text parts incrementally.
@@ -698,13 +700,23 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         span.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, totalInputTokens);
                         span.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, totalOutputTokens);
                         span.setAttribute(ATTR.GEN_AI_FINISH_REASON, hitStepLimitWithoutFinalAnswer ? "max_steps" : "stop");
+                        // Gemini promptTokenCount is OVERLAPPING: it already includes
+                        // cachedContentTokenCount. Subtract once here so calculateCost
+                        // bills the cached portion at the cheaper cacheRead rate without
+                        // double-counting. Total billable tokens are conserved.
+                        const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                         analyticsResolve({
                             provider: this.providerName,
                             model: modelName,
                             tokenUsage: {
-                                input: totalInputTokens,
+                                input: adjustedInputTokens,
                                 output: totalOutputTokens,
-                                total: totalInputTokens + totalOutputTokens,
+                                total: adjustedInputTokens +
+                                    totalCacheReadTokens +
+                                    totalOutputTokens,
+                                ...(totalCacheReadTokens > 0
+                                    ? { cacheReadTokens: totalCacheReadTokens }
+                                    : {}),
                             },
                             requestDuration: responseTime,
                             timestamp: new Date().toISOString(),
@@ -831,6 +843,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 let lastStepText = "";
                 let totalInputTokens = 0;
                 let totalOutputTokens = 0;
+                let totalCacheReadTokens = 0;
                 const allToolCalls = [];
                 const toolExecutions = [];
                 let step = 0;
@@ -856,6 +869,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         const chunkResult = await collectStreamChunks(stream);
                         totalInputTokens += chunkResult.inputTokens;
                         totalOutputTokens += chunkResult.outputTokens;
+                        totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                         const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                         // If no function calls, we're done
                         if (chunkResult.stepFunctionCalls.length === 0) {
@@ -927,14 +941,21 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 // analytics / evaluation / tracing stay attached. The native AI
                 // Studio generate path bypasses BaseProvider.generate(), so
                 // skipping enhanceResult would silently drop those features.
+                // Gemini promptTokenCount is OVERLAPPING (already includes
+                // cachedContentTokenCount). Subtract once so the cached portion is
+                // billed at the cheaper cacheRead rate without double-counting.
+                const adjustedInputTokens = Math.max(0, totalInputTokens - totalCacheReadTokens);
                 const baseResult = {
                     content: finalText,
                     provider: this.providerName,
                     model: modelName,
                     usage: {
-                        input: totalInputTokens,
+                        input: adjustedInputTokens,
                         output: totalOutputTokens,
-                        total: totalInputTokens + totalOutputTokens,
+                        total: adjustedInputTokens + totalCacheReadTokens + totalOutputTokens,
+                        ...(totalCacheReadTokens > 0
+                            ? { cacheReadTokens: totalCacheReadTokens }
+                            : {}),
                     },
                     responseTime,
                     toolsUsed: allToolCalls.map((tc) => tc.toolName),