@x12i/ai-gateway 9.6.3 → 9.6.5

package/dist-cjs/gateway.cjs

@@ -13,12 +13,13 @@ import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys }
 import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, hasNonZeroTokenUsage, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildOptimixerActualUsage, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, isMaxTokensExplicitlySet, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
 import { getAiToolsClient } from './ai-tools-client.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
+import { applyOpenRouterInvokePolicy } from './ai-tools-client.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
-import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+import { gatewayLogDebug, withActivityIdentity, withGatewayLogContext } 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 OPENROUTER_API_KEY in the environment to use OpenRouter (legacy OPEN_ROUTER_KEY is still read as fallback), or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
+const NO_PROVIDER_HINT = ' Set OPENROUTER_API_KEY in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
 /** Warn when a successful call reports no tokens and/or explicit zero cost (often missing adapter metadata). */
 function warnIfSuccessfulInvokeReportsZeroUsageOrCost(logger, identity, meta, invokeKind) {
     const { tokens, costUsd, cost } = meta;
@@ -51,6 +52,8 @@ export class AIGateway {
     defaultModelConfig = {};
     _autoRegisterDone = false;
     _aiToolsClient = null;
+    preferOpenRouter;
+    openRouterApiKey;
     constructor(config = {}, activityManager) {
         this.config = config;
         this.activityManager = activityManager;
@@ -61,6 +64,8 @@ export class AIGateway {
         this.optimixerManager = components.optimixerManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
         this.defaultModelConfig = components.defaultModelConfig ?? {};
+        this.preferOpenRouter = components.preferOpenRouter;
+        this.openRouterApiKey = components.openRouterApiKey;
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
             logger: this.logger
@@ -74,647 +79,665 @@ export class AIGateway {
      * Invoke chat request (without structured output requirements)
      */
     async invokeChat(request) {
-        const startTime = Date.now();
         // Basic validation
         validateChatRequest(request);
         ensureGatewayRequestIdentity(request, undefined, this.logger);
         setGatewayLastJobId(resolveRuntimeJobId(request));
-        // Generate simple task type ID
-        const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
-        // Simple message construction
-        const messages = this.buildSimpleMessages(request);
-        // Merge config (modelConfig > request.config > gateway defaults)
-        const aiTools = await this.getAiTools();
-        const mergedConfig = await mergeConfig(request, this.config, this.logger, {
-            defaultModelConfig: this.defaultModelConfig,
-            catalog: aiTools?.catalog ?? null
-        });
-        // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
-        request._mergedRouterConfig = mergedConfig;
-        // 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);
-            this._autoRegisterDone = true;
-        }
-        const optimixerPrediction = await this.applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages);
-        // Start activity tracking if available
-        let activity = undefined;
-        if (this.activityManager) {
-            try {
-                activity = await this.activityManager.startActivity(request, startTime);
-            }
-            catch (activityError) {
-                // Log activity tracking error but don't fail the request
-                this.logger.warn('Failed to start activity tracking', {
-                    aiRequestId: request.aiRequestId,
-                    error: activityError instanceof Error ? activityError.message : String(activityError)
-                });
-            }
-        }
-        try {
-            // Call router directly with merged config
-            const response = await this.router.invoke({
-                request: {
-                    messages,
-                    config: mergedConfig,
-                    identity: request.identity
-                },
-                mode: 'sync'
+        return withGatewayLogContext(request.identity, async () => {
+            const startTime = Date.now();
+            // Generate simple task type ID
+            const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
+            // Simple message construction
+            const messages = this.buildSimpleMessages(request);
+            // Merge config (modelConfig > request.config > gateway defaults)
+            const aiTools = await this.getAiTools();
+            const mergedConfig = await mergeConfig(request, this.config, this.logger, {
+                defaultModelConfig: this.defaultModelConfig,
+                catalog: aiTools?.catalog ?? null,
+                routingEnv: aiTools?.routingEnv,
             });
-            const metaChat = response?.metadata || {};
-            const tokensChat = extractTokenUsageFromRouterResponse(response);
-            const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
-                mergedConfig,
-                calculator: aiTools?.calculator ?? null,
-                calculateCost: this.config.aiTools?.calculateCost
+            // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
+            request._mergedRouterConfig = mergedConfig;
+            applyOpenRouterInvokePolicy(mergedConfig, {
+                preferOpenRouter: this.preferOpenRouter,
+                openRouterApiKey: this.openRouterApiKey,
+                routingEnv: aiTools?.routingEnv,
+                resolution: request._modelResolution,
             });
-            // Create enhanced response
-            const enhancedResponse = {
-                content: response.content || '',
-                metadata: {
-                    aiRequestId: request.aiRequestId,
-                    identity: request.identity,
-                    latencyMs: Date.now() - startTime,
-                    tokens: tokensChat,
-                    taskTypeId,
-                    agentType: 'chat',
-                    ...(costCompletionChat.costStatus === 'priced'
-                        ? {
-                            costUsd: costCompletionChat.cost,
-                            ...(typeof metaChat.cost === 'number'
-                                ? { cost: metaChat.cost }
-                                : { cost: costCompletionChat.cost })
-                        }
-                        : {}),
-                    ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {}),
-                    ...(costCompletionChat.costBreakdown
-                        ? { costBreakdown: costCompletionChat.costBreakdown }
-                        : {})
-                }
-            };
-            // Track activity success if activity was started
-            if (activity) {
+            // 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);
+                this._autoRegisterDone = true;
+            }
+            const optimixerPrediction = await this.applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages);
+            // Start activity tracking if available
+            let activity = undefined;
+            if (this.activityManager) {
                 try {
-                    await this.activityManager.logSuccess(activity, {
-                        ...costCompletionChat,
-                        response: enhancedResponse,
-                        endTime: Date.now(),
-                        duration: Date.now() - startTime
-                    });
+                    activity = await this.activityManager.startActivity(request, startTime);
                 }
                 catch (activityError) {
                     // Log activity tracking error but don't fail the request
-                    this.logger.warn('Failed to track activity success', {
+                    this.logger.warn('Failed to start activity tracking', {
                         aiRequestId: request.aiRequestId,
                         error: activityError instanceof Error ? activityError.message : String(activityError)
                     });
                 }
             }
-            if (optimixerPrediction) {
-                await this.optimixerManager?.completePrediction(optimixerPrediction.requestId, buildOptimixerActualUsage(tokensChat, response, Date.now() - startTime));
+            try {
+                // Call router directly with merged config
+                const response = await this.router.invoke({
+                    request: {
+                        messages,
+                        config: mergedConfig,
+                        identity: request.identity
+                    },
+                    mode: 'sync'
+                });
+                const metaChat = response?.metadata || {};
+                const tokensChat = extractTokenUsageFromRouterResponse(response);
+                const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
+                    mergedConfig,
+                    calculator: aiTools?.calculator ?? null,
+                    calculateCost: this.config.aiTools?.calculateCost
+                });
+                // Create enhanced response
+                const enhancedResponse = {
+                    content: response.content || '',
+                    metadata: {
+                        aiRequestId: request.aiRequestId,
+                        identity: request.identity,
+                        latencyMs: Date.now() - startTime,
+                        tokens: tokensChat,
+                        taskTypeId,
+                        agentType: 'chat',
+                        ...(costCompletionChat.costStatus === 'priced'
+                            ? {
+                                costUsd: costCompletionChat.cost,
+                                ...(typeof metaChat.cost === 'number'
+                                    ? { cost: metaChat.cost }
+                                    : { cost: costCompletionChat.cost })
+                            }
+                            : {}),
+                        ...(costCompletionChat.costStatus ? { costStatus: costCompletionChat.costStatus } : {}),
+                        ...(costCompletionChat.costBreakdown
+                            ? { costBreakdown: costCompletionChat.costBreakdown }
+                            : {})
+                    }
+                };
+                // Track activity success if activity was started
+                if (activity) {
+                    try {
+                        await this.activityManager.logSuccess(activity, {
+                            ...costCompletionChat,
+                            response: enhancedResponse,
+                            endTime: Date.now(),
+                            duration: Date.now() - startTime
+                        });
+                    }
+                    catch (activityError) {
+                        // Log activity tracking error but don't fail the request
+                        this.logger.warn('Failed to track activity success', {
+                            aiRequestId: request.aiRequestId,
+                            error: activityError instanceof Error ? activityError.message : String(activityError)
+                        });
+                    }
+                }
+                if (optimixerPrediction) {
+                    await this.optimixerManager?.completePrediction(optimixerPrediction.requestId, buildOptimixerActualUsage(tokensChat, response, Date.now() - startTime));
+                }
+                warnIfSuccessfulInvokeReportsZeroUsageOrCost(this.logger, request.identity, {
+                    tokens: enhancedResponse.metadata.tokens,
+                    costUsd: enhancedResponse.metadata.costUsd,
+                    cost: enhancedResponse.metadata.cost
+                }, 'invokeChat');
+                return enhancedResponse;
             }
-            warnIfSuccessfulInvokeReportsZeroUsageOrCost(this.logger, request.identity, {
-                tokens: enhancedResponse.metadata.tokens,
-                costUsd: enhancedResponse.metadata.costUsd,
-                cost: enhancedResponse.metadata.cost
-            }, 'invokeChat');
-            return enhancedResponse;
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            if (err.message.includes(NO_PROVIDER_ERROR)) {
-                throw new Error(err.message + NO_PROVIDER_HINT);
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                if (err.message.includes(NO_PROVIDER_ERROR)) {
+                    throw new Error(err.message + NO_PROVIDER_HINT);
+                }
+                throw err;
             }
-            throw err;
-        }
+        });
     }
     /**
      * Invoke AI request (with structured output support)
      */
     async invoke(request) {
-        const startTime = Date.now();
         // Basic validation
         validateAIRequest(request);
         ensureGatewayRequestIdentity(request, undefined, this.logger);
         setGatewayLastJobId(resolveRuntimeJobId(request));
-        // Generate simple task type ID
-        const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
-        // Resolve instructions and build messages using proper components
-        let resolvedRequest = request;
-        let messages = [];
-        // Create parsedSnapshot to store parsed request data and messages
-        const parsedSnapshot = {};
-        // Use proper instruction resolution and message building
-        let builtMessages;
-        try {
-            builtMessages = await buildMessages(request, this.messageBuilderConfig, {
-                parsedSnapshot
-            });
-            messages = builtMessages.messages;
-            resolvedRequest = request;
-        }
-        catch (error) {
-            // If message building fails (e.g., prompt/instruction resolution error), log as bad request
-            const err = error instanceof Error ? error : new Error(String(error));
-            const endTime = Date.now();
-            const duration = endTime - startTime;
-            // Determine if this is a prompt/instruction resolution error
-            // If a key was provided but couldn't be resolved to content, it's a bad request
-            const errWithCode = err; // Type assertion for error with optional code property
-            const isResolutionError = err.name === 'InstructionNotFoundError' ||
-                err.name === 'InstructionBackendError' ||
-                err.name === 'TemplateResolutionError' ||
-                errWithCode.code === 'PROMPT_NOT_FOUND' ||
-                errWithCode.code === 'PROMPT_RESOLUTION_ERROR' ||
-                errWithCode.code === 'PROMPT_RENDERED_EMPTY' ||
-                errWithCode.code === 'TEMPLATE_RESOLUTION_ERROR' ||
-                errWithCode.code === 'TEMPLATE_VARIABLE_MISSING' ||
-                err.message.includes('Failed to resolve') ||
-                err.message.includes('Failed to render prompt template') ||
-                err.message.includes('not found') ||
-                err.message.includes('Instruction not found') ||
-                err.message.includes('Prompt not found');
-            if (isResolutionError && this.activityManager) {
-                // Log to bad requests collection
-                await this.activityManager.logBadRequest(request, err, {
-                    endTime,
-                    duration,
-                    error: err.message,
-                    errorType: errWithCode.code || 'MessageBuildError',
-                    diagnosticInfo: {
-                        errorCode: errWithCode.code,
-                        errorName: err.name,
-                        failureType: 'validation-failure',
-                        stage: 'message-building',
-                        prompt: request.prompt,
-                        instructions: typeof request.instructions === 'string' ? request.instructions.substring(0, 100) : '(object)'
-                    },
-                    failureType: 'validation-failure'
-                }, startTime);
-            }
-            const rejectMeta = buildInvokeRejectionMetadata({
-                request,
-                taskTypeId,
-                startTime,
-                gatewayAiRequestId: request.aiRequestId
-            });
-            attachGatewayInvokeRejectionMetadata(err, rejectMeta);
-            // Re-throw the error so it propagates to the caller
-            throw err;
-        }
-        // Store messages in parsedSnapshot for activity tracking
-        parsedSnapshot.messages = messages;
-        // parsed.instructions and parsed.prompt are set by buildMessages to the resolved/rendered content
-        // (after key resolution and Rendrix). Do not overwrite with raw request keys.
-        if (parsedSnapshot.context === undefined) {
-            parsedSnapshot.context = request.context;
-        }
-        // Attach parsedSnapshot to request for activity tracking
-        request._parsedRequest = parsedSnapshot;
-        // Merge config (modelConfig > request.config > gateway defaults)
-        const aiTools = await this.getAiTools();
-        const mergedConfig = await mergeConfig(request, this.config, this.logger, {
-            defaultModelConfig: this.defaultModelConfig,
-            catalog: aiTools?.catalog ?? null
-        });
-        request._mergedRouterConfig = mergedConfig;
-        logResolvedModelRouting(this.logger, request, mergedConfig);
-        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);
-            this._autoRegisterDone = true;
-        }
-        const optimixerPrediction = await this.applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages);
-        // Start activity tracking if available
-        let activity = undefined;
-        if (this.activityManager) {
+        return withGatewayLogContext(request.identity, async () => {
+            const startTime = Date.now();
+            // Generate simple task type ID
+            const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
+            // Resolve instructions and build messages using proper components
+            let resolvedRequest = request;
+            let messages = [];
+            // Create parsedSnapshot to store parsed request data and messages
+            const parsedSnapshot = {};
+            // Use proper instruction resolution and message building
+            let builtMessages;
             try {
-                activity = await this.activityManager.startActivity(request, startTime);
-            }
-            catch (activityError) {
-                // Log activity tracking error but don't fail the request
-                this.logger.warn('Failed to start activity tracking', {
-                    aiRequestId: request.aiRequestId,
-                    error: activityError instanceof Error ? activityError.message : String(activityError)
+                builtMessages = await buildMessages(request, this.messageBuilderConfig, {
+                    parsedSnapshot
                 });
+                messages = builtMessages.messages;
+                resolvedRequest = request;
             }
-        }
-        try {
-            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'
+            catch (error) {
+                // If message building fails (e.g., prompt/instruction resolution error), log as bad request
+                const err = error instanceof Error ? error : new Error(String(error));
+                const endTime = Date.now();
+                const duration = endTime - startTime;
+                // Determine if this is a prompt/instruction resolution error
+                // If a key was provided but couldn't be resolved to content, it's a bad request
+                const errWithCode = err; // Type assertion for error with optional code property
+                const isResolutionError = err.name === 'InstructionNotFoundError' ||
+                    err.name === 'InstructionBackendError' ||
+                    err.name === 'TemplateResolutionError' ||
+                    errWithCode.code === 'PROMPT_NOT_FOUND' ||
+                    errWithCode.code === 'PROMPT_RESOLUTION_ERROR' ||
+                    errWithCode.code === 'PROMPT_RENDERED_EMPTY' ||
+                    errWithCode.code === 'TEMPLATE_RESOLUTION_ERROR' ||
+                    errWithCode.code === 'TEMPLATE_VARIABLE_MISSING' ||
+                    err.message.includes('Failed to resolve') ||
+                    err.message.includes('Failed to render prompt template') ||
+                    err.message.includes('not found') ||
+                    err.message.includes('Instruction not found') ||
+                    err.message.includes('Prompt not found');
+                if (isResolutionError && this.activityManager) {
+                    // Log to bad requests collection
+                    await this.activityManager.logBadRequest(request, err, {
+                        endTime,
+                        duration,
+                        error: err.message,
+                        errorType: errWithCode.code || 'MessageBuildError',
+                        diagnosticInfo: {
+                            errorCode: errWithCode.code,
+                            errorName: err.name,
+                            failureType: 'validation-failure',
+                            stage: 'message-building',
+                            prompt: request.prompt,
+                            instructions: typeof request.instructions === 'string' ? request.instructions.substring(0, 100) : '(object)'
+                        },
+                        failureType: 'validation-failure'
+                    }, startTime);
+                }
+                const rejectMeta = buildInvokeRejectionMetadata({
+                    request,
+                    taskTypeId,
+                    startTime,
+                    gatewayAiRequestId: request.aiRequestId
                 });
+                attachGatewayInvokeRejectionMetadata(err, rejectMeta);
+                // Re-throw the error so it propagates to the caller
+                throw err;
             }
-            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 });
+            // Store messages in parsedSnapshot for activity tracking
+            parsedSnapshot.messages = messages;
+            // parsed.instructions and parsed.prompt are set by buildMessages to the resolved/rendered content
+            // (after key resolution and Rendrix). Do not overwrite with raw request keys.
+            if (parsedSnapshot.context === undefined) {
+                parsedSnapshot.context = request.context;
+            }
+            // Attach parsedSnapshot to request for activity tracking
+            request._parsedRequest = parsedSnapshot;
+            // Merge config (modelConfig > request.config > gateway defaults)
+            const aiTools = await this.getAiTools();
+            const mergedConfig = await mergeConfig(request, this.config, this.logger, {
+                defaultModelConfig: this.defaultModelConfig,
+                catalog: aiTools?.catalog ?? null,
+                routingEnv: aiTools?.routingEnv,
+            });
+            request._mergedRouterConfig = mergedConfig;
+            applyOpenRouterInvokePolicy(mergedConfig, {
+                preferOpenRouter: this.preferOpenRouter,
+                openRouterApiKey: this.openRouterApiKey,
+                routingEnv: aiTools?.routingEnv,
+                resolution: request._modelResolution,
+            });
+            logResolvedModelRouting(this.logger, request, mergedConfig);
+            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);
+                this._autoRegisterDone = true;
+            }
+            const optimixerPrediction = await this.applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages);
+            // Start activity tracking if available
+            let activity = undefined;
+            if (this.activityManager) {
+                try {
+                    activity = await this.activityManager.startActivity(request, startTime);
+                }
+                catch (activityError) {
+                    // Log activity tracking error but don't fail the request
+                    this.logger.warn('Failed to start activity tracking', {
+                        aiRequestId: request.aiRequestId,
+                        error: activityError instanceof Error ? activityError.message : String(activityError)
+                    });
                 }
-                const defaultTarget = this.config?.defaultTarget;
-                if (defaultTarget?.engine && defaultTarget?.model) {
-                    candidates.push({ provider: String(defaultTarget.engine), model: String(defaultTarget.model) });
+            }
+            try {
+                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'
+                    });
                 }
-                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) });
+                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 });
                     }
