@juspay/neurolink 12.25.2 → 12.25.4

package/dist/context/nativeGenerateGuard.d.ts

@@ -1,6 +1,28 @@
 import type { NativeGenerateGuardConfig } from "../types/index.js";
 /** V3-shape adapter for the reclaim policy shared with streaming guards. */
 export declare function createNativeGenerateGuard(config: NativeGenerateGuardConfig): {
+    /**
+     * Record the prompt-token count the vendor reported for the step just
+     * sent.
+     *
+     * Paired with the estimate this guard made for that same step it yields a
+     * calibration ratio — how far the local estimator undercounts what the
+     * vendor actually charges — and that ratio scales the reclaim threshold,
+     * so the guard fires against real token accounting rather than its own.
+     * A non-finite or non-positive figure is ignored, leaving calibration at
+     * 1 rather than skewing it toward a number the vendor never reported.
+     */
     observeUsage(usage: unknown): void;
+    /**
+     * Reclaim context from `conversation` when it has crossed the guard's
+     * threshold, or return `undefined` to send it unchanged.
+     *
+     * The initial task prefix — every message up to and including the first
+     * user turn — is protected as a unit, so leading system messages cannot
+     * displace the task itself from entry zero. Only the entries strictly
+     * between that prefix and the newest `DEFAULT_LOOP_GUARD_PROTECTED_TAIL`
+     * are eligible for truncation or dropping under the shared reclaim
+     * policy; that protected tail — the live working set — is left intact.
+     */
     guardConversation(conversation: Array<Record<string, unknown>>): Array<Record<string, unknown>> | undefined;
 };

package/dist/context/nativeGenerateGuard.js

@@ -52,6 +52,17 @@ export function createNativeGenerateGuard(config) {
     let observedPromptTokens;
     const cost = (message) => estimateTokens(textOf(message), config.provider) + TOKENS_PER_MESSAGE;
     return {
+        /**
+         * Record the prompt-token count the vendor reported for the step just
+         * sent.
+         *
+         * Paired with the estimate this guard made for that same step it yields a
+         * calibration ratio — how far the local estimator undercounts what the
+         * vendor actually charges — and that ratio scales the reclaim threshold,
+         * so the guard fires against real token accounting rather than its own.
+         * A non-finite or non-positive figure is ignored, leaving calibration at
+         * 1 rather than skewing it toward a number the vendor never reported.
+         */
         observeUsage(usage) {
             const input = isRecord(usage) ? usage.inputTokens : undefined;
             const total = isRecord(input) ? input.total : input;
@@ -60,6 +71,17 @@ export function createNativeGenerateGuard(config) {
                     ? total
                     : undefined;
         },
+        /**
+         * Reclaim context from `conversation` when it has crossed the guard's
+         * threshold, or return `undefined` to send it unchanged.
+         *
+         * The initial task prefix — every message up to and including the first
+         * user turn — is protected as a unit, so leading system messages cannot
+         * displace the task itself from entry zero. Only the entries strictly
+         * between that prefix and the newest `DEFAULT_LOOP_GUARD_PROTECTED_TAIL`
+         * are eligible for truncation or dropping under the shared reclaim
+         * policy; that protected tail — the live working set — is left intact.
+         */
         guardConversation(conversation) {
             // Policy entry zero is protected. Fold the entire initial task prefix
             // into it so leading system messages cannot displace task protection.

package/dist/core/modules/ToolsManager.js

@@ -322,17 +322,29 @@ export class ToolsManager {
         for (let pass = 0; pass < MAX_ENVELOPE_TIGHTENING_PASSES; pass++) {
             const allocations = waterFillTextBudget(sizes, textBudget);
             const replacements = new Map();
+            // Record the sizes here, log them only if this pass is the one that
+            // survives. A rejected pass never happened as far as the caller is
+            // concerned, and up to MAX_ENVELOPE_TIGHTENING_PASSES of them can be
+            // rejected on a single call — building their template strings, and the
+            // byteLength each one interpolates, is work paid whether or not debug
+            // logging is even enabled.
+            const truncatedItems = [];
             textIndexes.forEach((index, k) => {
                 const item = content[index];
                 const { preview, truncated, originalSize } = generateToolOutputPreview(item.text, { maxBytes: allocations[k], notice });
                 if (truncated) {
-                    logger.debug(`[ToolsManager] Truncated '${toolName}' MCP content text item ${index}: ${originalSize} bytes → ${Buffer.byteLength(preview, "utf-8")} bytes (envelope budget ${maxBytes})`);
+                    truncatedItems.push({ index, originalSize });
                     replacements.set(index, preview);
                 }
             });
             const candidate = rebuild(replacements);
             const candidateSize = serializedByteLength(candidate);
             if (candidateSize !== undefined && candidateSize <= maxBytes) {
+                if (logger.shouldLog("debug")) {
+                    for (const { index, originalSize } of truncatedItems) {
+                        logger.debug(`[ToolsManager] Truncated '${toolName}' MCP content text item ${index}: ${originalSize} bytes → ${Buffer.byteLength(replacements.get(index) ?? "", "utf-8")} bytes (envelope budget ${maxBytes})`);
+                    }
+                }
                 return candidate;
             }
             if (candidateSize === undefined || replacements.size === 0) {

package/dist/proxy/codexFallback.js

@@ -66,6 +66,8 @@ export class CodexFallbackStreamError extends Error {
                 }),
                 inputTokensObserved: observed.inputTokensObserved,
                 outputTokensObserved: observed.outputTokensObserved,
+                cacheReadTokensObserved: observed.cacheReadTokensObserved,
+                cacheCreationTokensObserved: observed.cacheCreationTokensObserved,
             }
             : usage;
     }
@@ -566,6 +568,8 @@ export function parseCodexFallbackSSE(sse) {
                 }),
                 inputTokensObserved: parsedUsage.inputTokensObserved,
                 outputTokensObserved: parsedUsage.outputTokensObserved,
+                cacheReadTokensObserved: parsedUsage.cacheReadTokensObserved,
+                cacheCreationTokensObserved: parsedUsage.cacheCreationTokensObserved,
             };
         }
         textFromResponse = outputTextFromResponse(payload);
@@ -725,6 +729,8 @@ export async function createCodexFallbackStream(response, model) {
                             }),
                             inputTokensObserved: parsedUsage.inputTokensObserved,
                             outputTokensObserved: parsedUsage.outputTokensObserved,
