@juspay/neurolink 11.12.0 → 11.13.0

package/dist/lib/proxy/proxyTranslationEngine.js

@@ -249,6 +249,8 @@ export async function handleTranslatedStreamRequest(args) {
     let succeeded = false;
     let streamInterruptedAfterOutput = false;
     let translatedModel;
+    /** Provider that actually served the successful attempt, for costing. */
+    let translatedProvider;
     let finalStreamError = "No translation providers succeeded";
     let upstreamIterator;
     let lastAttemptLabel = "translation";
@@ -328,6 +330,19 @@ export async function handleTranslatedStreamRequest(args) {
                                 controller.enqueue(encoder.encode(frame));
                             }
                         }
+                        translatedModel = streamResult.model;
+                        translatedProvider = attempt.provider;
+                        // Substitution BEFORE usage: setUsage() and recordMetrics() price
+                        // the request immediately, against the tracer's current model and
+                        // billing provider. Recording first and substituting afterwards
+                        // bills the model the client ASKED for — which is exactly what
+                        // ProxyTracer.setModelSubstitution() documents as wrong, since a
+                        // claude-* alias served by another provider would be charged at
+                        // Claude rates. The finally block below still calls it, harmlessly,
+                        // for paths that never reach here.
+                        if (tracer && translatedModel && translatedModel !== requestModel) {
+                            tracer.setModelSubstitution(requestModel, translatedModel, translatedProvider);
+                        }
                         // Track usage and metrics
                         const resolvedUsageForTracer = extractUsageFromStreamResult(streamResult.usage);
                         tracer?.setUsage({
@@ -337,7 +352,6 @@ export async function handleTranslatedStreamRequest(args) {
                             cacheReadTokens: 0,
                         });
                         tracer?.recordMetrics();
-                        translatedModel = streamResult.model;
                         succeeded = true;
                         return;
                     }
@@ -378,7 +392,7 @@ export async function handleTranslatedStreamRequest(args) {
                     controller.close();
                 }
                 if (tracer && translatedModel && translatedModel !== requestModel) {
-                    tracer.setModelSubstitution(requestModel, translatedModel);
+                    tracer.setModelSubstitution(requestModel, translatedModel, translatedProvider);
                 }
                 const terminalStatus = cancelled
                     ? 499
@@ -499,6 +513,12 @@ export async function handleTranslatedJsonRequest(args) {
                     : undefined,
                 toolCalls: streamResult.toolCalls,
             };