-                }
-                // 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
-                                }
+                    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) });
                             }
-                        }, (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: {
+                        }
+                    }
+                    // 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,
-                                        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;
+                                        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 attemptCostUsd = extractCostUsdFromRouterResponse(respAny);
+                                        if (typeof attemptCostUsd === 'number')
+                                            a.costUsd = attemptCostUsd;
+                                        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);
                                         }
                                     }
-                                    a.routing.requestIds = requestIds;
-                                    a.modelUsed =
-                                        meta?.modelUsed || meta?.model || respAny.model || candidate.model;
-                                    const attemptCostUsd = extractCostUsdFromRouterResponse(respAny);
-                                    if (typeof attemptCostUsd === 'number')
-                                        a.costUsd = attemptCostUsd;
-                                    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)) };
                                     }
                                 }
-                                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
+                            });
+                            response = result.response;
+                            lastError = undefined;
+                            break; // success => stop fallback chain
+                        }
+                        catch (err) {
+                            lastError = err instanceof Error ? err : new Error(String(err));
+                            continue;
+                        }
                     }
-                    catch (err) {
-                        lastError = err instanceof Error ? err : new Error(String(err));
-                        continue;
+                    if (!response) {
+                        const fallbackAttempts = buildGatewayFallbackAttemptsFromTrace(traceAttempts, deduped, lastError);
+                        const providersTried = [...new Set(deduped.map((c) => c.provider))];
+                        this.logger.error('Trace fallback chain exhausted', withActivityIdentity(request.identity, {
+                            providersTried,
+                            candidates: deduped,
+                            fallbackAttempts,
+                            debugKind: gatewayLogDebug.anomaly
+                        }));
+                        const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
+                        exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
+                        if (lastError) {
+                            exhausted.cause = lastError;
+                        }
+                        throw exhausted;
                     }
-                }
-                if (!response) {
-                    const fallbackAttempts = buildGatewayFallbackAttemptsFromTrace(traceAttempts, deduped, lastError);
-                    const providersTried = [...new Set(deduped.map((c) => c.provider))];
-                    this.logger.error('Trace fallback chain exhausted', withActivityIdentity(request.identity, {
-                        providersTried,
-                        candidates: deduped,
-                        fallbackAttempts,
-                        debugKind: gatewayLogDebug.anomaly
-                    }));
-                    const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
-                    exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
-                    if (lastError) {
-                        exhausted.cause = lastError;
+                    // 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;
+                        }
                     }