+                            cacheReadTokensObserved: parsedUsage.cacheReadTokensObserved,
+                            cacheCreationTokensObserved: parsedUsage.cacheCreationTokensObserved,
                         };
                     }
                     const responseBody = payload.response;
@@ -789,10 +795,18 @@ export async function createCodexFallbackStream(response, model) {
                 }, "empty_response", usage);
             }
             const finishReason = toolCalls.size > 0 ? "tool_use" : "end_turn";
+            // A count Codex never reported is omitted rather than sent as 0: this is
+            // what the Claude client reads, and a zero there is indistinguishable
+            // from an observed cache miss. `proxyTokenUsage` floors an absent count
+            // to 0, so the observation flags are the only thing that still knows.
             yield* serializer.finish(usage?.output, finishReason, {
                 input_tokens: usage?.input,
-                cache_read_input_tokens: usage?.cacheReadTokens,
-                cache_creation_input_tokens: usage?.cacheCreationTokens,
+                cache_read_input_tokens: usage?.cacheReadTokensObserved
+                    ? usage.cacheReadTokens
+                    : undefined,
+                cache_creation_input_tokens: usage?.cacheCreationTokensObserved
+                    ? usage.cacheCreationTokens
+                    : undefined,
             });
             return {
                 text: textParts.join(""),

package/dist/proxy/codexUsage.js

@@ -45,6 +45,12 @@ import { sanitizeForLog } from "../utils/logSanitize.js";
 const nonNegativeInt = (value) => typeof value === "number" && Number.isFinite(value) && value > 0
     ? Math.floor(value)
     : 0;
+/**
+ * Whether a count was actually reported, matching what `nonNegativeInt` will
+ * keep. A negative or non-finite value is floored to zero there, so treating
+ * it as observed would record it as a real zero.
+ */
+const observedCount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
 function usefulOutputItem(item) {
     if (!item || typeof item !== "object") {
         return false;
@@ -108,6 +114,8 @@ export function extractCodexUsage(payload) {
         outputTokensObserved: typeof output === "number" && Number.isFinite(output) && output >= 0,
         cacheReadTokens: nonNegativeInt(inputDetails?.cached_tokens),
         cacheCreationTokens: nonNegativeInt(inputDetails?.cache_write_tokens),
+        cacheReadTokensObserved: observedCount(inputDetails?.cached_tokens),
+        cacheCreationTokensObserved: observedCount(inputDetails?.cache_write_tokens),
         reasoningTokens: nonNegativeInt(outputDetails?.reasoning_tokens),
         reasoningTokensObserved: typeof outputDetails?.reasoning_tokens === "number" &&
             Number.isFinite(outputDetails.reasoning_tokens) &&

package/dist/proxy/proxyAnalysis.js

@@ -439,6 +439,10 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
     let recoveredAfterRetry = 0;
     let requestsWithUsage = 0;
     let requestsWithCacheRead = 0;
+    // Turns whose cache breakdown the provider actually reported. A turn that
+    // reported none cannot count as a miss, so it is excluded from the hit-rate
+    // denominator rather than folded in as a zero.
+    let requestsWithCacheObservation = 0;
     let cacheReadTokens = 0;
     let cacheCreationTokens = 0;
     let inputTokens = 0;
@@ -514,7 +518,10 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
             outputTokens += request.outputTokens ?? 0;
             cacheReadTokens += request.cacheReadTokens ?? 0;
             cacheCreationTokens += request.cacheCreationTokens ?? 0;
-            requestsWithCacheRead += (request.cacheReadTokens ?? 0) > 0 ? 1 : 0;
+            if (request.cacheReadTokensObserved !== false) {
+                requestsWithCacheObservation += 1;
+                requestsWithCacheRead += (request.cacheReadTokens ?? 0) > 0 ? 1 : 0;
+            }
             if (request.model) {
                 // Records written before `provider` existed carry only a model name.
                 // "openai-compatible" resolves to the cross-provider table search in
@@ -557,6 +564,7 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
         cache: {
             requestsWithUsage,
             requestsWithCacheRead,
+            requestsWithCacheObservation,
             cacheReadTokens,
             cacheCreationTokens,
             inputTokens,
@@ -567,8 +575,8 @@ function summarizeFinalRequests(finalRequests, terminalStreamErrors, attemptsByR
             modelsPricedByPrefix: [...modelsPricedByPrefix].sort(),
             requestsUnpriced,
             unpricedModels: [...unpricedModels].sort(),
-            requestHitRate: requestsWithUsage > 0
-                ? Number((requestsWithCacheRead / requestsWithUsage).toFixed(4))
+            requestHitRate: requestsWithCacheObservation > 0
+                ? Number((requestsWithCacheRead / requestsWithCacheObservation).toFixed(4))
                 : null,
         },
         finalRequestLatency,
@@ -1080,6 +1088,16 @@ export async function analyzeProxyLogs(options) {
                 outputTokens: finiteNumber(record.outputTokens),
                 cacheReadTokens: finiteNumber(record.cacheReadTokens),
                 cacheCreationTokens: finiteNumber(record.cacheCreationTokens),
+                // Read as a boolean only. An absent flag means observed, which keeps
+                // every record written before the flag existed counting as it did.
+                // The merge below drops undefined from the later record, so a
+                // headers-only first record cannot erase a flag the body record sets.
+                cacheReadTokensObserved: typeof record.cacheReadTokensObserved === "boolean"
+                    ? record.cacheReadTokensObserved
+                    : undefined,
+                cacheCreationTokensObserved: typeof record.cacheCreationTokensObserved === "boolean"
+                    ? record.cacheCreationTokensObserved
+                    : undefined,
                 errorType: stringValue(record.errorType),
                 errorCode: stringValue(record.errorCode),
                 routingDecision,

package/dist/proxy/proxyTracer.js

@@ -385,8 +385,14 @@ class ProxyTracer {
             "ai.tokens.input": billingUsage.input,
             "ai.tokens.output": ctx.outputTokens,
             "ai.tokens.total": totalTokens,
-            "ai.tokens.cache_creation": ctx.cacheCreationTokens,
-            "ai.tokens.cache_read": ctx.cacheReadTokens,
+            // An unreported cache count is left off the span rather than written as
+            // zero, which would read back as an observed cache miss.
+            ...(ctx.cacheCreationTokensObserved === false
+                ? {}
+                : { "ai.tokens.cache_creation": ctx.cacheCreationTokens }),
+            ...(ctx.cacheReadTokensObserved === false
+                ? {}
+                : { "ai.tokens.cache_read": ctx.cacheReadTokens }),
         });
         if (ctx.reasoningTokens !== undefined) {
             this.rootSpan.setAttribute("ai.tokens.reasoning", ctx.reasoningTokens);
@@ -687,8 +693,15 @@ class ProxyTracer {
             };
             m.tokensInput.add(proxyTokenUsage(this.usage).input, tokenLabels);
             m.tokensOutput.add(this.usage.outputTokens, tokenLabels);
-            m.tokensCacheRead.add(this.usage.cacheReadTokens, tokenLabels);
-            m.tokensCacheCreation.add(this.usage.cacheCreationTokens, tokenLabels);
+            // Skipped, not zeroed, when the provider reported no breakdown: a zero
+            // here is read back as an observed cache miss and drags the measured
+            // cache rate down by however many such replies arrive.
+            if (this.usage.cacheReadTokensObserved !== false) {
+                m.tokensCacheRead.add(this.usage.cacheReadTokens, tokenLabels);
+            }
+            if (this.usage.cacheCreationTokensObserved !== false) {
+                m.tokensCacheCreation.add(this.usage.cacheCreationTokens, tokenLabels);
+            }
             if (this.usage.reasoningTokens) {
                 m.tokensReasoning.add(this.usage.reasoningTokens, tokenLabels);
             }

package/dist/proxy/requestLogger.js

@@ -144,6 +144,13 @@ export const __requestLoggerTestHooks = {
     defaultFlushTimeoutMs: REQUEST_LOG_FLUSH_TIMEOUT_MS,
     pendingOperationCount: () => pendingLogOperations.size,
     trackLogOperation,
+    /**
+     * Pricing annotation, exposed because it is otherwise reachable only through
+     * a full log-write cycle. What it refuses to price matters as much as what it
+     * prices: a turn whose cached portion is unknown must not be charged as if
+     * the cache were empty.
+     */
+    annotateRequestPricing,
     setAppendFileForTests: (writer) => {
         appendMetadataFile = writer;
     },
@@ -226,7 +233,14 @@ function annotateRequestPricing(entry) {
         !Number.isFinite(cacheCreation) ||
         cacheCreation < 0 ||
         (entry.inputIncludesCachedTokens === true &&
-            cacheRead + cacheCreation > input)) {
+            cacheRead + cacheCreation > input) ||
+        // When input includes the cached portion but the provider never reported
+        // it, subtracting a defaulted 0 prices the cached tokens at full input
+        // rate and reports zero cache savings. That is a guess, not a price, so
+        // the turn is incomplete rather than silently mispriced.
+        (entry.inputIncludesCachedTokens === true &&
+            (entry.cacheReadTokensObserved === false ||
+                entry.cacheCreationTokensObserved === false))) {
         entry.pricingStatus = "usage_incomplete";
         return;
     }

package/dist/server/routes/claudeProxyRoutes.js

@@ -3909,8 +3909,14 @@ async function executeClaudeCodexFallback(args) {
                 tracer?.setUsage({
                     inputTokens: result.usage.input,
                     outputTokens: result.usage.output,
+                    // `?? 0` alone would record a Codex reply that carried no
+                    // `input_tokens_details` as an observed cache miss. This is the
+                    // leg most fallback traffic actually takes, so it is the one that
+                    // skews the measured Codex cache rate.
                     cacheReadTokens: result.usage.cacheReadTokens ?? 0,
                     cacheCreationTokens: result.usage.cacheCreationTokens ?? 0,
+                    cacheReadTokensObserved: result.usage.cacheReadTokensObserved === true,
+                    cacheCreationTokensObserved: result.usage.cacheCreationTokensObserved === true,
                     reasoningTokens: result.usage.reasoning,
                 }, { recordMetrics: false });
             }
@@ -3951,8 +3957,14 @@ async function executeClaudeCodexFallback(args) {
                 outputTokens: result?.usage?.outputTokensObserved
                     ? result.usage.output
                     : undefined,
-                cacheCreationTokens: result?.usage?.cacheCreationTokens,
-                cacheReadTokens: result?.usage?.cacheReadTokens,
+                cacheCreationTokens: result?.usage?.cacheCreationTokensObserved
+                    ? result.usage.cacheCreationTokens
+                    : undefined,
+                cacheReadTokens: result?.usage?.cacheReadTokensObserved
+                    ? result.usage.cacheReadTokens
+                    : undefined,
+                cacheReadTokensObserved: result?.usage?.cacheReadTokensObserved === true,
+                cacheCreationTokensObserved: result?.usage?.cacheCreationTokensObserved === true,
                 reasoningTokens: result?.usage?.reasoning,
                 errorCode: failure?.code,
                 retryable: failure?.retryable,
@@ -6394,8 +6406,14 @@ function createClaudeRequestRuntimeContext(args) {
                 outputTokens: fallbackFailureUsage.outputTokensObserved
                     ? fallbackFailureUsage.output
                     : undefined,
-                cacheReadTokens: fallbackFailureUsage.cacheReadTokens,
-                cacheCreationTokens: fallbackFailureUsage.cacheCreationTokens,
+                cacheReadTokens: fallbackFailureUsage.cacheReadTokensObserved
+                    ? fallbackFailureUsage.cacheReadTokens
+                    : undefined,
+                cacheCreationTokens: fallbackFailureUsage.cacheCreationTokensObserved
+                    ? fallbackFailureUsage.cacheCreationTokens
+                    : undefined,
+                cacheReadTokensObserved: fallbackFailureUsage.cacheReadTokensObserved === true,
+                cacheCreationTokensObserved: fallbackFailureUsage.cacheCreationTokensObserved === true,
                 reasoningTokens: fallbackFailureUsage.reasoning,
                 ...extra,
             };
@@ -6420,6 +6438,8 @@ function createClaudeRequestRuntimeContext(args) {
                     outputTokens: fallbackFailureUsage.output,
                     cacheReadTokens: fallbackFailureUsage.cacheReadTokens ?? 0,
                     cacheCreationTokens: fallbackFailureUsage.cacheCreationTokens ?? 0,
+                    cacheReadTokensObserved: fallbackFailureUsage.cacheReadTokensObserved === true,
+                    cacheCreationTokensObserved: fallbackFailureUsage.cacheCreationTokensObserved === true,
                     reasoningTokens: fallbackFailureUsage.reasoning,
                 }, { recordMetrics: false });
             }

package/dist/server/routes/codexProxyRoutes.js

@@ -440,6 +440,15 @@ function captureCodexResponse(ctx, response, phase, account, attempt) {
         headers: response.headers,
     });
 }
+/**
+ * Serve one native `/backend-api/codex/responses` turn.
+ *
+ * Owns the whole hop: account selection and rotation, the upstream request,
+ * the SSE relay back to the caller, and the terminal accounting that turns the
+ * observed wire usage into request-log and tracer records. Usage counts the
+ * provider did not report are carried as unobserved rather than zero, so a
+ * silent cache breakdown is never recorded as a cache miss.
+ */
 async function executeCodexResponsesRequest(ctx) {
     const requestStartTime = Date.now();
     let body = (ctx.body ?? {});
@@ -889,8 +898,12 @@ async function executeCodexResponsesRequest(ctx) {
                                         outputTokens: usage.outputTokensObserved
                                             ? usage.outputTokens
                                             : undefined,
-                                        cacheReadTokens: usage.cacheReadTokens,
-                                        cacheCreationTokens: usage.cacheCreationTokens,
+                                        cacheReadTokens: usage.cacheReadTokensObserved
+                                            ? usage.cacheReadTokens
+                                            : undefined,
+                                        cacheCreationTokens: usage.cacheCreationTokensObserved
+                                            ? usage.cacheCreationTokens
+                                            : undefined,
                                         reasoningTokens: usage.reasoningTokensObserved
                                             ? usage.reasoningTokens
                                             : undefined,
@@ -904,6 +917,8 @@ async function executeCodexResponsesRequest(ctx) {
                                             reasoningTokens: usage.reasoningTokensObserved
                                                 ? usage.reasoningTokens
                                                 : undefined,
+                                            cacheReadTokensObserved: usage.cacheReadTokensObserved === true,
+                                            cacheCreationTokensObserved: usage.cacheCreationTokensObserved === true,
                                             inputIncludesCachedTokens: true,
                                         });
                                     }

package/dist/types/codex.d.ts

@@ -184,6 +184,8 @@ export type CodexFallbackResult = {
         /** Numeric serializer compatibility must not imply provider observation. */
         inputTokensObserved?: boolean;
         outputTokensObserved?: boolean;
+        cacheReadTokensObserved?: boolean;
+        cacheCreationTokensObserved?: boolean;
     };
     finishReason: "end_turn" | "tool_use";
 };

package/dist/types/generate.d.ts

@@ -1685,7 +1685,13 @@ export type NativeGenerateLoopArgs = {
 };
 export type NativeGenerateLoopResult = {
     text: string;
-    /** Joined reasoning content parts from the final step, when the vendor sent any. */
+    /**
+     * Joined reasoning content parts from EVERY step, when the vendor sent any.
+     *
+     * Was final-step-only until the native generate loop began accumulating
+     * across steps; a multi-step turn would otherwise report only the reasoning
+     * that happened after its last tool call.
+     */
     reasoning?: string;
     finishReason: string;
     rawFinishReason?: string;

package/dist/types/proxy.d.ts

@@ -676,6 +676,15 @@ export type RequestLogEntry = {
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    /**
+     * Whether the provider reported each cache count. Omitted means observed,
+     * so every path that genuinely reports a breakdown is unchanged. When
+     * false the count is absent rather than zero, and the reporting and
+     * pricing paths must not read it as a cache miss: a zero folded into a
+     * hit-rate denominator biases every rate built on these records down.
+     */
+    cacheReadTokensObserved?: boolean;
+    cacheCreationTokensObserved?: boolean;
     /** Reasoning tokens are a subset of output, never additional usage. */
     reasoningTokens?: number;
     /**
@@ -1032,6 +1041,9 @@ export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, ac
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    /** False when the provider reported no cache breakdown; see RequestLogEntry. */
+    cacheReadTokensObserved?: boolean;
+    cacheCreationTokensObserved?: boolean;
     reasoningTokens?: number;
     errorCode?: string;
     retryable?: boolean;
@@ -1899,6 +1911,15 @@ export type UsageContext = {
     outputTokens: number;
     cacheCreationTokens: number;
     cacheReadTokens: number;
+    /**
+     * Whether the provider actually reported each cache count. Omitted means
+     * observed, so every path that genuinely reports a breakdown is unchanged.
+     * When false the count is not recorded at all, because a zero written into
+     * `proxy_tokens_cache_read` is indistinguishable from a real cache miss and
+     * biases every rate built on that counter downward.
+     */
+    cacheReadTokensObserved?: boolean;
+    cacheCreationTokensObserved?: boolean;
     reasoningTokens?: number;
     rateLimitAfter5h?: number;
     rateLimitAfter7d?: number;
@@ -2223,6 +2244,12 @@ export type ProxyAnalysisReport = {
     cache: {
         requestsWithUsage: number;
         requestsWithCacheRead: number;
+        /**
+         * Turns whose cache breakdown the provider actually reported, and the
+         * denominator of `requestHitRate`. A turn that reported none is not a
+         * miss, so counting it would bias the rate down.
+         */
+        requestsWithCacheObservation: number;
         cacheReadTokens: number;
         cacheCreationTokens: number;
         /** Ordinary input, excluding the separately reported cache read/write buckets. */
@@ -2294,6 +2321,13 @@ export type ProxyAnalysisFinalRequestRecord = {
     outputTokens: number | null;
     cacheReadTokens: number | null;
     cacheCreationTokens: number | null;
+    /**
+     * False when the provider reported no cache breakdown. Such a turn is not a
+     * cache miss, so it is excluded from the hit-rate denominator rather than
+     * counted as a zero.
+     */
+    cacheReadTokensObserved?: boolean;
+    cacheCreationTokensObserved?: boolean;
     errorType: string | null;
     errorCode: string | null;
     routingDecision: ProxyAccountRoutingDecision | null;
@@ -2328,6 +2362,22 @@ export type CodexStreamUsage = {
     cacheReadTokens: number;
     /** Cache writes, which bill at a premium over both reads and plain input. */
     cacheCreationTokens: number;
+    /**
+     * Whether the provider supplied each cache count, tracked per field.
+     *
+     * Without this a reply that omits `input_tokens_details` is recorded as a
+     * total cache miss rather than as unknown, which biases every measured cache
+     * rate downward. Input, output and reasoning already carry this distinction.
+     *
+     * The two fields are tracked separately because a reply can carry one and
+     * not the other: a single flag covering both would let a missing
+     * `cache_write_tokens` ride in on an observed `cached_tokens` and be
+     * recorded as a real zero. A count that is present but not a finite,
+     * non-negative number is not observed either — `nonNegativeInt` floors it to
+     * zero, which is indistinguishable from a genuine zero once recorded.
+     */
+    cacheReadTokensObserved?: boolean;
+    cacheCreationTokensObserved?: boolean;
     reasoningTokens: number;
     /** Whether the provider supplied a valid reasoning breakdown. */
     reasoningTokensObserved?: boolean;

package/dist/utils/messageBuilder.js

@@ -1374,7 +1374,8 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // ordinary "transcribe this recording" request — took the text-only branch
     // below, where the collected bytes have nowhere to go and only the metadata
     // summary survives.
-    const hasNativeAudio = (inp.nativeAudioFiles?.length ?? 0) > 0 && supportsNativeAudio(provider);
+    const hasNativeAudio = (inp.nativeAudioFiles?.length ?? 0) > 0 &&
+        supportsNativeAudio(provider, model);
     // If no images, PDFs or audio, use standard message building and convert to MultimodalChatMessage[]
     if (!hasImages && !hasPDFs && !hasNativeAudio) {
         // #289: CSV content[] items don't need vision, so they never reach the
@@ -1574,7 +1575,7 @@ async function appendCsvContentToText(csvItems, baseText) {
 /**
  * Convert advanced content format to provider-specific format
  */
-async function convertContentToProviderFormat(content, provider, _model, pdfOptions, audioFiles = [], outputFormat) {
+async function convertContentToProviderFormat(content, provider, model, pdfOptions, audioFiles = [], outputFormat) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
     const pdfContent = content.filter((c) => c.type === "pdf");
@@ -1596,7 +1597,7 @@ async function convertContentToProviderFormat(content, provider, _model, pdfOpti
     // change exists to stop, reached through a different branch. Gated on the
     // provider accepting audio so one that cannot keeps the cheaper plain-text
     // shape rather than an array carrying a part it will ignore.
-    const deliversAudio = audioFiles.length > 0 && supportsNativeAudio(provider);
+    const deliversAudio = audioFiles.length > 0 && supportsNativeAudio(provider, model);
     const hasMultimodal = imageContent.length > 0 || pdfContent.length > 0 || deliversAudio;
     // Validate that we have at least some content
     if (!hasMultimodal && !text) {
@@ -1627,7 +1628,7 @@ async function convertContentToProviderFormat(content, provider, _model, pdfOpti
     await enforceAggregatePdfLimits(pdfFiles, provider, {
         trustSuppliedPageCounts: false,
     });
-    return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model, {
+    return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, model, {
         audioFiles,
         outputFormat,
     });
@@ -2225,7 +2226,7 @@ mediaOptions = {}) {
     // itself rather than replacing the description — a model asked "how long is
     // this?" keeps the exact answer, and one asked "what is said?" can now
     // answer at all.
-    if (audioFiles.length > 0 && supportsNativeAudio(provider)) {
+    if (audioFiles.length > 0 && supportsNativeAudio(provider, model)) {
         for (const audio of audioFiles) {
             // Derived from the trimmed basename so a directory containing a dot
             // (`/srv/v1.2/recording`) cannot be mistaken for the file's extension.