@x12i/ai-gateway 9.0.3 → 9.0.8

package/dist/gateway-retry.d.ts

@@ -34,7 +34,27 @@ export declare function sleep(ms: number): Promise<void>;
  * Invokes router with retry logic for network and server errors
  * Returns response and retry metadata
  */
-export declare function invokeWithRetry(routerRequest: any, retryConfig: RetryConfig, jobId: string, router: LLMProviderRouter, logger: Logxer): Promise<{
+export declare function invokeWithRetry(routerRequest: any, retryConfig: RetryConfig, jobId: string, router: LLMProviderRouter, logger: Logxer, hooks?: {
+    /**
+     * Called immediately before each provider call attempt (including the first try).
+     * `retryIndex` is 0-based within this invokeWithRetry call.
+     */
+    onTryStart?: (info: {
+        retryIndex: number;
+        startedAt: number;
+    }) => void;
+    /**
+     * Called immediately after each provider call attempt finishes (success or error).
+     * `retryIndex` is 0-based within this invokeWithRetry call.
+     */
+    onTryEnd?: (info: {
+        retryIndex: number;
+        endedAt: number;
+        ok: boolean;
+        response?: any;
+        error?: Error;
+    }) => void;
+}): Promise<{
     response: any;
     retryMetadata?: {
         retryCount: number;

package/dist/gateway-retry.js

@@ -93,7 +93,7 @@ export function sleep(ms) {
  * Invokes router with retry logic for network and server errors
  * Returns response and retry metadata
  */
-export async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger) {
+export async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger, hooks) {
     const maxRetries = retryConfig.maxRetries ?? 3;
     const initialDelay = retryConfig.initialDelay ?? 1000;
     const maxDelay = retryConfig.maxDelay ?? 30000;
@@ -103,8 +103,12 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
     let lastError;
     const retryAttempts = [];
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const startedAt = Date.now();
+        hooks?.onTryStart?.({ retryIndex: attempt, startedAt });
         try {
             const response = await router.invoke(routerRequest);
+            const endedAt = Date.now();
+            hooks?.onTryEnd?.({ retryIndex: attempt, endedAt, ok: true, response });
             // Log success after retry if this wasn't the first attempt
             if (attempt > 0) {
                 logger.info('Request succeeded after retry', {
@@ -128,6 +132,8 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
         }
         catch (error) {
             lastError = error instanceof Error ? error : new Error(String(error));
+            const endedAt = Date.now();
+            hooks?.onTryEnd?.({ retryIndex: attempt, endedAt, ok: false, error: lastError });
             // Check if error is retryable
             if (!isRetryableError(lastError)) {
                 logger.debug('Non-retryable error, not retrying', {

package/dist/gateway-utils.d.ts

@@ -19,3 +19,20 @@ export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer):
 export declare function mergeConfig(request: ChatRequest & {
     useInternalDefaults?: 'skill' | 'audit';
 }, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;
+/**
+ * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ */
+export declare function normalizeRouterUsageTokens(usage: unknown): {
+    prompt: number;
+    completion: number;
+    total: number;
+} | undefined;
+/**
+ * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ */
+export declare function extractTokenUsageFromRouterResponse(routerResponse: unknown): {
+    prompt: number;
+    completion: number;
+    total: number;
+};

package/dist/gateway-utils.js

@@ -179,3 +179,55 @@ export async function mergeConfig(request, config, logger) {
     });
     return merged;
 }
+function firstFiniteNumber(...vals) {
+    for (const v of vals) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ */
+export function normalizeRouterUsageTokens(usage) {
+    if (usage == null || typeof usage !== 'object')
+        return undefined;
+    const u = usage;
+    const prompt = firstFiniteNumber(u.promptTokens, u.inputTokens, u.prompt, u.prompt_tokens) ?? 0;
+    const completion = firstFiniteNumber(u.completionTokens, u.outputTokens, u.completion, u.completion_tokens) ?? 0;
+    let total = firstFiniteNumber(u.totalTokens, u.total_tokens) ?? 0;
+    if (!total && (prompt || completion))
+        total = prompt + completion;
+    return { prompt, completion, total };
+}
+/**
+ * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ */
+export function extractTokenUsageFromRouterResponse(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object') {
+        return { prompt: 0, completion: 0, total: 0 };
+    }
+    const r = routerResponse;
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    const buckets = [r.usage];
+    if (meta) {
+        buckets.push(meta.usage);
+        const nested = meta['ai-activities-response'];
+        if (nested != null && typeof nested === 'object') {
+            buckets.push(nested.usage);
+        }
+    }
+    const raw = r.rawResponse ?? r.raw;
+    if (raw != null && typeof raw === 'object') {
+        buckets.push(raw.usage);
+    }
+    for (const b of buckets) {
+        const n = normalizeRouterUsageTokens(b);
+        if (n && (n.prompt || n.completion || n.total))
+            return n;
+    }
+    return { prompt: 0, completion: 0, total: 0 };
+}

package/dist/gateway.js

@@ -8,10 +8,11 @@ import { ensureGatewayRequestIdentity } from './activity-manager.js';
 import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
-import { mergeConfig } from './gateway-utils.js';
+import { extractTokenUsageFromRouterResponse, mergeConfig } from './gateway-utils.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+import { invokeWithRetry } from './gateway-retry.js';
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
 const NO_PROVIDER_HINT = ' Set OPEN_ROUTER_KEY (or OPENROUTER_API_KEY) in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
@@ -93,7 +94,7 @@ export class AIGateway {
                     aiRequestId: request.aiRequestId,
                     identity: request.identity,
                     latencyMs: Date.now() - startTime,
-                    tokens: response.usage || { prompt: 0, completion: 0, total: 0 },
+                    tokens: extractTokenUsageFromRouterResponse(response),
                     taskTypeId,
                     agentType: 'chat'
                 }
@@ -203,6 +204,9 @@ export class AIGateway {
         request._parsedRequest = parsedSnapshot;
         // Merge config (modelConfig > request.config > gateway defaults)
         const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        const diagnosticsMode = request.diagnostics?.mode;
+        const traceEnabled = diagnosticsMode === 'trace';
+        const includeRawProviderPayload = request.diagnostics?.includeRawProviderPayload === true;
         // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
         if (!this._autoRegisterDone) {
             await autoRegisterProviders(this.router, this.logger);
@@ -223,15 +227,206 @@ export class AIGateway {
             }
         }
         try {
-            // Call router directly with merged config
-            const response = await this.router.invoke({
-                request: {
-                    messages,
-                    config: mergedConfig,
-                    identity: request.identity
-                },
-                mode: 'sync'
-            });
+            let response;
+            let traceAttempts;
+            let traceRetryCount;
+            let traceFallbackCount;
+            let traceRequestIds;
+            let providerCallLatencyMs;
+            if (!traceEnabled) {
+                // Default minimal behavior (no extra allocations/payload).
+                response = await this.router.invoke({
+                    request: {
+                        messages,
+                        config: mergedConfig,
+                        identity: request.identity
+                    },
+                    mode: 'sync'
+                });
+            }
+            else {
+                const capString = (s, maxLen) => (s.length <= maxLen ? s : s.slice(0, maxLen) + '…');
+                const capErrorMessage = (s) => capString(s, 500);
+                const safeJsonStringify = (value) => {
+                    try {
+                        return JSON.stringify(value);
+                    }
+                    catch {
+                        return '[Unserializable]';
+                    }
+                };
+                const gatewayAiRequestId = request.aiRequestId;
+                const baseRequest = {
+                    request: {
+                        messages,
+                        config: mergedConfig,
+                        identity: request.identity
+                    },
+                    mode: 'sync'
+                };
+                // Build deterministic provider/model candidate chain.
+                const candidates = [];
+                const primaryProvider = mergedConfig?.provider;
+                const primaryModel = mergedConfig?.model;
+                if (typeof primaryProvider === 'string' && typeof primaryModel === 'string') {
+                    candidates.push({ provider: primaryProvider, model: primaryModel });
+                }
+                const defaultTarget = this.config?.defaultTarget;
+                if (defaultTarget?.engine && defaultTarget?.model) {
+                    candidates.push({ provider: String(defaultTarget.engine), model: String(defaultTarget.model) });
+                }
+                const fallbackChain = this.config?.fallbackChain;
+                if (Array.isArray(fallbackChain)) {
+                    for (const item of fallbackChain) {
+                        if (item && typeof item === 'object' && 'engine' in item && 'model' in item) {
+                            candidates.push({ provider: String(item.engine), model: String(item.model) });
+                        }
+                    }
+                }
+                // De-dup while preserving order.
+                const seen = new Set();
+                const deduped = candidates.filter(c => {
+                    const key = `${c.provider}::${c.model}`;
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+                traceAttempts = [];
+                // Attempt execution across fallbacks (authoritative ordering).
+                let lastError;
+                for (let fallbackIndex = 0; fallbackIndex < deduped.length; fallbackIndex++) {
+                    const candidate = deduped[fallbackIndex];
+                    // Track per-retry attempt objects through retry hooks.
+                    const attemptIndexByRetry = new Map();
+                    try {
+                        const result = await invokeWithRetry({
+                            ...baseRequest,
+                            request: {
+                                ...baseRequest.request,
+                                config: {
+                                    ...mergedConfig,
+                                    provider: candidate.provider,
+                                    model: candidate.model
+                                }
+                            }
+                        }, (this.config.retry ?? {}), request.identity.jobId || request.aiRequestId, this.router, this.logger, {
+                            onTryStart: ({ retryIndex, startedAt }) => {
+                                const idx = traceAttempts.push({
+                                    timing: { startedAt, endedAt: startedAt, durationMs: 0 },
+                                    routing: {
+                                        provider: candidate.provider,
+                                        requestIds: { gatewayAiRequestId },
+                                        retryIndex,
+                                        fallbackIndex
+                                    },
+                                    usage: {
+                                        tokens: { prompt: 0, completion: 0, total: 0 },
+                                        maxTokensRequested: typeof mergedConfig?.maxTokens === 'number' ? mergedConfig.maxTokens : undefined
+                                    },
+                                    modelUsed: candidate.model,
+                                    ok: false
+                                }) - 1;
+                                attemptIndexByRetry.set(retryIndex, idx);
+                            },
+                            onTryEnd: ({ retryIndex, endedAt, ok, response: tryResp, error: tryErr }) => {
+                                const idx = attemptIndexByRetry.get(retryIndex);
+                                if (idx === undefined)
+                                    return;
+                                const a = traceAttempts[idx];
+                                a.timing.endedAt = endedAt;
+                                a.timing.durationMs = Math.max(0, endedAt - a.timing.startedAt);
+                                a.ok = ok;
+                                const respAny = tryResp;
+                                if (ok && respAny) {
+                                    const meta = respAny.metadata || {};
+                                    const tokenCounts = extractTokenUsageFromRouterResponse(respAny);
+                                    a.usage = {
+                                        tokens: tokenCounts,
+                                        maxTokensRequested: typeof meta?.maxTokensRequested === 'number'
+                                            ? meta.maxTokensRequested
+                                            : typeof mergedConfig?.maxTokens === 'number'
+                                                ? mergedConfig.maxTokens
+                                                : undefined
+                                    };
+                                    a.routing.provider = meta?.provider || respAny.provider || candidate.provider;
+                                    if (typeof meta?.region === 'string')
+                                        a.routing.region = meta.region;
+                                    const requestIds = {
+                                        gatewayAiRequestId,
+                                        routerRequestId: respAny.requestId || meta?.requestId
+                                    };
+                                    if (typeof meta?.providerRequestId === 'string')
+                                        requestIds.providerRequestId = meta.providerRequestId;
+                                    if (typeof meta?.openrouterRequestId === 'string')
+                                        requestIds.openrouterRequestId = meta.openrouterRequestId;
+                                    if (meta?.requestIds && typeof meta.requestIds === 'object') {
+                                        for (const [k, v] of Object.entries(meta.requestIds)) {
+                                            if (typeof v === 'string')
+                                                requestIds[k] = v;
+                                        }
+                                    }
+                                    a.routing.requestIds = requestIds;
+                                    a.modelUsed =
+                                        meta?.modelUsed || meta?.model || respAny.model || candidate.model;
+                                    const costUsd = typeof meta?.costUsd === 'number'
+                                        ? meta.costUsd
+                                        : typeof meta?.cost === 'number'
+                                            ? meta.cost
+                                            : typeof respAny?.costUsd === 'number'
+                                                ? respAny.costUsd
+                                                : typeof respAny?.cost === 'number'
+                                                    ? respAny.cost
+                                                    : undefined;
+                                    if (typeof costUsd === 'number')
+                                        a.costUsd = costUsd;
+                                    if (includeRawProviderPayload) {
+                                        // Size-capped preview only.
+                                        const raw = respAny.rawResponse ?? respAny.raw ?? respAny;
+                                        const rawStr = typeof raw === 'string' ? raw : safeJsonStringify(raw);
+                                        a.rawProviderPayload = capString(rawStr, 4000);
+                                    }
+                                }
+                                else if (tryErr) {
+                                    a.error = { name: tryErr.name || 'Error', message: capErrorMessage(tryErr.message || String(tryErr)) };
+                                }
+                            }
+                        });
+                        response = result.response;
+                        lastError = undefined;
+                        break; // success => stop fallback chain
+                    }
+                    catch (err) {
+                        lastError = err instanceof Error ? err : new Error(String(err));
+                        continue;
+                    }
+                }
+                if (!response) {
+                    throw lastError ?? new Error('All fallback candidates failed');
+                }
+                // Summary counts + final request ids.
+                traceRetryCount = traceAttempts.filter(a => a.routing.retryIndex > 0).length;
+                const fallbackIndices = new Set(traceAttempts.map(a => a.routing.fallbackIndex));
+                traceFallbackCount = Math.max(0, fallbackIndices.size - 1);
+                const finalResp = response;
+                const finalMeta = finalResp?.metadata || {};
+                traceRequestIds = {
+                    gatewayAiRequestId,
+                    routerRequestId: finalResp?.requestId || finalMeta?.requestId
+                };
+                if (typeof finalMeta?.providerRequestId === 'string')
+                    traceRequestIds.providerRequestId = finalMeta.providerRequestId;
+                if (typeof finalMeta?.openrouterRequestId === 'string')
+                    traceRequestIds.openrouterRequestId = finalMeta.openrouterRequestId;
+                if (finalMeta?.requestIds && typeof finalMeta.requestIds === 'object') {
+                    for (const [k, v] of Object.entries(finalMeta.requestIds)) {
+                        if (typeof v === 'string')
+                            traceRequestIds[k] = v;
+                    }
+                }
+                const lastOk = [...traceAttempts].reverse().find(a => a.ok);
+                providerCallLatencyMs = lastOk?.timing?.durationMs;
+            }
             // Contract output processing removed - expectedSchema no longer supported
             // Create enhanced response - extract content properly from router response
             const routerResponse = response;
@@ -293,35 +488,49 @@ export class AIGateway {
             }
             contentType = 'structured';
             parsingMethod = 'flex-md';
-            // Extract token usage properly
-            let tokens = { prompt: 0, completion: 0, total: 0 };
-            if (routerResponse.usage) {
-                tokens = {
-                    prompt: routerResponse.usage.promptTokens || routerResponse.usage.inputTokens || 0,
-                    completion: routerResponse.usage.completionTokens || routerResponse.usage.outputTokens || 0,
-                    total: routerResponse.usage.totalTokens || 0
-                };
-            }
-            else if (routerResponse.metadata?.['ai-activities-response']?.usage) {
-                const usage = routerResponse.metadata['ai-activities-response'].usage;
-                tokens = {
-                    prompt: usage.promptTokens || usage.inputTokens || 0,
-                    completion: usage.completionTokens || usage.outputTokens || 0,
-                    total: usage.totalTokens || 0
-                };
-            }
+            const tokens = extractTokenUsageFromRouterResponse(routerResponse);
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
                 metadata: {
                     aiRequestId: request.aiRequestId,
                     identity: request.identity,
-                    latencyMs: Date.now() - startTime,
+                    latencyMs: traceEnabled && typeof providerCallLatencyMs === 'number' ? providerCallLatencyMs : (Date.now() - startTime),
                     tokens: tokens,
                     taskTypeId,
                     agentType: 'ai',
                     contentType,
-                    parsingMethod
+                    parsingMethod,
+                    ...(traceEnabled
+                        ? (() => {
+                            const meta = routerResponse?.metadata || {};
+                            const provider = meta.provider || routerResponse?.provider || mergedConfig?.provider;
+                            const region = typeof meta.region === 'string' ? meta.region : undefined;
+                            const modelUsed = meta.modelUsed || meta.model || routerResponse?.model || mergedConfig?.model;
+                            const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
+                                ? meta.maxTokensRequested
+                                : typeof mergedConfig?.maxTokens === 'number'
+                                    ? mergedConfig.maxTokens
+                                    : undefined;
+                            const costUsd = typeof meta.costUsd === 'number'
+                                ? meta.costUsd
+                                : typeof meta.cost === 'number'
+                                    ? meta.cost
+                                    : undefined;
+                            return {
+                                provider,
+                                region,
+                                modelUsed,
+                                maxTokensRequested,
+                                cost: typeof meta.cost === 'number' ? meta.cost : undefined,
+                                costUsd,
+                                requestIds: traceRequestIds,
+                                retryCount: traceRetryCount,
+                                fallbackCount: traceFallbackCount,
+                                attempts: traceAttempts
+                            };
+                        })()
+                        : {})
                 }
             };
             // Track activity success if activity was started

package/dist/types.d.ts

@@ -10,6 +10,65 @@ export type UsageTier = string;
 import type { Activix } from '@x12i/activix';
 import type { TemplateRenderOptions } from '@x12i/rendrix';
 import type { Logxer } from '@x12i/logxer';
+/**
+ * Diagnostics options for opt-in authoritative tracing.
+ * Default behavior must remain minimal when diagnostics are not enabled.
+ */
+export type DiagnosticsMode = 'none' | 'trace';
+export interface DiagnosticsOptions {
+    mode?: DiagnosticsMode;
+    /**
+     * Whether to include raw provider payloads (NEVER on by default).
+     * Implementations must size-cap any raw payload included.
+     */
+    includeRawProviderPayload?: boolean;
+}
+export type GatewayTraceRequestIds = {
+    /** Stable alias of gateway aiRequestId (always set when trace enabled). */
+    gatewayAiRequestId: string;
+    /** Router-level correlation id, when available. */
+    routerRequestId?: string;
+    /** Provider-level request id (or equivalent), when available. */
+    providerRequestId?: string;
+    /** OpenRouter request id, when applicable and available. */
+    openrouterRequestId?: string;
+    /** Allow additional stable ids without breaking contract. */
+    [key: string]: string | undefined;
+};
+export type GatewayTraceAttempt = {
+    timing: {
+        startedAt: number;
+        endedAt: number;
+        durationMs: number;
+    };
+    routing: {
+        provider: string;
+        region?: string;
+        requestIds: GatewayTraceRequestIds;
+        retryIndex: number;
+        fallbackIndex: number;
+    };
+    usage?: {
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+        maxTokensRequested?: number;
+    };
+    modelUsed?: string;
+    costUsd?: number;
+    ok: boolean;
+    error?: {
+        name: string;
+        message: string;
+    };
+    /**
+     * Optional raw provider payload (size-capped, gated by request flag).
+     * The exact shape is intentionally loose to avoid locking downstream to provider schemas.
+     */
+    rawProviderPayload?: unknown;
+};
 /**
  * Identity object used for activity linkage.
  * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,
@@ -606,6 +665,11 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Used when inferenceType is provided for parsing inference outputs
      */
     parseOptions?: Record<string, unknown>;
+    /**
+     * Optional diagnostics controls. When omitted or mode != 'trace', the gateway must not
+     * attach heavy diagnostic objects or raw provider payloads.
+     */
+    diagnostics?: DiagnosticsOptions;
 }
 /**
  * Chat request for conversational use cases
@@ -835,6 +899,41 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Cost in USD (if available)
          */
         cost?: number;
+        /**
+         * Cost in USD (preferred, stable key for trace mode).
+         * When both are present, costUsd should mirror cost.
+         */
+        costUsd?: number;
+        /**
+         * Final effective max token cap applied (after merges/normalization), if known.
+         */
+        maxTokensRequested?: number;
+        /**
+         * Model that actually served the response (after routing/fallback), if known.
+         * This is distinct from requested model.
+         */
+        modelUsed?: string;
+        /**
+         * Optional region identifier when applicable (provider-specific).
+         */
+        region?: string;
+        /**
+         * Stable request/correlation identifiers across gateway/router/provider layers.
+         * Only populated when diagnostics trace mode is enabled.
+         */
+        requestIds?: GatewayTraceRequestIds;
+        /**
+         * Total number of retries performed across the execution (trace mode).
+         */
+        retryCount?: number;
+        /**
+         * Total number of fallback transitions performed across the execution (trace mode).
+         */
+        fallbackCount?: number;
+        /**
+         * Ordered, authoritative attempts across retries and fallbacks (trace mode).
+         */
+        attempts?: GatewayTraceAttempt[];
         /**
          * Content type classification
          * Indicates whether content is 'string', 'object', 'array', or 'null'

package/dist/usage-tracker.js

@@ -8,6 +8,7 @@
  *
  * Note: x-models dependency removed - usage tracking functions are permanently disabled
  */
+import { extractTokenUsageFromRouterResponse } from './gateway-utils.js';
 /**
  * Manages usage tracking for LLM requests
  */
@@ -26,11 +27,7 @@ export class UsageTracker {
      * @returns Token usage breakdown
      */
     extractTokens(response) {
-        return {
-            prompt: response.usage?.promptTokens || 0,
-            completion: response.usage?.completionTokens || 0,
-            total: response.usage?.totalTokens || 0
-        };
+        return extractTokenUsageFromRouterResponse(response);
     }
     /**
      * Records usage for a request

package/dist-cjs/gateway-retry.cjs

@@ -101,7 +101,7 @@ function sleep(ms) {
  * Invokes router with retry logic for network and server errors
  * Returns response and retry metadata
  */
-async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger) {
+async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger, hooks) {
     const maxRetries = retryConfig.maxRetries ?? 3;
     const initialDelay = retryConfig.initialDelay ?? 1000;
     const maxDelay = retryConfig.maxDelay ?? 30000;
@@ -111,8 +111,12 @@ async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger
     let lastError;
     const retryAttempts = [];
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        const startedAt = Date.now();
+        hooks?.onTryStart?.({ retryIndex: attempt, startedAt });
         try {
             const response = await router.invoke(routerRequest);
+            const endedAt = Date.now();
+            hooks?.onTryEnd?.({ retryIndex: attempt, endedAt, ok: true, response });
             // Log success after retry if this wasn't the first attempt
             if (attempt > 0) {
                 logger.info('Request succeeded after retry', {
@@ -136,6 +140,8 @@ async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger
         }
         catch (error) {
             lastError = error instanceof Error ? error : new Error(String(error));
+            const endedAt = Date.now();
+            hooks?.onTryEnd?.({ retryIndex: attempt, endedAt, ok: false, error: lastError });
             // Check if error is retryable
             if (!isRetryableError(lastError)) {
                 logger.debug('Non-retryable error, not retrying', {

package/dist-cjs/gateway-retry.d.ts

@@ -34,7 +34,27 @@ export declare function sleep(ms: number): Promise<void>;
  * Invokes router with retry logic for network and server errors
  * Returns response and retry metadata
  */
-export declare function invokeWithRetry(routerRequest: any, retryConfig: RetryConfig, jobId: string, router: LLMProviderRouter, logger: Logxer): Promise<{
+export declare function invokeWithRetry(routerRequest: any, retryConfig: RetryConfig, jobId: string, router: LLMProviderRouter, logger: Logxer, hooks?: {
+    /**
+     * Called immediately before each provider call attempt (including the first try).
+     * `retryIndex` is 0-based within this invokeWithRetry call.
+     */
+    onTryStart?: (info: {
+        retryIndex: number;
+        startedAt: number;
+    }) => void;
+    /**
+     * Called immediately after each provider call attempt finishes (success or error).
+     * `retryIndex` is 0-based within this invokeWithRetry call.
+     */
+    onTryEnd?: (info: {
+        retryIndex: number;
+        endedAt: number;
+        ok: boolean;
+        response?: any;
+        error?: Error;
+    }) => void;
+}): Promise<{
     response: any;
     retryMetadata?: {
         retryCount: number;

package/dist-cjs/gateway-utils.cjs

@@ -40,6 +40,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateMD5Hash = generateMD5Hash;
 exports.ensureTaskTypeId = ensureTaskTypeId;
 exports.mergeConfig = mergeConfig;
+exports.normalizeRouterUsageTokens = normalizeRouterUsageTokens;
+exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterResponse;
 const crypto = __importStar(require("crypto"));
 const gateway_instructions_js_1 = require("./gateway-instructions.cjs");
 const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
@@ -217,3 +219,55 @@ async function mergeConfig(request, config, logger) {
     });
     return merged;
 }
+function firstFiniteNumber(...vals) {
+    for (const v of vals) {
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ */
+function normalizeRouterUsageTokens(usage) {
+    if (usage == null || typeof usage !== 'object')
+        return undefined;
+    const u = usage;
+    const prompt = firstFiniteNumber(u.promptTokens, u.inputTokens, u.prompt, u.prompt_tokens) ?? 0;
+    const completion = firstFiniteNumber(u.completionTokens, u.outputTokens, u.completion, u.completion_tokens) ?? 0;
+    let total = firstFiniteNumber(u.totalTokens, u.total_tokens) ?? 0;
+    if (!total && (prompt || completion))
+        total = prompt + completion;
+    return { prompt, completion, total };
+}
+/**
+ * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ */
+function extractTokenUsageFromRouterResponse(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object') {
+        return { prompt: 0, completion: 0, total: 0 };
+    }
+    const r = routerResponse;
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    const buckets = [r.usage];
+    if (meta) {
+        buckets.push(meta.usage);
+        const nested = meta['ai-activities-response'];
+        if (nested != null && typeof nested === 'object') {
+            buckets.push(nested.usage);
+        }
+    }
+    const raw = r.rawResponse ?? r.raw;
+    if (raw != null && typeof raw === 'object') {
+        buckets.push(raw.usage);
+    }
+    for (const b of buckets) {
+        const n = normalizeRouterUsageTokens(b);
+        if (n && (n.prompt || n.completion || n.total))
+            return n;
+    }
+    return { prompt: 0, completion: 0, total: 0 };
+}

package/dist-cjs/gateway-utils.d.ts

@@ -19,3 +19,20 @@ export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer):
 export declare function mergeConfig(request: ChatRequest & {
     useInternalDefaults?: 'skill' | 'audit';
 }, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;
+/**
+ * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ */
+export declare function normalizeRouterUsageTokens(usage: unknown): {
+    prompt: number;
+    completion: number;
+    total: number;
+} | undefined;
+/**
+ * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ */
+export declare function extractTokenUsageFromRouterResponse(routerResponse: unknown): {
+    prompt: number;
+    completion: number;
+    total: number;
+};

package/dist-cjs/gateway.cjs

@@ -15,6 +15,7 @@ const gateway_utils_js_1 = require("./gateway-utils.cjs");
 const gateway_provider_auto_register_js_1 = require("./gateway-provider-auto-register.cjs");
 const runtime_objects_js_1 = require("./runtime-objects.cjs");
 const gateway_log_meta_js_1 = require("./gateway-log-meta.cjs");
+const gateway_retry_js_1 = require("./gateway-retry.cjs");
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
 const NO_PROVIDER_HINT = ' Set OPEN_ROUTER_KEY (or OPENROUTER_API_KEY) in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
@@ -96,7 +97,7 @@ class AIGateway {
                     aiRequestId: request.aiRequestId,
                     identity: request.identity,
                     latencyMs: Date.now() - startTime,
-                    tokens: response.usage || { prompt: 0, completion: 0, total: 0 },
+                    tokens: (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(response),
                     taskTypeId,
                     agentType: 'chat'
                 }
@@ -206,6 +207,9 @@ class AIGateway {
         request._parsedRequest = parsedSnapshot;
         // Merge config (modelConfig > request.config > gateway defaults)
         const mergedConfig = await (0, gateway_utils_js_1.mergeConfig)(request, this.config, this.logger);
+        const diagnosticsMode = request.diagnostics?.mode;
+        const traceEnabled = diagnosticsMode === 'trace';
+        const includeRawProviderPayload = request.diagnostics?.includeRawProviderPayload === true;
         // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
         if (!this._autoRegisterDone) {
             await (0, gateway_provider_auto_register_js_1.autoRegisterProviders)(this.router, this.logger);
@@ -226,15 +230,206 @@ class AIGateway {
             }
         }
         try {
-            // Call router directly with merged config
-            const response = await this.router.invoke({
-                request: {
-                    messages,
-                    config: mergedConfig,
-                    identity: request.identity
-                },
-                mode: 'sync'
-            });
+            let response;
+            let traceAttempts;
+            let traceRetryCount;
+            let traceFallbackCount;
+            let traceRequestIds;
+            let providerCallLatencyMs;
+            if (!traceEnabled) {
+                // Default minimal behavior (no extra allocations/payload).
+                response = await this.router.invoke({
+                    request: {
+                        messages,
+                        config: mergedConfig,
+                        identity: request.identity
+                    },
+                    mode: 'sync'
+                });
+            }
+            else {
+                const capString = (s, maxLen) => (s.length <= maxLen ? s : s.slice(0, maxLen) + '…');
+                const capErrorMessage = (s) => capString(s, 500);
+                const safeJsonStringify = (value) => {
+                    try {
+                        return JSON.stringify(value);
+                    }
+                    catch {
+                        return '[Unserializable]';
+                    }
+                };
+                const gatewayAiRequestId = request.aiRequestId;
+                const baseRequest = {
+                    request: {
+                        messages,
+                        config: mergedConfig,
+                        identity: request.identity
+                    },
+                    mode: 'sync'
+                };
+                // Build deterministic provider/model candidate chain.
+                const candidates = [];
+                const primaryProvider = mergedConfig?.provider;
+                const primaryModel = mergedConfig?.model;
+                if (typeof primaryProvider === 'string' && typeof primaryModel === 'string') {
+                    candidates.push({ provider: primaryProvider, model: primaryModel });
+                }
+                const defaultTarget = this.config?.defaultTarget;
+                if (defaultTarget?.engine && defaultTarget?.model) {
+                    candidates.push({ provider: String(defaultTarget.engine), model: String(defaultTarget.model) });
+                }
+                const fallbackChain = this.config?.fallbackChain;
+                if (Array.isArray(fallbackChain)) {
+                    for (const item of fallbackChain) {
+                        if (item && typeof item === 'object' && 'engine' in item && 'model' in item) {
+                            candidates.push({ provider: String(item.engine), model: String(item.model) });
+                        }
+                    }
+                }
+                // De-dup while preserving order.
+                const seen = new Set();
+                const deduped = candidates.filter(c => {
+                    const key = `${c.provider}::${c.model}`;
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                });
+                traceAttempts = [];
+                // Attempt execution across fallbacks (authoritative ordering).
+                let lastError;
+                for (let fallbackIndex = 0; fallbackIndex < deduped.length; fallbackIndex++) {
+                    const candidate = deduped[fallbackIndex];
+                    // Track per-retry attempt objects through retry hooks.
+                    const attemptIndexByRetry = new Map();
+                    try {
+                        const result = await (0, gateway_retry_js_1.invokeWithRetry)({
+                            ...baseRequest,
+                            request: {
+                                ...baseRequest.request,
+                                config: {
+                                    ...mergedConfig,
+                                    provider: candidate.provider,
+                                    model: candidate.model
+                                }
+                            }
+                        }, (this.config.retry ?? {}), request.identity.jobId || request.aiRequestId, this.router, this.logger, {
+                            onTryStart: ({ retryIndex, startedAt }) => {
+                                const idx = traceAttempts.push({
+                                    timing: { startedAt, endedAt: startedAt, durationMs: 0 },
+                                    routing: {
+                                        provider: candidate.provider,
+                                        requestIds: { gatewayAiRequestId },
+                                        retryIndex,
+                                        fallbackIndex
+                                    },
+                                    usage: {
+                                        tokens: { prompt: 0, completion: 0, total: 0 },
+                                        maxTokensRequested: typeof mergedConfig?.maxTokens === 'number' ? mergedConfig.maxTokens : undefined
+                                    },
+                                    modelUsed: candidate.model,
+                                    ok: false
+                                }) - 1;
+                                attemptIndexByRetry.set(retryIndex, idx);
+                            },
+                            onTryEnd: ({ retryIndex, endedAt, ok, response: tryResp, error: tryErr }) => {
+                                const idx = attemptIndexByRetry.get(retryIndex);
+                                if (idx === undefined)
+                                    return;
+                                const a = traceAttempts[idx];
+                                a.timing.endedAt = endedAt;
+                                a.timing.durationMs = Math.max(0, endedAt - a.timing.startedAt);
+                                a.ok = ok;
+                                const respAny = tryResp;
+                                if (ok && respAny) {
+                                    const meta = respAny.metadata || {};
+                                    const tokenCounts = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(respAny);
+                                    a.usage = {
+                                        tokens: tokenCounts,
+                                        maxTokensRequested: typeof meta?.maxTokensRequested === 'number'
+                                            ? meta.maxTokensRequested
+                                            : typeof mergedConfig?.maxTokens === 'number'
+                                                ? mergedConfig.maxTokens
+                                                : undefined
+                                    };
+                                    a.routing.provider = meta?.provider || respAny.provider || candidate.provider;
+                                    if (typeof meta?.region === 'string')
+                                        a.routing.region = meta.region;
+                                    const requestIds = {
+                                        gatewayAiRequestId,
+                                        routerRequestId: respAny.requestId || meta?.requestId
+                                    };
+                                    if (typeof meta?.providerRequestId === 'string')
+                                        requestIds.providerRequestId = meta.providerRequestId;
+                                    if (typeof meta?.openrouterRequestId === 'string')
+                                        requestIds.openrouterRequestId = meta.openrouterRequestId;
+                                    if (meta?.requestIds && typeof meta.requestIds === 'object') {
+                                        for (const [k, v] of Object.entries(meta.requestIds)) {
+                                            if (typeof v === 'string')
+                                                requestIds[k] = v;
+                                        }
+                                    }
+                                    a.routing.requestIds = requestIds;
+                                    a.modelUsed =
+                                        meta?.modelUsed || meta?.model || respAny.model || candidate.model;
+                                    const costUsd = typeof meta?.costUsd === 'number'
+                                        ? meta.costUsd
+                                        : typeof meta?.cost === 'number'
+                                            ? meta.cost
+                                            : typeof respAny?.costUsd === 'number'
+                                                ? respAny.costUsd
+                                                : typeof respAny?.cost === 'number'
+                                                    ? respAny.cost
+                                                    : undefined;
+                                    if (typeof costUsd === 'number')
+                                        a.costUsd = costUsd;
+                                    if (includeRawProviderPayload) {
+                                        // Size-capped preview only.
+                                        const raw = respAny.rawResponse ?? respAny.raw ?? respAny;
+                                        const rawStr = typeof raw === 'string' ? raw : safeJsonStringify(raw);
+                                        a.rawProviderPayload = capString(rawStr, 4000);
+                                    }
+                                }
+                                else if (tryErr) {
+                                    a.error = { name: tryErr.name || 'Error', message: capErrorMessage(tryErr.message || String(tryErr)) };
+                                }
+                            }
+                        });
+                        response = result.response;
+                        lastError = undefined;
+                        break; // success => stop fallback chain
+                    }
+                    catch (err) {
+                        lastError = err instanceof Error ? err : new Error(String(err));
+                        continue;
+                    }
+                }
+                if (!response) {
+                    throw lastError ?? new Error('All fallback candidates failed');
+                }
+                // Summary counts + final request ids.
+                traceRetryCount = traceAttempts.filter(a => a.routing.retryIndex > 0).length;
+                const fallbackIndices = new Set(traceAttempts.map(a => a.routing.fallbackIndex));
+                traceFallbackCount = Math.max(0, fallbackIndices.size - 1);
+                const finalResp = response;
+                const finalMeta = finalResp?.metadata || {};
+                traceRequestIds = {
+                    gatewayAiRequestId,
+                    routerRequestId: finalResp?.requestId || finalMeta?.requestId
+                };
+                if (typeof finalMeta?.providerRequestId === 'string')
+                    traceRequestIds.providerRequestId = finalMeta.providerRequestId;
+                if (typeof finalMeta?.openrouterRequestId === 'string')
+                    traceRequestIds.openrouterRequestId = finalMeta.openrouterRequestId;
+                if (finalMeta?.requestIds && typeof finalMeta.requestIds === 'object') {
+                    for (const [k, v] of Object.entries(finalMeta.requestIds)) {
+                        if (typeof v === 'string')
+                            traceRequestIds[k] = v;
+                    }
+                }
+                const lastOk = [...traceAttempts].reverse().find(a => a.ok);
+                providerCallLatencyMs = lastOk?.timing?.durationMs;
+            }
             // Contract output processing removed - expectedSchema no longer supported
             // Create enhanced response - extract content properly from router response
             const routerResponse = response;
@@ -296,35 +491,49 @@ class AIGateway {
             }
             contentType = 'structured';
             parsingMethod = 'flex-md';
-            // Extract token usage properly
-            let tokens = { prompt: 0, completion: 0, total: 0 };
-            if (routerResponse.usage) {
-                tokens = {
-                    prompt: routerResponse.usage.promptTokens || routerResponse.usage.inputTokens || 0,
-                    completion: routerResponse.usage.completionTokens || routerResponse.usage.outputTokens || 0,
-                    total: routerResponse.usage.totalTokens || 0
-                };
-            }
-            else if (routerResponse.metadata?.['ai-activities-response']?.usage) {
-                const usage = routerResponse.metadata['ai-activities-response'].usage;
-                tokens = {
-                    prompt: usage.promptTokens || usage.inputTokens || 0,
-                    completion: usage.completionTokens || usage.outputTokens || 0,
-                    total: usage.totalTokens || 0
-                };
-            }
+            const tokens = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(routerResponse);
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
                 metadata: {
                     aiRequestId: request.aiRequestId,
                     identity: request.identity,
-                    latencyMs: Date.now() - startTime,
+                    latencyMs: traceEnabled && typeof providerCallLatencyMs === 'number' ? providerCallLatencyMs : (Date.now() - startTime),
                     tokens: tokens,
                     taskTypeId,
                     agentType: 'ai',
                     contentType,
-                    parsingMethod
+                    parsingMethod,
+                    ...(traceEnabled
+                        ? (() => {
+                            const meta = routerResponse?.metadata || {};
+                            const provider = meta.provider || routerResponse?.provider || mergedConfig?.provider;
+                            const region = typeof meta.region === 'string' ? meta.region : undefined;
+                            const modelUsed = meta.modelUsed || meta.model || routerResponse?.model || mergedConfig?.model;
+                            const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
+                                ? meta.maxTokensRequested
+                                : typeof mergedConfig?.maxTokens === 'number'
+                                    ? mergedConfig.maxTokens
+                                    : undefined;
+                            const costUsd = typeof meta.costUsd === 'number'
+                                ? meta.costUsd
+                                : typeof meta.cost === 'number'
+                                    ? meta.cost
+                                    : undefined;
+                            return {
+                                provider,
+                                region,
+                                modelUsed,
+                                maxTokensRequested,
+                                cost: typeof meta.cost === 'number' ? meta.cost : undefined,
+                                costUsd,
+                                requestIds: traceRequestIds,
+                                retryCount: traceRetryCount,
+                                fallbackCount: traceFallbackCount,
+                                attempts: traceAttempts
+                            };
+                        })()
+                        : {})
                 }
             };
             // Track activity success if activity was started

package/dist-cjs/types.d.ts

@@ -10,6 +10,65 @@ export type UsageTier = string;
 import type { Activix } from '@x12i/activix';
 import type { TemplateRenderOptions } from '@x12i/rendrix';
 import type { Logxer } from '@x12i/logxer';
+/**
+ * Diagnostics options for opt-in authoritative tracing.
+ * Default behavior must remain minimal when diagnostics are not enabled.
+ */
+export type DiagnosticsMode = 'none' | 'trace';
+export interface DiagnosticsOptions {
+    mode?: DiagnosticsMode;
+    /**
+     * Whether to include raw provider payloads (NEVER on by default).
+     * Implementations must size-cap any raw payload included.
+     */
+    includeRawProviderPayload?: boolean;
+}
+export type GatewayTraceRequestIds = {
+    /** Stable alias of gateway aiRequestId (always set when trace enabled). */
+    gatewayAiRequestId: string;
+    /** Router-level correlation id, when available. */
+    routerRequestId?: string;
+    /** Provider-level request id (or equivalent), when available. */
+    providerRequestId?: string;
+    /** OpenRouter request id, when applicable and available. */
+    openrouterRequestId?: string;
+    /** Allow additional stable ids without breaking contract. */
+    [key: string]: string | undefined;
+};
+export type GatewayTraceAttempt = {
+    timing: {
+        startedAt: number;
+        endedAt: number;
+        durationMs: number;
+    };
+    routing: {
+        provider: string;
+        region?: string;
+        requestIds: GatewayTraceRequestIds;
+        retryIndex: number;
+        fallbackIndex: number;
+    };
+    usage?: {
+        tokens: {
+            prompt: number;
+            completion: number;
+            total: number;
+        };
+        maxTokensRequested?: number;
+    };
+    modelUsed?: string;
+    costUsd?: number;
+    ok: boolean;
+    error?: {
+        name: string;
+        message: string;
+    };
+    /**
+     * Optional raw provider payload (size-capped, gated by request flag).
+     * The exact shape is intentionally loose to avoid locking downstream to provider schemas.
+     */
+    rawProviderPayload?: unknown;
+};
 /**
  * Identity object used for activity linkage.
  * On gateway requests/responses it lives on `identity`. When activity tracking persists via Activix v5+,
@@ -606,6 +665,11 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Used when inferenceType is provided for parsing inference outputs
      */
     parseOptions?: Record<string, unknown>;
+    /**
+     * Optional diagnostics controls. When omitted or mode != 'trace', the gateway must not
+     * attach heavy diagnostic objects or raw provider payloads.
+     */
+    diagnostics?: DiagnosticsOptions;
 }
 /**
  * Chat request for conversational use cases
@@ -835,6 +899,41 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Cost in USD (if available)
          */
         cost?: number;
+        /**
+         * Cost in USD (preferred, stable key for trace mode).
+         * When both are present, costUsd should mirror cost.
+         */
+        costUsd?: number;
+        /**
+         * Final effective max token cap applied (after merges/normalization), if known.
+         */
+        maxTokensRequested?: number;
+        /**
+         * Model that actually served the response (after routing/fallback), if known.
+         * This is distinct from requested model.
+         */
+        modelUsed?: string;
+        /**
+         * Optional region identifier when applicable (provider-specific).
+         */
+        region?: string;
+        /**
+         * Stable request/correlation identifiers across gateway/router/provider layers.
+         * Only populated when diagnostics trace mode is enabled.
+         */
+        requestIds?: GatewayTraceRequestIds;
+        /**
+         * Total number of retries performed across the execution (trace mode).
+         */
+        retryCount?: number;
+        /**
+         * Total number of fallback transitions performed across the execution (trace mode).
+         */
+        fallbackCount?: number;
+        /**
+         * Ordered, authoritative attempts across retries and fallbacks (trace mode).
+         */
+        attempts?: GatewayTraceAttempt[];
         /**
          * Content type classification
          * Indicates whether content is 'string', 'object', 'array', or 'null'

package/dist-cjs/usage-tracker.cjs

@@ -11,6 +11,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UsageTracker = void 0;
+const gateway_utils_js_1 = require("./gateway-utils.cjs");
 /**
  * Manages usage tracking for LLM requests
  */
@@ -29,11 +30,7 @@ class UsageTracker {
      * @returns Token usage breakdown
      */
     extractTokens(response) {
-        return {
-            prompt: response.usage?.promptTokens || 0,
-            completion: response.usage?.completionTokens || 0,
-            total: response.usage?.totalTokens || 0
-        };
+        return (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(response);
     }
     /**
      * Records usage for a request

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.0.3",
+  "version": "9.0.8",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -60,7 +60,7 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/ai-providers-router": "^4.7.1",
+    "@x12i/ai-providers-router": "^4.7.7",
     "@x12i/rendrix": "^4.2.0",
     "@aws-sdk/s3-request-presigner": "^3.953.0",
     "@x12i/env": "^4.0.1",