@x12i/ai-gateway 10.3.1 → 10.4.1

package/dist/openrouter-runtime-adapter/validate-server-tools.js

@@ -0,0 +1,151 @@
+import { GatewayValidationError, ProviderConfigError, } from '../instruction-errors.js';
+const TOOL_KEYS = [
+    'webSearch',
+    'webFetch',
+    'datetime',
+    'imageGeneration',
+    'applyPatch',
+    'fusion',
+    'advisor',
+    'subagent',
+];
+function getToolMode(serverTools, key) {
+    const tool = serverTools?.[key];
+    if (!tool)
+        return undefined;
+    if (Array.isArray(tool)) {
+        return tool.some((t) => t.mode === 'required')
+            ? 'required'
+            : tool.some((t) => t.mode === 'allowed')
+                ? 'allowed'
+                : 'disabled';
+    }
+    return tool.mode;
+}
+export function hasAnyServerToolMode(serverTools, mode) {
+    if (!serverTools)
+        return false;
+    for (const key of TOOL_KEYS) {
+        const m = getToolMode(serverTools, key);
+        if (m === mode)
+            return true;
+    }
+    return false;
+}
+export function hasAnyActiveServerTool(serverTools) {
+    if (!serverTools)
+        return false;
+    for (const key of TOOL_KEYS) {
+        const m = getToolMode(serverTools, key);
+        if (m === 'allowed' || m === 'required')
+            return true;
+    }
+    return false;
+}
+export function hasRequiredServerTool(serverTools) {
+    return hasAnyServerToolMode(serverTools, 'required');
+}
+function resolveEffectiveApiMode(openrouter, serverTools) {
+    if (openrouter?.apiMode)
+        return openrouter.apiMode;
+    const applyPatch = serverTools?.applyPatch;
+    if (applyPatch && applyPatch.mode !== 'disabled')
+        return 'auto';
+    return 'auto';
+}
+export function validateApplyPatchConfig(serverTools, openrouter) {
+    const applyPatch = serverTools?.applyPatch;
+    if (!applyPatch || applyPatch.mode === 'disabled')
+        return;
+    if (applyPatch.behavior === 'apply_with_callback') {
+        throw new GatewayValidationError('PATCH_APPLIER_REQUIRED', 'applyPatch behavior apply_with_callback is not supported by ai-gateway; use return_only');
+    }
+    const apiMode = resolveEffectiveApiMode(openrouter, serverTools);
+    if (apiMode === 'chat') {
+        throw new GatewayValidationError('APPLY_PATCH_REQUIRES_RESPONSES_API', 'applyPatch requires openrouter.apiMode = "responses" or auto mode resolving to responses');
+    }
+}
+export function applyPostRoutingServerToolsPolicy(input) {
+    const warnings = [];
+    const { serverTools, openrouter, openRouterApiKey } = input;
+    let provider = input.provider?.toLowerCase();
+    if (!hasAnyActiveServerTool(serverTools)) {
+        return { serverTools, warnings, forceOpenRouter: false };
+    }
+    validateApplyPatchConfig(serverTools, openrouter);
+    if (hasRequiredServerTool(serverTools)) {
+        if (!openRouterApiKey) {
+            throw new ProviderConfigError('OPENROUTER_SERVER_TOOL_REQUIRES_KEY', 'Required OpenRouter server tools need OPENROUTER_API_KEY or GatewayConfig.openrouter.apiKey');
+        }
+        if (provider !== 'openrouter') {
+            provider = 'openrouter';
+            return { serverTools, warnings, forceOpenRouter: true };
+        }
+        return { serverTools, warnings, forceOpenRouter: false };
+    }
+    if (provider !== 'openrouter') {
+        warnings.push({
+            code: 'SERVER_TOOLS_IGNORED_FOR_NON_OPENROUTER_PROVIDER',
+            message: 'OpenRouter server tools were requested but the final provider is not openrouter; tools were stripped',
+        });
+        return { serverTools: undefined, warnings, forceOpenRouter: false };
+    }
+    return { serverTools, warnings, forceOpenRouter: false };
+}
+export function applyOnlineVariantMigration(model, serverTools) {
+    if (!model.endsWith(':online')) {
+        return { model, serverTools };
+    }
+    const stripped = model.slice(0, -':online'.length);
+    const merged = { ...(serverTools ?? {}) };
+    if (!merged.webSearch) {
+        merged.webSearch = { mode: 'allowed' };
+    }
+    return {
+        model: stripped,
+        serverTools: merged,
+        warning: {
+            code: 'OPENROUTER_ONLINE_VARIANT_DEPRECATED',
+            message: `Model suffix :online is deprecated; stripped to "${stripped}" and enabled webSearch.mode=allowed`,
+        },
+    };
+}
+export function mergeServerToolsConfig(...layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        for (const key of TOOL_KEYS) {
+            const val = layer[key];
+            if (val !== undefined) {
+                out[key] = val;
+            }
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+export function mergeOpenRouterConfig(...layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        if (layer.apiMode !== undefined)
+            out.apiMode = layer.apiMode;
+        if (layer.includeRawInTrace !== undefined)
+            out.includeRawInTrace = layer.includeRawInTrace;
+        if (layer.rawOverrides !== undefined) {
+            out.rawOverrides = { ...(out.rawOverrides ?? {}), ...layer.rawOverrides };
+        }
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Default applyPatch behavior when not specified. */
+export function normalizeApplyPatchDefaults(serverTools) {
+    if (!serverTools?.applyPatch)
+        return serverTools;
+    const applyPatch = {
+        behavior: 'return_only',
+        ...serverTools.applyPatch,
+    };
+    return { ...serverTools, applyPatch };
+}

package/dist/types.d.ts

@@ -51,6 +51,202 @@ export type GatewayTraceRequestIds = {
     /** Allow additional stable ids without breaking contract. */
     [key: string]: string | undefined;
 };
+export type GatewayServerToolMode = 'disabled' | 'allowed' | 'required';
+export type GatewayNestedServerTool = {
+    type: 'openrouter:web_search';
+    parameters?: Record<string, unknown>;
+} | {
+    type: 'openrouter:web_fetch';
+    parameters?: Record<string, unknown>;
+} | {
+    type: 'openrouter:datetime';
+    parameters?: Record<string, unknown>;
+} | {
+    type: 'openrouter:image_generation';
+    parameters?: Record<string, unknown>;
+};
+export interface GatewayWebSearchToolConfig {
+    mode: GatewayServerToolMode;
+    engine?: 'auto' | 'native' | 'exa' | 'firecrawl' | 'parallel' | 'perplexity';
+    maxResults?: number;
+    maxTotalResults?: number;
+    searchContextSize?: 'low' | 'medium' | 'high';
+    maxCharacters?: number;
+    allowedDomains?: string[];
+    excludedDomains?: string[];
+    userLocation?: {
+        type: 'approximate';
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+    };
+    requireCitations?: boolean;
+    onFailure?: 'fail' | 'warn' | 'continue';
+}
+export interface GatewayWebFetchToolConfig {
+    mode: GatewayServerToolMode;
+    engine?: 'auto' | 'native' | 'exa' | 'openrouter' | 'firecrawl' | 'parallel';
+    maxUses?: number;
+    maxContentTokens?: number;
+    allowedDomains?: string[];
+    blockedDomains?: string[];
+    onFailure?: 'fail' | 'warn' | 'continue';
+}
+export interface GatewayDatetimeToolConfig {
+    mode: GatewayServerToolMode;
+    timezone?: string;
+}
+export interface GatewayImageGenerationToolConfig {
+    mode: GatewayServerToolMode;
+    model?: string;
+    quality?: 'low' | 'medium' | 'high' | string;
+    size?: string;
+    aspectRatio?: string;
+    background?: string;
+    outputFormat?: 'png' | 'jpeg' | 'webp' | string;
+    outputCompression?: number;
+    moderation?: string;
+}
+export interface GatewayApplyPatchToolConfig {
+    mode: GatewayServerToolMode;
+    behavior?: 'return_only' | 'apply_with_callback';
+    allowCreate?: boolean;
+    allowUpdate?: boolean;
+    allowDelete?: boolean;
+    workspaceRoot?: string;
+}
+export interface GatewayFusionToolConfig {
+    mode: GatewayServerToolMode;
+    analysisModels?: string[];
+    judgeModel?: string;
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    temperature?: number;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+    };
+}
+export interface GatewayAdvisorToolConfig {
+    mode: GatewayServerToolMode;
+    name?: string;
+    model?: string;
+    instructions?: string;
+    tools?: GatewayNestedServerTool[];
+    forwardTranscript?: boolean;
+    stream?: boolean;
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    temperature?: number;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+    };
+}
+export interface GatewaySubagentToolConfig {
+    mode: GatewayServerToolMode;
+    model?: string;
+    instructions?: string;
+    tools?: GatewayNestedServerTool[];
+    maxToolCalls?: number;
+    maxCompletionTokens?: number;
+    temperature?: number;
+    reasoning?: {
+        effort?: 'low' | 'medium' | 'high';
+        maxTokens?: number;
+    };
+}
+export interface GatewayServerToolsConfig {
+    webSearch?: GatewayWebSearchToolConfig;
+    webFetch?: GatewayWebFetchToolConfig;
+    datetime?: GatewayDatetimeToolConfig;
+    imageGeneration?: GatewayImageGenerationToolConfig;
+    applyPatch?: GatewayApplyPatchToolConfig;
+    fusion?: GatewayFusionToolConfig;
+    advisor?: GatewayAdvisorToolConfig | GatewayAdvisorToolConfig[];
+    subagent?: GatewaySubagentToolConfig;
+}
+export interface GatewayOpenRouterConfig {
+    apiMode?: 'chat' | 'responses' | 'auto';
+    rawOverrides?: Record<string, unknown>;
+    includeRawInTrace?: boolean;
+}
+export interface GatewayOpenRouterRuntimeConfig {
+    enabled?: boolean;
+    apiMode?: 'chat' | 'responses' | 'auto';
+    includeRawInTrace?: boolean;
+}
+export interface GatewayServerToolUsage {
+    requested: boolean;
+    required: boolean;
+    used: boolean;
+    callCount?: number;
+    policyViolation?: string;
+}
+export interface GatewayServerToolUsageMap {
+    webSearch?: GatewayServerToolUsage;
+    webFetch?: GatewayServerToolUsage;
+    datetime?: GatewayServerToolUsage;
+    imageGeneration?: GatewayServerToolUsage;
+    applyPatch?: GatewayServerToolUsage;
+    fusion?: GatewayServerToolUsage;
+    advisor?: GatewayServerToolUsage;
+    subagent?: GatewayServerToolUsage;
+}
+export interface GatewayCitation {
+    type: 'url';
+    url: string;
+    title?: string;
+    excerpt?: string;
+    startIndex?: number;
+    endIndex?: number;
+    sourceProvider: 'openrouter';
+}
+export interface GatewayGeneratedImage {
+    imageUrl: string;
+    status: 'ok' | 'error';
+    error?: string;
+    raw?: unknown;
+}
+export interface GatewayPatchProposal {
+    callId: string;
+    status: 'completed' | 'failed';
+    operation: {
+        type: 'create_file';
+        path: string;
+        diff: string;
+    } | {
+        type: 'update_file';
+        path: string;
+        diff: string;
+    } | {
+        type: 'delete_file';
+        path: string;
+    };
+    raw?: unknown;
+}
+export interface GatewayWarning {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface GatewayPolicyViolation {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export interface GatewayOpenRouterRuntimeMetadata {
+    apiMode: 'chat' | 'responses';
+    warnings: GatewayWarning[];
+    policyViolations: GatewayPolicyViolation[];
+    requestIds?: string[];
+    serverToolsRequested?: GatewayServerToolUsageMap;
+    serverToolsUsed?: GatewayServerToolUsageMap;
+    citations?: GatewayCitation[];
+    generatedImages?: GatewayGeneratedImage[];
+    patchProposals?: GatewayPatchProposal[];
+}
 export type GatewayTraceAttempt = {
     timing: {
         startedAt: number;
@@ -95,6 +291,13 @@ export type GatewayTraceAttempt = {
      * The exact shape is intentionally loose to avoid locking downstream to provider schemas.
      */
     rawProviderPayload?: unknown;
+    openrouterRuntime?: {
+        apiMode?: 'chat' | 'responses';
+        serverTools?: GatewayServerToolUsageMap;
+        citationCount?: number;
+        generatedImageCount?: number;
+        patchProposalCount?: number;
+    };
 };
 /**
  * Allowlisted merged router/generation config returned in {@link EnhancedLLMResponse.metadata}
@@ -115,6 +318,8 @@ export type GatewayTraceUsageSummary = {
     cost?: number;
     costStatus?: 'priced' | 'unpriced';
     costBreakdown?: GatewayTraceAttempt['costBreakdown'];
+    serverTools?: GatewayServerToolUsageMap;
+    citations?: GatewayCitation[];
 };
 export type GatewayTraceMergedConfig = Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP' | 'frequencyPenalty' | 'presencePenalty' | 'stop'>>;
 /**
@@ -316,11 +521,21 @@ export interface ModelConfig {
      * Generation stops when any stop sequence is encountered
      */
     stop?: string[];
+    /**
+     * OpenRouter-only server tools. Ignored unless final provider is openrouter.
+     */
+    serverTools?: GatewayServerToolsConfig;
+    /**
+     * OpenRouter-specific execution controls.
+     */
+    openrouter?: GatewayOpenRouterConfig;
     /**
      * Additional provider-specific parameters
      */
     [key: string]: any;
 }
+/** Alias for {@link ModelConfig} in gateway documentation. */
+export type GatewayModelConfig = ModelConfig;
 export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'logger'> {
     /**
      * Default target (engine + model) for routing
@@ -397,6 +612,15 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     openRouter?: {
         prefer?: boolean;
     };
+    /**
+     * Default OpenRouter server tool policy merged into every invoke (lowest priority).
+     */
+    defaultServerTools?: GatewayServerToolsConfig;
+    /**
+     * OpenRouter runtime integration defaults.
+     * @default `{ enabled: true, apiMode: 'auto', includeRawInTrace: false }`
+     */
+    openrouterRuntime?: GatewayOpenRouterRuntimeConfig;
     /**
      * Operational mode override (`process.env.mode` / `MODE` when omitted; default `debug`).
      * Downstream hosts (ai-skills, ai-tasks, graph-engine) should expose this to their clients.
@@ -1035,6 +1259,16 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Reflects gateway merge order: modelConfig / request.config / defaults.
          */
         effectiveModelConfig?: Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>>;
+        /** OpenRouter server tool usage summary (additive). */
+        serverTools?: GatewayServerToolUsageMap;
+        /** Citations extracted by OpenRouter runtime (additive). */
+        citations?: GatewayCitation[];
+        /** Generated image metadata from OpenRouter runtime (additive). */
+        generatedImages?: GatewayGeneratedImage[];
+        /** Patch proposals from OpenRouter runtime — never applied by the gateway (additive). */
+        patchProposals?: GatewayPatchProposal[];
+        /** OpenRouter runtime execution metadata (additive). */
+        openrouterRuntime?: GatewayOpenRouterRuntimeMetadata;
         /**
          * Stable request/correlation identifiers across gateway/router/provider layers.
          * Only populated when diagnostics trace mode is enabled.

package/dist-cjs/activity-manager.cjs

@@ -230,6 +230,39 @@ function pickActivixCompletionRoutingMetadata(response) {
             if (m.effectiveModelConfig != null && typeof m.effectiveModelConfig === 'object') {
                 out.effectiveModelConfig = m.effectiveModelConfig;
             }
+            const citations = m.citations;
+            if (Array.isArray(citations) && citations.length) {
+                out.citations = citations
+                    .filter((c) => c != null && typeof c === 'object')
+                    .map((c) => {
+                    const row = c;
+                    return {
+                        ...(typeof row.url === 'string' ? { url: row.url } : {}),
+                        ...(typeof row.title === 'string' ? { title: row.title } : {}),
+                    };
+                });
+                out.citationCount = citations.length;
+            }
+            const serverTools = m.serverTools;
+            const generatedImages = m.generatedImages;
+            const patchProposals = m.patchProposals;
+            const openrouterRuntime = m.openrouterRuntime;
+            if (serverTools != null ||
+                openrouterRuntime != null ||
+                (Array.isArray(generatedImages) && generatedImages.length) ||
+                (Array.isArray(patchProposals) && patchProposals.length)) {
+                out.openrouterRuntime = {
+                    ...(openrouterRuntime != null && typeof openrouterRuntime === 'object'
+                        ? {
+                            apiMode: openrouterRuntime.apiMode,
+                            serverTools,
+                        }
+                        : { serverTools }),
+                    citationCount: Array.isArray(citations) ? citations.length : 0,
+                    generatedImageCount: Array.isArray(generatedImages) ? generatedImages.length : 0,
+                    patchProposalCount: Array.isArray(patchProposals) ? patchProposals.length : 0,
+                };
+            }
         }
     }
     return out;

package/dist-cjs/gateway-config.cjs

@@ -11,6 +11,7 @@ import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
 import { UsageTracker } from './usage-tracker.js';
 import { mergeTemplateRenderOptions } from './template-render-merge.js';
+import { registerOpenRouterRuntime, shouldUseOpenRouterRuntime, } from './openrouter-runtime-adapter/index.js';
 /** Resolve current module directory across ESM/CJS builds. */
 function getModuleDir() {
     if (typeof __dirname !== 'undefined') {
@@ -167,6 +168,20 @@ export function initializeGatewayComponents(config) {
     }
     const router = new LLMProviderRouter(routerConfig);
     setupRequestInterceptor(router, logger);
+    if (openRouterKey && shouldUseOpenRouterRuntime(config)) {
+        registerOpenRouterRuntime(router, {
+            apiKey: openRouterKey,
+            logger,
+            runtimeConfig: config.openrouterRuntime,
+        });
+    }
+    else if (openRouterKey) {
+        logger.debug('OpenRouter legacy provider path enabled (runtime disabled)', {
+            AI_GATEWAY_USE_OPENROUTER_RUNTIME: process.env.AI_GATEWAY_USE_OPENROUTER_RUNTIME,
+            AI_GATEWAY_USE_LEGACY_OPENROUTER: process.env.AI_GATEWAY_USE_LEGACY_OPENROUTER,
+            openrouterRuntimeEnabled: config.openrouterRuntime?.enabled,
+        });
+    }
     const usageTracker = new UsageTracker({
         enableUsageTracking: config.enableUsageTracking ?? true,
         usageTier: config.usageTier,

package/dist-cjs/gateway-utils.cjs

@@ -9,6 +9,7 @@ import { extractHttpStatusCode } from './gateway-retry.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { MaxTokensRequiredError, ModelRequiredError, } from './instruction-errors.js';
 import { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
+import { applyOnlineVariantMigration, applyPostRoutingServerToolsPolicy, mergeOpenRouterConfig, mergeServerToolsConfig, normalizeApplyPatchDefaults, resolveOpenRouterRuntimeDefaults, pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata, } from './openrouter-runtime-adapter/index.js';
 import { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P } from './gateway-defaults.js';
 function getPreParsedInstructions(instructions) {
     return instructions ?? '';
@@ -115,6 +116,31 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     merged.model = ingress.model;
     originalProvider = merged.provider;
     originalModel = merged.model;
+    const runtimeDefaults = resolveOpenRouterRuntimeDefaults(config);
+    let mergedServerTools = normalizeApplyPatchDefaults(mergeServerToolsConfig(config.defaultServerTools, request.config?.serverTools, request.modelConfig?.serverTools));
+    const mergedOpenRouter = mergeOpenRouterConfig({ apiMode: runtimeDefaults.apiMode, includeRawInTrace: runtimeDefaults.includeRawInTrace }, request.config?.openrouter, request.modelConfig?.openrouter);
+    const onlineMigration = applyOnlineVariantMigration(merged.model, mergedServerTools);
+    if (onlineMigration.model !== merged.model) {
+        merged.model = onlineMigration.model;
+        originalModel = merged.model;
+        mergedServerTools = onlineMigration.serverTools;
+        logger.warn('OpenRouter :online model variant migrated', {
+            jobId: request.identity.jobId,
+            code: onlineMigration.warning?.code,
+            message: onlineMigration.warning?.message,
+        });
+        const warnings = request._openrouterWarnings;
+        if (onlineMigration.warning) {
+            request._openrouterWarnings = [
+                ...(warnings ?? []),
+                onlineMigration.warning,
+            ];
+        }
+    }
+    if (mergedServerTools)
+        merged.serverTools = mergedServerTools;
+    if (mergedOpenRouter)
+        merged.openrouter = mergedOpenRouter;
     if (resolveModels && mergeOptions?.catalog) {
         try {
             const resolved = await resolveInvokeModel({ provider: merged.provider, model: merged.model }, {
@@ -175,6 +201,34 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             merged.providerProxy = resolved.router.providerProxy;
         }
     }
+    const serverToolsPolicy = applyPostRoutingServerToolsPolicy({
+        provider: merged.provider,
+        serverTools: merged.serverTools,
+        openrouter: merged.openrouter,
+        openRouterApiKey: mergeOptions?.openRouterApiKey,
+    });
+    if (serverToolsPolicy.forceOpenRouter) {
+        merged.provider = 'openrouter';
+        logger.verbose('Required OpenRouter server tool forced provider=openrouter', {
+            jobId: request.identity.jobId,
+        });
+    }
+    if (serverToolsPolicy.serverTools) {
+        merged.serverTools = serverToolsPolicy.serverTools;
+    }
+    else {
+        delete merged.serverTools;
+    }
+    if (serverToolsPolicy.warnings.length) {
+        const existing = request._openrouterWarnings;
+        request._openrouterWarnings = [
+            ...(existing ?? []),
+            ...serverToolsPolicy.warnings,
+        ];
+        for (const w of serverToolsPolicy.warnings) {
+            logger.warn(w.message, { jobId: request.identity.jobId, code: w.code });
+        }
+    }
     if (!merged.model) {
         throw new ModelRequiredError();
     }
@@ -571,7 +625,7 @@ function buildTraceAttemptPricingRecord(attempt, mergedConfig) {
 /**
  * Trace-mode summary: final token usage + resolved billing (after catalog pricing when applicable).
  */
-export function buildTraceUsageSummary(tokens, billing, maxTokensRequested) {
+export function buildTraceUsageSummary(tokens, billing, maxTokensRequested, openrouterExtras) {
     if (!hasNonZeroTokenUsage(tokens) && !billing.costStatus) {
         return undefined;
     }
@@ -589,8 +643,26 @@ export function buildTraceUsageSummary(tokens, billing, maxTokensRequested) {
     if (billing.costBreakdown) {
         summary.costBreakdown = billing.costBreakdown;
     }
+    if (openrouterExtras?.serverTools)
+        summary.serverTools = openrouterExtras.serverTools;
+    if (openrouterExtras?.citations?.length)
+        summary.citations = openrouterExtras.citations;
     return summary;
 }
+/**
+ * Additive OpenRouter runtime metadata for gateway responses.
+ */
+export function pickEnhancedOpenRouterMetadata(routerResponse, traceEnabled = false) {
+    const slice = pickOpenRouterRuntimeMetadataSlice(routerResponse);
+    if (!slice.openrouterRuntime && !slice.serverTools && !slice.citations?.length) {
+        return slice;
+    }
+    const openrouterRuntime = enrichTraceOpenRouterRuntimeMetadata(slice.openrouterRuntime, slice, traceEnabled);
+    return {
+        ...slice,
+        ...(openrouterRuntime ? { openrouterRuntime } : {}),
+    };
+}
 /**
  * Apply resolved billing to trace attempts: final successful attempt gets aggregate billing;
  * other successful attempts without router cost get per-attempt catalog pricing when enabled.

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

@@ -5,6 +5,7 @@
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
+import { pickOpenRouterRuntimeMetadataSlice, enrichTraceOpenRouterRuntimeMetadata } from './openrouter-runtime-adapter/index.js';
 /**
  * Generates MD5 hash of a string
  */
@@ -132,7 +133,13 @@ export declare function buildTraceUsageSummary(tokens: {
     prompt: number;
     completion: number;
     total: number;
-}, billing: ResolvedActivityCost, maxTokensRequested?: number): GatewayTraceUsageSummary | undefined;
+}, billing: ResolvedActivityCost, maxTokensRequested?: number, openrouterExtras?: Pick<GatewayTraceUsageSummary, 'serverTools' | 'citations'>): GatewayTraceUsageSummary | undefined;
+/**
+ * Additive OpenRouter runtime metadata for gateway responses.
+ */
+export declare function pickEnhancedOpenRouterMetadata(routerResponse: unknown, traceEnabled?: boolean): ReturnType<typeof pickOpenRouterRuntimeMetadataSlice> & {
+    openrouterRuntime?: ReturnType<typeof enrichTraceOpenRouterRuntimeMetadata>;
+};
 /**
  * Apply resolved billing to trace attempts: final successful attempt gets aggregate billing;
  * other successful attempts without router cost get per-attempt catalog pricing when enabled.