@x12i/ai-gateway 9.0.3 → 9.0.7

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.js

@@ -12,6 +12,7 @@ import { 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).';
@@ -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,209 @@ 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 usage = respAny.usage || meta?.['ai-activities-response']?.usage;
+                                    const prompt = usage?.promptTokens ?? usage?.inputTokens ?? 0;
+                                    const completion = usage?.completionTokens ?? usage?.outputTokens ?? 0;
+                                    const total = usage?.totalTokens ?? 0;
+                                    a.usage = {
+                                        tokens: { prompt, completion, total },
+                                        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;
@@ -316,12 +514,42 @@ export class AIGateway {
                 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-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.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).';
@@ -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,209 @@ 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 usage = respAny.usage || meta?.['ai-activities-response']?.usage;
+                                    const prompt = usage?.promptTokens ?? usage?.inputTokens ?? 0;
+                                    const completion = usage?.completionTokens ?? usage?.outputTokens ?? 0;
+                                    const total = usage?.totalTokens ?? 0;
+                                    a.usage = {
+                                        tokens: { prompt, completion, total },
+                                        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;
@@ -319,12 +517,42 @@ class AIGateway {
                 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.0.3",
+  "version": "9.0.7",
   "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",