@juspay/neurolink 9.81.3 → 9.83.0

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/proxy/proxyDispatcher.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Install the tuned global undici dispatcher. Idempotent — safe to call once at
+ * proxy startup. No-op when `NEUROLINK_PROXY_KEEPALIVE` is off/false/0.
+ */
+export declare function configureProxyKeepAliveDispatcher(): void;

package/dist/lib/proxy/proxyDispatcher.js

@@ -0,0 +1,61 @@
+/**
+ * Tuned global undici dispatcher for the proxy's upstream forwards.
+ *
+ * The Claude passthrough (`claudeProxyRoutes.ts`) forwards every request to
+ * Anthropic via the global `fetch` → undici global dispatcher. undici keep-alives
+ * by default, but with a ~4s idle timeout: between Claude Code turns (the user
+ * reads output, a tool runs, the model thinks) the idle socket closes, so the
+ * next request opens a brand-new TCP connection. Under sustained use that is a
+ * high rate of short-lived outbound flows.
+ *
+ * On hosts running a socket content-filter (CFIL) — e.g. SentinelOne or
+ * GlobalProtect network extensions — every new flow allocates per-flow kernel
+ * state, so a high flow rate amplifies any leak in that path. Reusing connections
+ * cuts the flow rate sharply, so we install a dispatcher with a longer keep-alive
+ * and a bounded, reused connection pool.
+ *
+ * Everything is overridable via env so it can be tuned (or disabled) per host:
+ *   NEUROLINK_PROXY_KEEPALIVE=off       disable; keep undici defaults
+ *   NEUROLINK_PROXY_KEEPALIVE_MS        idle keep-alive timeout (default 30000)
+ *   NEUROLINK_PROXY_KEEPALIVE_MAX_MS    keep-alive upper bound  (default 600000)
+ *   NEUROLINK_PROXY_MAX_CONNECTIONS     max pooled connections per origin (default 64)
+ */
+import { Agent, setGlobalDispatcher } from "undici";
+import { logger } from "../utils/logger.js";
+function readPositiveInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+let configured = false;
+/**
+ * Install the tuned global undici dispatcher. Idempotent — safe to call once at
+ * proxy startup. No-op when `NEUROLINK_PROXY_KEEPALIVE` is off/false/0.
+ */
+export function configureProxyKeepAliveDispatcher() {
+    if (configured) {
+        return;
+    }
+    configured = true;
+    const toggle = (process.env.NEUROLINK_PROXY_KEEPALIVE ?? "").toLowerCase();
+    if (toggle === "off" || toggle === "false" || toggle === "0") {
+        logger.debug("[proxy] keep-alive dispatcher disabled via env");
+        return;
+    }
+    const keepAliveTimeout = readPositiveInt("NEUROLINK_PROXY_KEEPALIVE_MS", 30_000);
+    const keepAliveMaxTimeout = readPositiveInt("NEUROLINK_PROXY_KEEPALIVE_MAX_MS", 600_000);
+    const connections = readPositiveInt("NEUROLINK_PROXY_MAX_CONNECTIONS", 64);
+    setGlobalDispatcher(new Agent({
+        keepAliveTimeout,
+        keepAliveMaxTimeout,
+        connections,
+        pipelining: 1,
+    }));
+    logger.debug(`[proxy] tuned undici dispatcher installed ` +
+        `(keepAliveTimeout=${keepAliveTimeout}ms, ` +
+        `keepAliveMaxTimeout=${keepAliveMaxTimeout}ms, connections=${connections})`);
+}
+//# sourceMappingURL=proxyDispatcher.js.map

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/systemMessages.d.ts

@@ -0,0 +1,29 @@
+import type { ModelMessage, SystemModelMessage } from "../types/index.js";
+/**
+ * Partition a built message array into system messages and the rest, so the
+ * system prompt can ride `generateText`'s top-level `system` option instead of
+ * the `messages` array.
+ *
+ * The AI SDK deprecates system-role entries inside `messages` (warns by default
+ * from ai@6.0.170 via the `allowSystemInMessages` option, rejected by default
+ * in v7, flagged as a prompt-injection risk). The `system` option accepts full
+ * SystemModelMessage objects, so per-message providerOptions (e.g. the anthropic
+ * cacheControl breakpoint set by buildMessagesArray) survive the move. See
+ * issue #1024.
+ *
+ * Order is preserved within both partitions and the input is not mutated.
+ *
+ * Guard: the partition only runs when it leaves a non-empty `messages` array.
+ * If every message is a system message (a system-only priming call) — or there
+ * are no system messages at all — the original array is returned untouched with
+ * `system: undefined`. The AI SDK rejects an empty `messages` array, and a
+ * system-only call has no hoisted form (the SDK also requires a non-system
+ * message), so that degenerate case is deliberately left on the old
+ * system-in-`messages` path rather than made to throw — it keeps whatever
+ * behaviour it had before #1024. The normal system-plus-conversation path is
+ * always hoisted.
+ */
+export declare function extractSystemMessages(messages: ModelMessage[]): {
+    system: SystemModelMessage[] | undefined;
+    messages: ModelMessage[];
+};

package/dist/lib/utils/systemMessages.js

@@ -0,0 +1,45 @@
+/**
+ * Partition a built message array into system messages and the rest, so the
+ * system prompt can ride `generateText`'s top-level `system` option instead of
+ * the `messages` array.
+ *
+ * The AI SDK deprecates system-role entries inside `messages` (warns by default
+ * from ai@6.0.170 via the `allowSystemInMessages` option, rejected by default
+ * in v7, flagged as a prompt-injection risk). The `system` option accepts full
+ * SystemModelMessage objects, so per-message providerOptions (e.g. the anthropic
+ * cacheControl breakpoint set by buildMessagesArray) survive the move. See
+ * issue #1024.
+ *
+ * Order is preserved within both partitions and the input is not mutated.
+ *
+ * Guard: the partition only runs when it leaves a non-empty `messages` array.
+ * If every message is a system message (a system-only priming call) — or there
+ * are no system messages at all — the original array is returned untouched with
+ * `system: undefined`. The AI SDK rejects an empty `messages` array, and a
+ * system-only call has no hoisted form (the SDK also requires a non-system
+ * message), so that degenerate case is deliberately left on the old
+ * system-in-`messages` path rather than made to throw — it keeps whatever
+ * behaviour it had before #1024. The normal system-plus-conversation path is
+ * always hoisted.
+ */
+export function extractSystemMessages(messages) {
+    const system = [];
+    const rest = [];
+    for (const message of messages) {
+        if (message.role === "system") {
+            system.push(message);
+        }
+        else {
+            rest.push(message);
+        }
+    }
+    // Only hoist when a non-empty messages array remains. A system-only call (or
+    // a no-system array) passes through unchanged: hoisting would empty
+    // `messages`, which the SDK rejects, and a system-only call has no compliant
+    // hoisted form.
+    if (system.length === 0 || rest.length === 0) {
+        return { system: undefined, messages };
+    }
+    return { system, messages: rest };
+}
+//# sourceMappingURL=systemMessages.js.map

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),