+            // Substitution BEFORE usage — see the streaming path for why: pricing
+            // happens inside setUsage()/recordMetrics(), so substituting afterwards
+            // bills the requested model instead of the one that served.
+            if (tracer && streamResult.model && streamResult.model !== requestModel) {
+                tracer.setModelSubstitution(requestModel, streamResult.model, attempt.provider);
+            }
             // Track usage and metrics
             const resolvedUsage = extractUsageFromStreamResult(streamResult.usage);
             tracer?.setUsage({
@@ -508,9 +528,6 @@ export async function handleTranslatedJsonRequest(args) {
                 cacheReadTokens: 0,
             });
             tracer?.recordMetrics();
-            if (tracer && streamResult.model && streamResult.model !== requestModel) {
-                tracer.setModelSubstitution(requestModel, streamResult.model);
-            }
             tracer?.end(200, Date.now() - requestStartTime);
             recordFinalSuccess(lastAttemptLabel, "translation");
             const traceCtx = tracer?.getTraceContext();

package/dist/lib/server/routes/codexProxyRoutes.js

@@ -21,6 +21,7 @@ import { tokenStore } from "../../auth/tokenStore.js";
 import { CODEX_ORIGINATOR, CODEX_RESPONSES_URL, CODEX_USER_AGENT, codexTokenNeedsRefresh, isPermanentCodexRefreshFailure, refreshCodexToken, resolveCodexAccountId, } from "../../auth/codexOAuth.js";
 import { clearAccountCooldown, loadAccountCooldowns, saveAccountCooldown, } from "../../proxy/accountCooldown.js";
 import { loadAccountQuotas, saveAccountQuota, } from "../../proxy/accountQuota.js";
+import { createCodexUsageTap } from "../../proxy/codexUsage.js";
 import { CODEX_ACCOUNT_PREFIX, parseCodexRateLimitHeaders, } from "../../proxy/codexAccountUsage.js";
 import { logRequest } from "../../proxy/requestLogger.js";
 import { parseRetryAfterMs } from "../../proxy/routingPolicy.js";
@@ -340,7 +341,34 @@ async function handleCodexResponsesRequest(ctx) {
                     connection: "keep-alive",
                     ...(ctx.responseHeaders ?? {}),
                 };
-                return new Response(upstream.body, {
+                // Tap the relay for token usage. The log above is written first and
+                // unconditionally so a request is never lost when a client hangs up
+                // mid-stream; this emits a second record for the same requestId
+                // carrying the counts, which proxyAnalysis merges. If the stream shape
+                // is not recognised, usage resolves null and nothing extra is written —
+                // i.e. exactly the previous behaviour.
+                if (!upstream.body) {
+                    return new Response(upstream.body, {
+                        status: upstream.status,
+                        headers,
+                    });
+                }
+                const { stream: usageTap, usage: usageSeen } = createCodexUsageTap();
+                usageSeen
+                    .then((usage) => {
+                    if (!usage) {
+                        return;
+                    }
+                    return writeLog(account.label, upstream.status, {
+                        provider: "openai",
+                        inputTokens: usage.inputTokens,
+                        outputTokens: usage.outputTokens,
+                        cacheReadTokens: usage.cacheReadTokens,
+                        cacheCreationTokens: usage.cacheCreationTokens,
+                    });
+                })
+                    .catch(() => undefined);
+                return new Response(upstream.body.pipeThrough(usageTap), {
                     status: upstream.status,
                     headers,
                 });

package/dist/lib/server/routes/openaiProxyRoutes.js

@@ -335,6 +335,11 @@ export function createOpenAIProxyRoutes(modelRouter, basePath = "", loopbackPort
                             toolCount: Object.keys(parsed.tools).length,
                             clientApp: "openai-compat",
                             userAgent: ctx.headers["user-agent"] ?? "",
+                            // Without this the tracer defaults to "anthropic" and every
+                            // non-Anthropic model prices to $0 (the anthropic table has no
+                            // _default), while a claude-* alias routed elsewhere prices at
+                            // Claude rates. Both are wrong in opposite directions.
+                            provider: targetProvider ?? "openai-compatible",
                         }, ctx.headers);
                         tracer.setMode("full");
                     }

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

@@ -570,6 +570,12 @@ export type RequestLogEntry = {
     outputTokens?: number;
     cacheCreationTokens?: number;
     cacheReadTokens?: number;
+    /**
+     * Provider that actually served the request, for costing. Absent on records
+     * written before this field existed; `proxyAnalysis` then falls back to a
+     * cross-provider model lookup rather than assuming Anthropic.
+     */
+    provider?: string;
     /** OTel trace ID for correlation with distributed traces */
     traceId?: string;
     /** OTel span ID for correlation with distributed traces */
@@ -1384,6 +1390,13 @@ export type ProxyRequestContext = {
     sessionId?: string;
     userAgent?: string;
     clientApp?: string;
+    /**
+     * Provider that will serve the request, used for costing. Defaults to
+     * "anthropic" when omitted, which is correct for the /v1/messages engine;
+     * the OpenAI-compatible engine must pass whatever ModelRouter resolved, or
+     * every non-Anthropic model prices to $0.
+     */
+    provider?: string;
 };
 /** Response-side details parsed from the upstream reply (model, finish, tools). */
 export type ResponseInfoContext = {
@@ -1662,7 +1675,27 @@ export type ProxyAnalysisReport = {
         cacheReadTokens: number;
         cacheCreationTokens: number;
         inputTokens: number;
+        outputTokens: number;
         requestHitRate: number | null;
+        /**
+         * Summed per-request cost in USD. Records that carry no model, or whose
+         * model matches no pricing table, contribute 0 — so this is a floor, not
+         * an exact bill. `requestsPriced` says how many records actually priced.
+         */
+        estimatedCostUsd: number;
+        requestsPriced: number;
+        /**
+         * Requests whose cost came from a longest-prefix fallback rather than an
+         * exact pricing row — the rate is inherited from a similarly-named model
+         * and may be wrong. Adding the real row makes these exact.
+         */
+        requestsPricedByPrefix: number;
+        /** Distinct models priced by prefix fallback, for the operator to chase. */
+        modelsPricedByPrefix: string[];
+        /** Requests carrying usage whose model matched no pricing row at all. */
+        requestsUnpriced: number;
+        /** Distinct models with no pricing row at all. */
+        unpricedModels: string[];
     };
     routing: {
         modes: Record<string, number>;
@@ -1698,13 +1731,45 @@ export type ProxyAnalysisFinalRequestRecord = {
     durationMs: number | null;
     account: string;
     accountType: string;
+    model: string | null;
+    provider: string | null;
     inputTokens: number | null;
+    outputTokens: number | null;
     cacheReadTokens: number | null;
     cacheCreationTokens: number | null;
     errorType: string | null;
     errorCode: string | null;
     routingDecision: ProxyAccountRoutingDecision | null;
 };
+/**
+ * A stream transformer that also handles cancellation.
+ *
+ * The Streams standard gives `Transformer` a `cancel()` callback — invoked when
+ * the stream is aborted rather than closed cleanly — and Node implements it,
+ * but TypeScript's bundled lib does not declare it yet. Without it there is no
+ * way to observe a client hanging up mid-response.
+ */
+export type ProxyCancellableTransformer<I, O> = Transformer<I, O> & {
+    cancel?: (reason?: unknown) => void;
+};
+/**
+ * Token usage scraped from a Codex (OpenAI Responses) SSE stream.
+ *
+ * Verified against real traffic: captured from a live `codex exec` run through
+ * the proxy on 2026-08-21 (`test/fixtures/codex-response-usage.sse`). The
+ * shape is `response.completed` → `response.usage`, carrying `input_tokens`,
+ * `output_tokens`, and an `input_tokens_details` object with `cached_tokens`
+ * and `cache_write_tokens`. The parser also accepts the common variants. Treat
+ * a null result as "not observed", never as "zero tokens".
+ */
+export type CodexStreamUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    /** Cache writes, which bill at a premium over both reads and plain input. */
+    cacheCreationTokens: number;
+    reasoningTokens: number;
+};
 /** Validated account-routing evidence joined to a final request log. */
 export type ProxyAnalysisRoutingRecord = {
     requestId: string;

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

@@ -14,4 +14,13 @@ export declare function calculateCost(provider: string, model: string, usage: To
  * USD price, and any caller gated by `hasPricing()` should treat them as
  * non-billable rather than zero-cost-billable.
  */
+/**
+ * Whether a model's rates came from an exact table entry or were inferred.
+ *
+ * `findRates` falls back to a longest-prefix match, so an unlisted model can
+ * silently inherit a listed one's rates — e.g. "gpt-5.6-sol" matches the
+ * "gpt-5" entry and is billed at its price. That is a guess, not a quote, and
+ * a caller reporting spend needs to be able to say which it had.
+ */
+export declare function isExactPricingMatch(provider: string, model: string): boolean;
 export declare function hasPricing(provider: string, model: string): boolean;

package/dist/lib/utils/pricing.js

@@ -11,6 +11,47 @@
 const PRICING = {
     // Anthropic (direct API) — updated March 2026
     anthropic: {
+        // Claude 5 family. Rates from platform.claude.com/docs/en/about-claude/pricing
+        // (checked 2026-08-21). Cache multipliers are the documented ones: a 5-minute
+        // cache write is 1.25x base input, a cache hit 0.1x.
+        "claude-fable-5": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 1.0 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-mythos-5": {
+            input: 10.0 / 1_000_000,
+            output: 50.0 / 1_000_000,
+            cacheRead: 1.0 / 1_000_000,
+            cacheCreation: 12.5 / 1_000_000,
+        },
+        "claude-opus-5": {
+            input: 5.0 / 1_000_000,
+            output: 25.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+            cacheCreation: 6.25 / 1_000_000,
+        },
+        "claude-opus-4-8": {
+            input: 5.0 / 1_000_000,
+            output: 25.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+            cacheCreation: 6.25 / 1_000_000,
+        },
+        "claude-opus-4-7": {
+            input: 5.0 / 1_000_000,
+            output: 25.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+            cacheCreation: 6.25 / 1_000_000,
+        },
+        // Sonnet 5's $2/$10 launch pricing became the standard price; the
+        // previously scheduled 2026-09-01 rise to $3/$15 was cancelled.
+        "claude-sonnet-5": {
+            input: 2.0 / 1_000_000,
+            output: 10.0 / 1_000_000,
+            cacheRead: 0.2 / 1_000_000,
+            cacheCreation: 2.5 / 1_000_000,
+        },
         // Claude 4.6 family
         "claude-opus-4-6": {
             input: 5.0 / 1_000_000,
@@ -31,6 +72,17 @@ const PRICING = {
             cacheRead: 0.3 / 1_000_000,
             cacheCreation: 3.75 / 1_000_000,
         },
+        // Undated aliases for the same models. Clients report the bare name far
+        // more often than the dated one, and without these the longest-prefix
+        // match lands on the previous generation ("claude-sonnet-4"), which both
+        // reports as an inferred rate and would silently drift if the two
+        // generations ever diverge in price.
+        "claude-sonnet-4-5": {
+            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-opus-4-5": {
             input: 5.0 / 1_000_000,
             output: 25.0 / 1_000_000,
@@ -43,6 +95,12 @@ const PRICING = {
             cacheRead: 0.1 / 1_000_000,
             cacheCreation: 1.25 / 1_000_000,
         },
+        "claude-haiku-4-5": {
+            input: 1.0 / 1_000_000,
+            output: 5.0 / 1_000_000,
+            cacheRead: 0.1 / 1_000_000,
+            cacheCreation: 1.25 / 1_000_000,
+        },
         // Claude 4.0/4.1 family
         "claude-opus-4-1": {
             input: 15.0 / 1_000_000,
@@ -147,6 +205,35 @@ const PRICING = {
     },
     // OpenAI — updated March 2026
     openai: {
+        // GPT-5.6 family (Sol/Terra/Luna). Rates reflect OpenAI's 2026-07-30 cut,
+        // which reduced Luna by 80% and Terra by 20%; Sol was unchanged. Many
+        // third-party tables still carry the pre-cut numbers.
+        // List rates. Note that some resellers advertise sol at 50% off
+        // ($2.50/$15.00/$0.25); those are promotional and expire, so the table
+        // carries list price and cache read stays the documented 0.1x of input.
+        "gpt-5.6-sol": {
+            input: 5.0 / 1_000_000,
+            output: 30.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+            cacheCreation: 6.25 / 1_000_000,
+        },
+        "gpt-5.6-terra": {
+            input: 2.0 / 1_000_000,
+            output: 12.0 / 1_000_000,
+            cacheRead: 0.2 / 1_000_000,
+            cacheCreation: 2.5 / 1_000_000,
+        },
+        "gpt-5.6-luna": {
+            input: 0.2 / 1_000_000,
+            output: 1.2 / 1_000_000,
+            cacheRead: 0.02 / 1_000_000,
+            cacheCreation: 0.25 / 1_000_000,
+        },
+        "gpt-5.5": {
+            input: 5.0 / 1_000_000,
+            output: 30.0 / 1_000_000,
+            cacheRead: 0.5 / 1_000_000,
+        },
         // GPT-5.x family
         // cacheRead = 0.25x input (cached input tokens; no separate cacheCreation).
         "gpt-5.4": {
@@ -625,7 +712,30 @@ const PROVIDER_ALIASES = {
  *
  * @returns The rate entry, or undefined when the combination is unknown.
  */
-function findRates(provider, model) {
+/**
+ * Whether the tail left over after a longest-prefix match is only a version or
+ * date stamp — e.g. "claude-sonnet-4-5-20250929-v1:0" against the table key
+ * "claude-sonnet-4-5". That is the *same* model carrying a release suffix, so
+ * its rate is quoted, not inferred.
+ *
+ * Deliberately narrow: "gpt-5.6-sol" against "gpt-5" leaves ".6-sol", which is
+ * a different model generation and stays flagged as inferred.
+ */
+const VERSION_SUFFIX_RE = /^[-@](\d{8}|v\d+(:\d+)?|latest)([-@:](\d{8}|v\d+(:\d+)?))*$/;
+function isVersionOnlySuffix(model, key) {
+    if (!model.startsWith(key) || model === key) {
+        return false;
+    }
+    return VERSION_SUFFIX_RE.test(model.slice(key.length));
+}
+function findRates(provider, model, 
+/**
+ * Set to true when the rates came from a literal table key rather than a
+ * prefix/fallback match. Threaded as an out-param so there is exactly one
+ * lookup implementation — a second hand-written copy drifted from this one
+ * and mislabelled every Bedrock and Vertex-Gemini hit.
+ */
+matchKind) {
     const stripped = provider.toLowerCase().replace(/[^a-z]/g, "");
     const normalizedProvider = PROVIDER_ALIASES[stripped] ?? stripped;
     // Proxy providers (LiteLLM, OpenRouter): search all known providers for a model match
@@ -633,6 +743,9 @@ function findRates(provider, model) {
         for (const providerPricing of Object.values(PRICING)) {
             // Exact match
             if (providerPricing[model]) {
+                if (matchKind) {
+                    matchKind.exact = true;
+                }
                 return providerPricing[model];
             }
             const sortedKeys = Object.keys(providerPricing).sort((a, b) => b.length - a.length);
@@ -667,6 +780,9 @@ function findRates(provider, model) {
         : model;
     // Exact match
     if (providerPricing[modelKey]) {
+        if (matchKind) {
+            matchKind.exact = true;
+        }
         return providerPricing[modelKey];
     }
     // Longest-prefix match (skip the synthetic "_default" sentinel below)
@@ -675,6 +791,9 @@ function findRates(provider, model) {
         .sort((a, b) => b.length - a.length);
     const key = sortedKeys.find((k) => modelKey.startsWith(k));
     if (key) {
+        if (matchKind && isVersionOnlySuffix(modelKey, key)) {
+            matchKind.exact = true;
+        }
         return providerPricing[key];
     }
     // Fallback: Vertex hosts both Claude and Gemini models.
@@ -686,6 +805,9 @@ function findRates(provider, model) {
         const googlePricing = PRICING["google"];
         if (googlePricing) {
             if (googlePricing[model]) {
+                if (matchKind) {
+                    matchKind.exact = true;
+                }
                 return googlePricing[model];
             }
             const googleKeys = Object.keys(googlePricing).sort((a, b) => b.length - a.length);
@@ -742,6 +864,19 @@ export function calculateCost(provider, model, usage) {
  * USD price, and any caller gated by `hasPricing()` should treat them as
  * non-billable rather than zero-cost-billable.
  */
+/**
+ * Whether a model's rates came from an exact table entry or were inferred.
+ *
+ * `findRates` falls back to a longest-prefix match, so an unlisted model can
+ * silently inherit a listed one's rates — e.g. "gpt-5.6-sol" matches the
+ * "gpt-5" entry and is billed at its price. That is a guess, not a quote, and
+ * a caller reporting spend needs to be able to say which it had.
+ */
+export function isExactPricingMatch(provider, model) {
+    const matchKind = { exact: false };
+    const rates = findRates(provider, model, matchKind);
+    return rates !== undefined && matchKind.exact;
+}
 export function hasPricing(provider, model) {
     const rates = findRates(provider, model);
     if (!rates) {

package/dist/providers/googleAiStudio/client.js

@@ -20,7 +20,7 @@ import { resolveToolExecutionRecords } from "../../core/toolExecutionRecorder.js
 import { buildGeminiResponseSchema, buildNativeConfig, computeMaxSteps, createContextGuard, buildUserPartsWithMultimodal, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, } from "../googleNativeGemini3/index.js";
 import { createStreamChannel } from "../../core/streamChannel.js";
 import { toNativeToolDeclarations } from "../../core/nativeToolFormat.js";
-import { createProxyFetch } from "../../proxy/proxyFetch.js";
+import { warnGoogleSdkIgnoresProxy } from "../../proxy/proxyFetch.js";
 // Google AI Live API types now imported from ../types/providerSpecific.js
 // Import proper types for multimodal message handling
 // Create Google GenAI client
@@ -38,16 +38,19 @@ async function createGoogleGenAIClient(apiKey, baseURL) {
         });
     }
     const Ctor = ctor;
-    // Include httpOptions with proxy fetch for corporate network support.
+    // httpOptions carries the endpoint override and nothing else. It used to
+    // also pass a proxy fetch, which the SDK silently ignored — see
+    // warnGoogleSdkIgnoresProxy for why that is not fixable here.
+    //
     // baseUrl is only included when resolved — verified against
     // @google/genai's ApiClient (dist/node/index.cjs) that it falls back to
     // its own default whenever httpOptions.baseUrl is undefined, so omitting
     // the key and passing `baseUrl: undefined` behave identically; the key is
     // still omitted outright for a cleaner outbound config object.
+    warnGoogleSdkIgnoresProxy("GoogleAIStudio");
     return new Ctor({
         apiKey,
         httpOptions: {
-            fetch: createProxyFetch(),
             ...(baseURL ? { baseUrl: baseURL } : {}),
         },
     });

package/dist/providers/googleVertex/client.js

@@ -11,7 +11,7 @@ import { DEFAULT_GEMINI_STREAM_TIMEOUT_MS, DEFAULT_MAX_STEPS, DEFAULT_TOOL_EXECU
 import { ModelConfigurationManager } from "../../core/modelConfiguration.js";
 import { isSchemaComplexityError } from "../../core/modules/structuredOutputPolicy.js";
 import { redactUrlForError, stringifyContentSafe, } from "../../utils/logSanitize.js";
-import { createProxyFetch } from "../../proxy/proxyFetch.js";
+import { warnGoogleSdkIgnoresProxy } from "../../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { classifyProviderError } from "../../utils/errorClassifier.js";
 import { ERROR_CODES, NeuroLinkError } from "../../utils/errorHandling.js";
@@ -843,6 +843,7 @@ export class GoogleVertexProvider extends BaseProvider {
      * Create @google/genai client configured for Vertex AI
      */
     async createVertexGenAIClient(regionOverride) {
+        warnGoogleSdkIgnoresProxy("GoogleVertex");
         const expressApiKey = this.resolveExpressApiKey();
         // Resolved only on the ADC path: getVertexProjectId() throws when no
         // project is configured, which an Express request legitimately has none of.
@@ -863,8 +864,10 @@ export class GoogleVertexProvider extends BaseProvider {
         const Ctor = ctor;
         const baseUrl = this.resolveBaseURL();
         const httpOptions = {
-            // Proxy fetch for corporate network support.
-            fetch: createProxyFetch(),
+            // The endpoint override and nothing else. This object used to also pass
+            // a proxy fetch, which the SDK silently ignored — see
+            // warnGoogleSdkIgnoresProxy for why that is not fixable here.
+            //
             // Only set when resolved: the SDK falls back to its own default
             // whenever httpOptions.baseUrl is undefined, so omitting the key and
             // passing undefined behave identically.

package/dist/proxy/codexUsage.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Codex (OpenAI Responses) SSE usage tap.
+ *
+ * The Codex proxy engine relays `upstream.body` to the client untouched and
+ * logs before a single byte is read, so no Codex request has ever carried token
+ * counts. This module adds a pass-through tap that scrapes `usage` out of the
+ * stream without holding back or altering any bytes.
+ *
+ * ## Safety contract
+ *
+ * This sits in the hot path of a live proxy, so it is built to be incapable of
+ * breaking a stream:
+ *
+ * - every chunk is enqueued **before** it is inspected;
+ * - all parsing runs inside try/catch, and a throw is swallowed;
+ * - a stream whose shape is unrecognised resolves `usage` to `null`, which is
+ *   exactly today's behaviour (a log with no token fields).
+ *
+ * The worst case is therefore "no tokens recorded", never a truncated or
+ * corrupted response.
+ *
+ * ## Wire shape
+ *
+ * **Verified against real traffic.** Captured from a live `codex exec` run
+ * through the proxy on 2026-08-21; the trimmed sample is at
+ * `test/fixtures/codex-response-usage.sse` and is asserted against in the
+ * codex suite. The real shape is
+ *
+ *   event: response.completed
+ *   data: {"type":"response.completed","response":{"usage":{
+ *     "input_tokens":N,"output_tokens":M,
+ *     "input_tokens_details":{"cached_tokens":K,"cache_write_tokens":W},
+ *     "output_tokens_details":{"reasoning_tokens":R}}}}
+ *
+ * Note that `response.created` arrives first carrying `usage: null`, which is
+ * why the scanner keeps the last non-null result rather than the first.
+ *
+ * It also accepts a `usage` object at the top level of any event and the
+ * `prompt_tokens`/`completion_tokens` spellings. A `null` result means "not
+ * observed", never "zero tokens".
+ */
+import type { CodexStreamUsage } from "../types/index.js";
+/**
+ * Pull usage out of one parsed SSE `data:` payload.
+ *
+ * Returns null when the payload carries no recognisable usage object, so the
+ * caller can keep the last non-null result rather than overwriting it with a
+ * later event that happens not to carry usage.
+ */
+export declare function extractCodexUsage(payload: unknown): CodexStreamUsage | null;
+/**
+ * Scan a slice of SSE text for usage, returning the last one found.
+ *
+ * Exported for tests: it is the whole parsing decision, and driving it through
+ * a real Codex stream would need a live ChatGPT subscription.
+ */
+export declare function scanCodexSSEForUsage(text: string): CodexStreamUsage | null;
+/**
+ * A pass-through TransformStream that reports the usage seen on a Codex SSE
+ * stream.
+ *
+ * `usage` resolves when the stream ends: to the last usage observed, or null if
+ * none was. It never rejects.
+ */
+export declare function createCodexUsageTap(): {
+    stream: TransformStream<Uint8Array, Uint8Array>;
+    usage: Promise<CodexStreamUsage | null>;
+};