-                    throw exhausted;
+                    const lastOk = [...traceAttempts].reverse().find(a => a.ok);
+                    providerCallLatencyMs = lastOk?.timing?.durationMs;
                 }
-                // 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;
-                    }
+                // Contract output processing removed - expectedSchema no longer supported
+                // Create enhanced response - extract content properly from router response
+                const routerResponse = response;
+                // Extract content from router response - router returns outputText, not content
+                let content = routerResponse.content || routerResponse.outputText || '';
+                // If content is still empty, try to extract from ai-activities metadata
+                if (!content && routerResponse.metadata?.['ai-activities-response']?.outputText) {
+                    content = routerResponse.metadata['ai-activities-response'].outputText;
                 }
-                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;
-            // Extract content from router response - router returns outputText, not content
-            let content = routerResponse.content || routerResponse.outputText || '';
-            // If content is still empty, try to extract from ai-activities metadata
-            if (!content && routerResponse.metadata?.['ai-activities-response']?.outputText) {
-                content = routerResponse.metadata['ai-activities-response'].outputText;
-            }
-            // Parse content using available parsers (flex-md, content normalizer, etc.)
-            let parsedContent = undefined;
-            let contentType = undefined;
-            let parsingMethod = undefined;
-            // Actually use flex-md parsing - extract structured data from markdown
-            try {
-                this.logger.debug('Attempting flex-md extraction', withActivityIdentity(request.identity, {
-                    contentLength: content.length,
-                    hasInstructions: !!resolvedRequest.instructions,
-                    debugKind: gatewayLogDebug.intent
-                }));
-                // Let flex-md extract structured data from the response content
-                const extractionResult = await extractJsonFromFlexMd(content, this.logger);
-                this.logger.debug('Flex-md extraction result', withActivityIdentity(request.identity, {
-                    hasResult: !!extractionResult,
-                    hasJson: !!(extractionResult && extractionResult.json),
-                    method: extractionResult?.method,
-                    jsonType: extractionResult?.json ? typeof extractionResult.json : 'none',
-                    debugKind: gatewayLogDebug.state
-                }));
-                if (extractionResult && extractionResult.json) {
-                    // Successfully extracted structured data
-                    parsedContent = extractionResult.json;
-                    this.logger.info('Flex-md extraction successful - parsed into structured object', withActivityIdentity(request.identity, {
-                        method: extractionResult.method,
-                        extractedKeys: Object.keys(extractionResult.json),
-                        debugKind: gatewayLogDebug.event
+                // Parse content using available parsers (flex-md, content normalizer, etc.)
+                let parsedContent = undefined;
+                let contentType = undefined;
+                let parsingMethod = undefined;
+                // Actually use flex-md parsing - extract structured data from markdown
+                try {
+                    this.logger.debug('Attempting flex-md extraction', withActivityIdentity(request.identity, {
+                        contentLength: content.length,
+                        hasInstructions: !!resolvedRequest.instructions,
+                        debugKind: gatewayLogDebug.intent
+                    }));
+                    // Let flex-md extract structured data from the response content
+                    const extractionResult = await extractJsonFromFlexMd(content, this.logger);
+                    this.logger.debug('Flex-md extraction result', withActivityIdentity(request.identity, {
+                        hasResult: !!extractionResult,
+                        hasJson: !!(extractionResult && extractionResult.json),
+                        method: extractionResult?.method,
+                        jsonType: extractionResult?.json ? typeof extractionResult.json : 'none',
+                        debugKind: gatewayLogDebug.state
                     }));
+                    if (extractionResult && extractionResult.json) {
+                        // Successfully extracted structured data
+                        parsedContent = extractionResult.json;
+                        this.logger.info('Flex-md extraction successful - parsed into structured object', withActivityIdentity(request.identity, {
+                            method: extractionResult.method,
+                            extractedKeys: Object.keys(extractionResult.json),
+                            debugKind: gatewayLogDebug.event
+                        }));
+                    }
+                    else {
+                        // Extraction failed, fall back to raw text wrapper
+                        this.logger.warn('Flex-md extraction failed - no structured data extracted', withActivityIdentity(request.identity, {
+                            hasResult: !!extractionResult,
+                            method: extractionResult?.method || 'none',
+                            debugKind: gatewayLogDebug.anomaly
+                        }));
+                        parsedContent = { rawText: content };
+                    }
                 }
-                else {
+                catch (extractionError) {
                     // Extraction failed, fall back to raw text wrapper
-                    this.logger.warn('Flex-md extraction failed - no structured data extracted', withActivityIdentity(request.identity, {
-                        hasResult: !!extractionResult,
-                        method: extractionResult?.method || 'none',
+                    const errorMessage = extractionError instanceof Error ? extractionError.message : String(extractionError);
+                    this.logger.warn('Flex-md extraction failed - flex-md library compatibility issue', withActivityIdentity(request.identity, {
+                        error: errorMessage,
+                        issue: 'flex-md uses require() in ES module context - needs fixing in flex-md-loader.ts',
+                        fallback: 'using rawText wrapper',
                         debugKind: gatewayLogDebug.anomaly
                     }));
                     parsedContent = { rawText: content };
                 }
-            }
-            catch (extractionError) {
-                // Extraction failed, fall back to raw text wrapper
-                const errorMessage = extractionError instanceof Error ? extractionError.message : String(extractionError);
-                this.logger.warn('Flex-md extraction failed - flex-md library compatibility issue', withActivityIdentity(request.identity, {
-                    error: errorMessage,
-                    issue: 'flex-md uses require() in ES module context - needs fixing in flex-md-loader.ts',
-                    fallback: 'using rawText wrapper',
-                    debugKind: gatewayLogDebug.anomaly
-                }));
-                parsedContent = { rawText: content };
-            }
-            contentType = 'structured';
-            parsingMethod = 'flex-md';
-            const outputContractKeys = resolveOutputContractFieldKeys(request);
-            parsedContent = await enrichParsedContentForOutputContract(parsedContent, content, outputContractKeys, this.logger);
-            let tokens = extractTokenUsageFromRouterResponse(routerResponse);
-            if (!(tokens.prompt || tokens.completion || tokens.total)) {
-                const alt = routerResponse?.rawResponse ?? routerResponse?.raw;
-                if (alt != null && typeof alt === 'object' && alt !== routerResponse) {
-                    const second = extractTokenUsageFromRouterResponse(alt);
-                    if (second.prompt || second.completion || second.total)
-                        tokens = second;
+                contentType = 'structured';
+                parsingMethod = 'flex-md';
+                const outputContractKeys = resolveOutputContractFieldKeys(request);
+                parsedContent = await enrichParsedContentForOutputContract(parsedContent, content, outputContractKeys, this.logger);
+                let tokens = extractTokenUsageFromRouterResponse(routerResponse);
+                if (!(tokens.prompt || tokens.completion || tokens.total)) {
+                    const alt = routerResponse?.rawResponse ?? routerResponse?.raw;
+                    if (alt != null && typeof alt === 'object' && alt !== routerResponse) {
+                        const second = extractTokenUsageFromRouterResponse(alt);
+                        if (second.prompt || second.completion || second.total)
+                            tokens = second;
+                    }
                 }
-            }
-            let costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
-                mergedConfig,
-                calculator: aiTools?.calculator ?? null,
-                calculateCost: this.config.aiTools?.calculateCost
-            });
-            if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
-                costCompletion = { ...costCompletion, costStatus: 'unpriced' };
-            }
-            const routerMetaForCost = routerResponse?.metadata || {};
-            const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
-            const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
-            const traceMergedRouterSnapshot = traceEnabled ? pickTraceMergedRouterConfig(mergedConfig) : undefined;
-            if (traceEnabled && traceAttempts) {
-                await enrichTraceAttemptsWithBilling(traceAttempts, costCompletion, {
+                let costCompletion = await resolveCostCompletionWithAiTools(routerResponse, tokens, {
                     mergedConfig,
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-            }
-            const traceUsageSummary = traceEnabled
-                ? buildTraceUsageSummary(tokens, costCompletion, routingMetadataSlice.maxTokensRequested)
-                : undefined;
-            const enhancedResponse = {
-                content: content,
-                parsedContent: parsedContent,
-                metadata: {
-                    aiRequestId: request.aiRequestId,
-                    identity: request.identity,
-                    latencyMs: traceEnabled && typeof providerCallLatencyMs === 'number' ? providerCallLatencyMs : (Date.now() - startTime),
-                    tokens: tokens,
-                    taskTypeId,
-                    agentType: 'ai',
-                    contentType,
-                    parsingMethod,
-                    ...routingMetadataSlice,
-                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
-                    ...(costCompletion.costStatus === 'priced'
-                        ? {
-                            costUsd: costCompletion.cost,
-                            ...(typeof routerMetaForCost.cost === 'number'
-                                ? { cost: routerMetaForCost.cost }
-                                : { cost: costCompletion.cost })
-                        }
-                        : {}),
-                    ...(costCompletion.costStatus ? { costStatus: costCompletion.costStatus } : {}),
-                    ...(costCompletion.costBreakdown ? { costBreakdown: costCompletion.costBreakdown } : {}),
-                    ...(traceEnabled
-                        ? {
-                            requestIds: traceRequestIds,
-                            retryCount: traceRetryCount,
-                            fallbackCount: traceFallbackCount,
-                            attempts: traceAttempts,
-                            ...(traceUsageSummary !== undefined ? { usage: traceUsageSummary } : {}),
-                            ...(traceMergedRouterSnapshot !== undefined
-                                ? { mergedRouterConfig: traceMergedRouterSnapshot }
-                                : {})
-                        }
-                        : {})
+                if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
+                    costCompletion = { ...costCompletion, costStatus: 'unpriced' };
                 }
-            };
-            // Track activity success if activity was started
-            if (activity) {
-                try {
-                    const diag = request.diagnostics;
-                    const includeFullProviderBlob = diag?.includeFullProviderResponseInActivity !== false;
-                    const maxFullChars = typeof diag?.activityFullResponseMaxChars === 'number' && diag.activityFullResponseMaxChars > 0
-                        ? diag.activityFullResponseMaxChars
-                        : DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS;
-                    const rawFull = routerResponse.rawResponse || routerResponse;
-                    const fullResponseForActivity = includeFullProviderBlob
-                        ? capActivityFullResponsePayload(rawFull, maxFullChars)
-                        : undefined;
-                    // Create activity response with proper structure for ActivityTracker
-                    const activityResponse = {
-                        content: {
-                            rawContent: content, // Store the actual response content as rawContent
-                            ...(fullResponseForActivity !== undefined ? { fullResponse: fullResponseForActivity } : {})
-                        },
-                        parsed: parsedContent, // Include parsed content in activity record
-                        metadata: enhancedResponse.metadata,
-                        status: 'success',
-                        error: null,
-                        usage: tokens
-                    };
-                    await this.activityManager.logSuccess(activity, {
-                        ...costCompletion,
-                        response: activityResponse,
-                        endTime: Date.now(),
-                        duration: Date.now() - startTime
+                const routerMetaForCost = routerResponse?.metadata || {};
+                const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+                const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);
+                const traceMergedRouterSnapshot = traceEnabled ? pickTraceMergedRouterConfig(mergedConfig) : undefined;
+                if (traceEnabled && traceAttempts) {
+                    await enrichTraceAttemptsWithBilling(traceAttempts, costCompletion, {
+                        mergedConfig,
+                        calculator: aiTools?.calculator ?? null,
+                        calculateCost: this.config.aiTools?.calculateCost
                     });
                 }
-                catch (activityError) {
-                    // Log activity tracking error but don't fail the request
-                    this.logger.warn('Failed to track activity success', {
+                const traceUsageSummary = traceEnabled
+                    ? buildTraceUsageSummary(tokens, costCompletion, routingMetadataSlice.maxTokensRequested)
+                    : undefined;
+                const enhancedResponse = {
+                    content: content,
+                    parsedContent: parsedContent,
+                    metadata: {
                         aiRequestId: request.aiRequestId,
-                        error: activityError instanceof Error ? activityError.message : String(activityError)
-                    });
+                        identity: request.identity,
+                        latencyMs: traceEnabled && typeof providerCallLatencyMs === 'number' ? providerCallLatencyMs : (Date.now() - startTime),
+                        tokens: tokens,
+                        taskTypeId,
+                        agentType: 'ai',
+                        contentType,
+                        parsingMethod,
+                        ...routingMetadataSlice,
+                        ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
+                        ...(costCompletion.costStatus === 'priced'
+                            ? {
+                                costUsd: costCompletion.cost,
+                                ...(typeof routerMetaForCost.cost === 'number'
+                                    ? { cost: routerMetaForCost.cost }
+                                    : { cost: costCompletion.cost })
+                            }
+                            : {}),
+                        ...(costCompletion.costStatus ? { costStatus: costCompletion.costStatus } : {}),
+                        ...(costCompletion.costBreakdown ? { costBreakdown: costCompletion.costBreakdown } : {}),
+                        ...(traceEnabled
+                            ? {
+                                requestIds: traceRequestIds,
+                                retryCount: traceRetryCount,
+                                fallbackCount: traceFallbackCount,
+                                attempts: traceAttempts,
+                                ...(traceUsageSummary !== undefined ? { usage: traceUsageSummary } : {}),
+                                ...(traceMergedRouterSnapshot !== undefined
+                                    ? { mergedRouterConfig: traceMergedRouterSnapshot }
+                                    : {})
+                            }
+                            : {})
+                    }
+                };
+                // Track activity success if activity was started
+                if (activity) {
+                    try {
+                        const diag = request.diagnostics;
+                        const includeFullProviderBlob = diag?.includeFullProviderResponseInActivity !== false;
+                        const maxFullChars = typeof diag?.activityFullResponseMaxChars === 'number' && diag.activityFullResponseMaxChars > 0
+                            ? diag.activityFullResponseMaxChars
+                            : DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS;
+                        const rawFull = routerResponse.rawResponse || routerResponse;
+                        const fullResponseForActivity = includeFullProviderBlob
+                            ? capActivityFullResponsePayload(rawFull, maxFullChars)
+                            : undefined;
+                        // Create activity response with proper structure for ActivityTracker
+                        const activityResponse = {
+                            content: {
+                                rawContent: content, // Store the actual response content as rawContent
+                                ...(fullResponseForActivity !== undefined ? { fullResponse: fullResponseForActivity } : {})
+                            },
+                            parsed: parsedContent, // Include parsed content in activity record
+                            metadata: enhancedResponse.metadata,
+                            status: 'success',
+                            error: null,
+                            usage: tokens
+                        };
+                        await this.activityManager.logSuccess(activity, {
+                            ...costCompletion,
+                            response: activityResponse,
+                            endTime: Date.now(),
+                            duration: Date.now() - startTime
+                        });
+                    }
+                    catch (activityError) {
+                        // Log activity tracking error but don't fail the request
+                        this.logger.warn('Failed to track activity success', {
+                            aiRequestId: request.aiRequestId,
+                            error: activityError instanceof Error ? activityError.message : String(activityError)
+                        });
+                    }
                 }
+                if (optimixerPrediction) {
+                    await this.optimixerManager?.completePrediction(optimixerPrediction.requestId, buildOptimixerActualUsage(tokens, routerResponse, Date.now() - startTime));
+                }
+                warnIfSuccessfulInvokeReportsZeroUsageOrCost(this.logger, request.identity, {
+                    tokens: enhancedResponse.metadata.tokens,
+                    costUsd: enhancedResponse.metadata.costUsd,
+                    cost: enhancedResponse.metadata.cost
+                }, 'invoke');
+                this.logger.debug('gateway: enhancedResponse', withActivityIdentity(request.identity, {
+                    latencyMs: enhancedResponse.metadata?.latencyMs,
+                    contentType: enhancedResponse.metadata?.contentType,
+                    debugKind: gatewayLogDebug.state
+                }));
+                return enhancedResponse;
             }
-            if (optimixerPrediction) {
-                await this.optimixerManager?.completePrediction(optimixerPrediction.requestId, buildOptimixerActualUsage(tokens, routerResponse, Date.now() - startTime));
-            }
-            warnIfSuccessfulInvokeReportsZeroUsageOrCost(this.logger, request.identity, {
-                tokens: enhancedResponse.metadata.tokens,
-                costUsd: enhancedResponse.metadata.costUsd,
-                cost: enhancedResponse.metadata.cost
-            }, 'invoke');
-            this.logger.debug('gateway: enhancedResponse', withActivityIdentity(request.identity, {
-                latencyMs: enhancedResponse.metadata?.latencyMs,
-                contentType: enhancedResponse.metadata?.contentType,
-                debugKind: gatewayLogDebug.state
-            }));
-            return enhancedResponse;
-        }
-        catch (error) {
-            const err = error instanceof Error ? error : new Error(String(error));
-            const partial = tryExtractRouterLikePayloadFromErrorChain(err);
-            const rejectMeta = buildInvokeRejectionMetadata({
-                request,
-                taskTypeId,
-                startTime,
-                mergedConfig,
-                partialRouterPayload: partial,
-                gatewayAiRequestId: request.aiRequestId,
-                error: err
-            });
-            attachGatewayInvokeRejectionMetadata(err, rejectMeta);
-            if (err.message.includes(NO_PROVIDER_ERROR)) {
-                const wrapped = new Error(err.message + NO_PROVIDER_HINT);
-                wrapped.cause = err;
-                attachGatewayInvokeRejectionMetadata(wrapped, rejectMeta);
-                throw wrapped;
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                const partial = tryExtractRouterLikePayloadFromErrorChain(err);
+                const rejectMeta = buildInvokeRejectionMetadata({
+                    request,
+                    taskTypeId,
+                    startTime,
+                    mergedConfig,
+                    partialRouterPayload: partial,
+                    gatewayAiRequestId: request.aiRequestId,
+                    error: err
+                });
+                attachGatewayInvokeRejectionMetadata(err, rejectMeta);
+                if (err.message.includes(NO_PROVIDER_ERROR)) {
+                    const wrapped = new Error(err.message + NO_PROVIDER_HINT);
+                    wrapped.cause = err;
+                    attachGatewayInvokeRejectionMetadata(wrapped, rejectMeta);
+                    throw wrapped;
+                }
+                throw err;
             }
-            throw err;
-        }
+        });
     }
     async applyAdaptiveMaxTokensIfEnabled(request, mergedConfig, messages) {
         if (!this.optimixerManager?.isEnabled() || isMaxTokensExplicitlySet(request, this.config)) {