@x12i/ai-gateway 10.0.2 → 10.0.5

package/dist/gateway-utils.js

@@ -4,11 +4,10 @@
  */
 import * as crypto from 'crypto';
 import { FallbackExhaustedError } from '@x12i/ai-providers-router';
-import { ModelResolutionError, isKnownProfileChoice } from '@x12i/ai-tools';
+import { ModelResolutionError, ModelProfileInputRejectedError, ModelProfileUnroutableError, resolveInvokeModel, } from '@x12i/ai-tools';
 import { extractHttpStatusCode } from './gateway-retry.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { MaxTokensRequiredError, ModelRequiredError } from './instruction-errors.js';
-import { applyModelResolution, buildModelResolverOptions } from './ai-tools-client.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 ?? '';
@@ -37,6 +36,7 @@ export async function ensureTaskTypeId(request, logger) {
     });
     return taskTypeId;
 }
+export { MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, } from '@x12i/ai-tools';
 /**
  * Merges config with defaults
  * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
@@ -100,45 +100,64 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     }
     if (resolveModels && mergeOptions?.catalog) {
         try {
-            const resolverOptions = buildModelResolverOptions(config, mergeOptions?.routingEnv);
-            const resolution = await mergeOptions.catalog.resolveModel({
-                provider: merged.provider,
-                model: explicitModel,
-            }, resolverOptions);
-            if (resolution.found) {
-                applyModelResolution(merged, resolution, config.defaultEngine, explicitModel);
-                request._modelResolution = {
-                    modelId: resolution.modelId,
-                    routedViaOpenRouter: resolution.routedViaOpenRouter,
-                    confidence: resolution.confidence,
-                    resolvedVia: resolution.resolvedVia,
-                    originalProvider,
-                    originalModel
-                };
-                logger.verbose('Catalog resolved model name', {
-                    jobId: request.identity.jobId,
-                    originalModel,
-                    resolvedModelId: resolution.modelId,
-                    provider: merged.provider,
-                    model: merged.model,
-                    confidence: resolution.confidence,
-                    resolvedVia: resolution.resolvedVia
-                });
+            const resolved = await resolveInvokeModel({ provider: merged.provider, model: explicitModel }, {
+                catalog: mergeOptions.catalog,
+                routingEnv: mergeOptions.routingEnv,
+                openRouterApiKey: mergeOptions.openRouterApiKey,
+                preferOpenRouter: mergeOptions.preferOpenRouter,
+                defaultProvider: config.defaultEngine,
+                resolveModels: true,
+                modelsOnly: config.aiTools?.modelsOnly !== false,
+                ...(config.aiTools?.catalogLane ? { catalogLane: config.aiTools.catalogLane } : {}),
+                ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
+            });
+            merged.provider = resolved.router.provider;
+            merged.model = resolved.router.model;
+            if (resolved.router.allowOpenRouterProxy !== undefined) {
+                merged.allowOpenRouterProxy = resolved.router.allowOpenRouterProxy;
             }
-            else {
-                throw buildModelResolutionFailureError(explicitModel, merged.provider, resolution);
+            if (resolved.router.providerProxy !== undefined) {
+                merged.providerProxy = resolved.router.providerProxy;
             }
+            request._modelResolution = resolved.diagnostics;
+            logger.verbose('Catalog resolved model name', {
+                jobId: request.identity.jobId,
+                originalModel,
+                originalProvider,
+                resolvedModelId: resolved.diagnostics.modelId,
+                provider: merged.provider,
+                model: merged.model,
+                confidence: resolved.diagnostics.confidence,
+                resolvedVia: resolved.diagnostics.resolvedVia,
+                routedViaOpenRouter: resolved.diagnostics.routedViaOpenRouter,
+            });
         }
         catch (error) {
-            if (error instanceof ModelResolutionError) {
-                throw error;
-            }
-            if (error instanceof ModelProfileUnroutableError) {
+            if (error instanceof ModelResolutionError ||
+                error instanceof ModelProfileUnroutableError ||
+                error instanceof ModelProfileInputRejectedError) {
                 throw error;
             }
             throw error;
         }
     }
+    else if (mergeOptions?.openRouterApiKey) {
+        const resolved = await resolveInvokeModel({ provider: merged.provider, model: explicitModel }, {
+            resolveModels: false,
+            routingEnv: mergeOptions.routingEnv,
+            openRouterApiKey: mergeOptions.openRouterApiKey,
+            preferOpenRouter: mergeOptions.preferOpenRouter,
+            defaultProvider: config.defaultEngine,
+        });
+        merged.provider = resolved.router.provider;
+        merged.model = resolved.router.model;
+        if (resolved.router.allowOpenRouterProxy !== undefined) {
+            merged.allowOpenRouterProxy = resolved.router.allowOpenRouterProxy;
+        }
+        if (resolved.router.providerProxy !== undefined) {
+            merged.providerProxy = resolved.router.providerProxy;
+        }
+    }
     if (!merged.model) {
         throw new ModelRequiredError();
     }
@@ -351,42 +370,119 @@ export function resolveCostCompletionForActivity(routerResponse, tokens) {
     }
     return resolveActivityCostCompletion(tokens, costUsd);
 }
-/** Record shape for {@link CostCalculator.calculateFromRecord} (router + merged config + usage). */
+/**
+ * Best-effort cache/reasoning token counts from router usage buckets
+ * (for {@link buildGatewayPricingRecord} / ai-tools {@link CostCalculator.calculateFromRecord}).
+ */
+export function extractUsageExtrasFromRouterResponse(routerResponse) {
+    if (routerResponse == null || typeof routerResponse !== 'object')
+        return {};
+    const r = routerResponse;
+    const roots = [r.usage];
+    const meta = r.metadata != null && typeof r.metadata === 'object'
+        ? r.metadata
+        : undefined;
+    if (meta) {
+        roots.push(meta.usage, meta.tokens);
+    }
+    const raw = r.rawResponse ?? r.raw;
+    if (raw != null && typeof raw === 'object') {
+        roots.push(raw.usage);
+    }
+    const extras = {};
+    for (const bucket of roots) {
+        if (bucket == null || typeof bucket !== 'object')
+            continue;
+        const u = bucket;
+        const cached = firstFiniteNumber(u.cached, u.cached_tokens, u.cachedTokens, u.cache_read_tokens, u.cacheReadTokens);
+        const cacheWrite = firstFiniteNumber(u.cacheWrite, u.cache_write_tokens, u.cacheWriteTokens);
+        const reasoning = firstFiniteNumber(u.reasoning, u.reasoning_tokens, u.reasoningTokens);
+        if (cached !== undefined && extras.cached === undefined)
+            extras.cached = cached;
+        if (cacheWrite !== undefined && extras.cacheWrite === undefined)
+            extras.cacheWrite = cacheWrite;
+        if (reasoning !== undefined && extras.reasoning === undefined)
+            extras.reasoning = reasoning;
+    }
+    return extras;
+}
+/**
+ * Whether ai-tools catalog pricing is authoritative enough for Step B (`priced`).
+ * Matches the generic engine contract: authoritative catalog hit with finite cost ≥ 0.
+ */
+export function catalogPricingSucceeded(result) {
+    if (result.unknownModel)
+        return false;
+    if (!result.isAuthoritative)
+        return false;
+    if (result.source === 'estimate-fallback' || result.source === 'local')
+        return false;
+    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost) || result.cost < 0) {
+        return false;
+    }
+    return true;
+}
+/** Record shape for {@link CostCalculator.calculateFromRecord} (shared engine contract). */
 export function buildGatewayPricingRecord(routerResponse, tokens, mergedConfig) {
-    const base = routerResponse != null && typeof routerResponse === 'object'
-        ? { ...routerResponse }
-        : {};
-    const meta = base.metadata != null && typeof base.metadata === 'object'
-        ? { ...base.metadata }
-        : {};
     const routing = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object'
+        ? mergedConfig
+        : {};
+    const requestModel = typeof cfg.model === 'string'
+        ? cfg.model
+        : typeof routing.modelUsed === 'string'
+            ? routing.modelUsed
+            : undefined;
+    const modelUsed = routing.modelUsed ?? requestModel;
+    const provider = routing.provider ??
+        (typeof cfg.provider === 'string' ? cfg.provider : undefined) ??
+        'openrouter';
+    const usageExtras = extractUsageExtrasFromRouterResponse(routerResponse);
+    const tokenSlice = {
+        prompt: tokens.prompt,
+        completion: tokens.completion,
+        total: tokens.total,
+        ...usageExtras
+    };
     return {
-        ...base,
+        model: modelUsed ?? requestModel ?? '',
+        ...(requestModel && modelUsed && requestModel !== modelUsed
+            ? { modelAlias: requestModel }
+            : {}),
+        ...(modelUsed ? { modelUsed, usedModel: modelUsed } : {}),
+        provider,
+        ...(provider || routing.region
+            ? {
+                routing: {
+                    provider,
+                    ...(routing.region ? { region: routing.region } : {})
+                }
+            }
+            : {}),
         usage: {
-            promptTokens: tokens.prompt,
-            completionTokens: tokens.completion,
-            totalTokens: tokens.total
+            prompt_tokens: tokens.prompt,
+            completion_tokens: tokens.completion,
+            total_tokens: tokens.total,
+            ...(usageExtras.cached !== undefined ? { cachedTokensPrompt: usageExtras.cached } : {}),
+            ...(usageExtras.cached !== undefined ? { cachedTokensTotal: usageExtras.cached } : {})
         },
-        tokens,
+        promptTokens: tokens.prompt,
+        completionTokens: tokens.completion,
+        totalTokens: tokens.total,
+        tokens: tokenSlice,
         metadata: {
-            ...meta,
-            tokens,
-            ...(routing.provider ? { provider: routing.provider } : {}),
-            ...(routing.modelUsed
-                ? { modelUsed: routing.modelUsed, model: routing.modelUsed }
-                : {})
+            provider,
+            ...(modelUsed ? { modelUsed, model: modelUsed } : {}),
+            ...(routing.maxTokensRequested !== undefined
+                ? { maxTokensRequested: routing.maxTokensRequested }
+                : {}),
+            tokens: tokenSlice
         },
         ...(mergedConfig != null ? { config: mergedConfig } : {})
     };
 }
 export function mapAiCostResultToResolvedActivityCost(base, result) {
-    if (result.unknownModel) {
-        return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
-    }
-    if (typeof result.cost !== 'number' || !Number.isFinite(result.cost)) {
-        return base;
-    }
-    if (!result.isAuthoritative && result.source === 'estimate-fallback') {
+    if (!catalogPricingSucceeded(result)) {
         return base.costStatus ? base : { ...base, costStatus: 'unpriced' };
     }
     return {
@@ -395,6 +491,16 @@ export function mapAiCostResultToResolvedActivityCost(base, result) {
         ...(result.breakdown ? { costBreakdown: result.breakdown } : {})
     };
 }
+/**
+ * G8 safety net: token usage without a billing signal → `unpriced`.
+ * Used at invoke boundaries after {@link resolveCostCompletionWithAiTools}.
+ */
+export function ensureInvokeBillingCostStatus(billing, tokens) {
+    if (!billing.costStatus && hasNonZeroTokenUsage(tokens)) {
+        return { ...billing, costStatus: 'unpriced' };
+    }
+    return billing;
+}
 /**
  * Router cost passthrough, then optional @x12i/ai-tools catalog pricing when still unpriced.
  */
@@ -419,30 +525,7 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         return mapAiCostResultToResolvedActivityCost(base, result);
     }
     catch {
-        const routing = pickInvokeRoutingMetadataSlice(routerResponse, options.mergedConfig);
-        const cfg = options.mergedConfig != null && typeof options.mergedConfig === 'object'
-            ? options.mergedConfig
-            : {};
-        const provider = routing.provider ?? cfg.provider;
-        const modelUsed = routing.modelUsed ?? cfg.model;
-        if (!provider || !modelUsed) {
-            return base;
-        }
-        try {
-            const result = await options.calculator.calculate({
-                tokens: {
-                    prompt: tokens.prompt,
-                    completion: tokens.completion,
-                    total: tokens.total
-                },
-                provider,
-                usedModel: modelUsed
-            });
-            return mapAiCostResultToResolvedActivityCost(base, result);
-        }
-        catch {
-            return base;
-        }
+        return ensureInvokeBillingCostStatus(base, tokens);
     }
 }
 function applyBillingToTraceAttempt(attempt, billing) {
@@ -679,31 +762,6 @@ export function pickRequestIdsFromRouterLike(gatewayAiRequestId, routerLike) {
     }
     return out;
 }
-/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
-export const MODEL_PROFILE_UNROUTABLE = 'MODEL_PROFILE_UNROUTABLE';
-export class ModelProfileUnroutableError extends Error {
-    profileAlias;
-    provider;
-    code = MODEL_PROFILE_UNROUTABLE;
-    constructor(profileAlias, provider, cause) {
-        super(`${MODEL_PROFILE_UNROUTABLE}: profile "${profileAlias}" is retired or has no routable catalog target` +
-            (provider ? ` (provider: "${provider}")` : '') +
-            '. Update @x12i/ai-profiles or choose another profile alias.');
-        this.profileAlias = profileAlias;
-        this.provider = provider;
-        this.name = 'ModelProfileUnroutableError';
-        if (cause !== undefined) {
-            this.cause = cause;
-        }
-    }
-}
-function buildModelResolutionFailureError(explicitModel, provider, resolution) {
-    const base = new ModelResolutionError({ provider, model: explicitModel }, resolution);
-    if (isKnownProfileChoice(explicitModel)) {
-        return new ModelProfileUnroutableError(explicitModel, provider, base);
-    }
-    return base;
-}
 /**
  * Build rejection-metadata fallback attempts from trace-mode {@link GatewayTraceAttempt}s.
  */
@@ -772,7 +830,7 @@ export function mapGatewayFallbackAttemptsToRouter(attempts) {
     }));
 }
 /**
- * Log profile alias vs OpenRouter model id actually sent to the router after catalog resolution.
+ * Log original input vs OpenRouter model id actually sent to the router after catalog resolution.
  */
 export function logResolvedModelRouting(logger, request, mergedConfig) {
     const res = request._modelResolution;
@@ -780,14 +838,14 @@ export function logResolvedModelRouting(logger, request, mergedConfig) {
         return;
     }
     const profileAlias = res.originalModel ?? mergedConfig?.model;
-    const invokedModelId = res.modelId ?? mergedConfig?.model;
+    const invokedModelId = res.invokedModelId ?? res.modelId ?? mergedConfig?.model;
     const provider = mergedConfig?.provider;
     const openRouterPath = res.routedViaOpenRouter === true || provider === 'openrouter';
     if (!openRouterPath) {
         return;
     }
-    logger.info('OpenRouter routing: profile alias resolved to model id for invoke', withActivityIdentity(request.identity, {
-        profileAlias,
+    logger.info('OpenRouter routing: input model resolved to catalog id for invoke', withActivityIdentity(request.identity, {
+        inputModel: profileAlias,
         invokedOpenRouterModelId: invokedModelId,
         provider,
         routedViaOpenRouter: res.routedViaOpenRouter,

package/dist/gateway.js

@@ -11,10 +11,9 @@ import { resolveRetryConfig } from './gateway-defaults.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
-import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, hasNonZeroTokenUsage, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, tryExtractRouterLikePayloadFromErrorChain } from './gateway-utils.js';
+import { attachGatewayInvokeRejectionMetadata, buildGatewayFallbackAttemptsFromTrace, buildInvokeRejectionMetadata, capActivityFullResponsePayload, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter, DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, extractCostUsdFromRouterResponse, extractTokenUsageFromRouterResponse, mergeConfig, pickEffectiveModelConfigForMetadata, pickInvokeRoutingMetadataSlice, pickTraceMergedRouterConfig, resolveCostCompletionWithAiTools, ensureInvokeBillingCostStatus, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, 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, withGatewayLogContext } from './gateway-log-meta.js';
 import { exceptionEvidence, fieldEvidence, GatewayLogCode, gatewayErrorCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
@@ -100,15 +99,11 @@ export class AIGateway {
             const mergedConfig = await mergeConfig(request, this.config, this.logger, {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
+                openRouterApiKey: this.openRouterApiKey,
+                preferOpenRouter: this.preferOpenRouter,
             });
             // 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,
-            });
             // 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);
@@ -140,11 +135,12 @@ export class AIGateway {
                 });
                 const metaChat = response?.metadata || {};
                 const tokensChat = extractTokenUsageFromRouterResponse(response);
-                const costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
+                let costCompletionChat = await resolveCostCompletionWithAiTools(response, tokensChat, {
                     mergedConfig,
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
+                costCompletionChat = ensureInvokeBillingCostStatus(costCompletionChat, tokensChat);
                 // Create enhanced response
                 const enhancedResponse = {
                     content: response.content || '',
@@ -292,14 +288,10 @@ export class AIGateway {
             const mergedConfig = await mergeConfig(request, this.config, this.logger, {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
-            });
-            request._mergedRouterConfig = mergedConfig;
-            applyOpenRouterInvokePolicy(mergedConfig, {
-                preferOpenRouter: this.preferOpenRouter,
                 openRouterApiKey: this.openRouterApiKey,
-                routingEnv: aiTools?.routingEnv,
-                resolution: request._modelResolution,
+                preferOpenRouter: this.preferOpenRouter,
             });
+            request._mergedRouterConfig = mergedConfig;
             logResolvedModelRouting(this.logger, request, mergedConfig);
             const diagnosticsMode = request.diagnostics?.mode;
             const traceEnabled = diagnosticsMode === 'trace';
@@ -623,9 +615,7 @@ export class AIGateway {
                     calculator: aiTools?.calculator ?? null,
                     calculateCost: this.config.aiTools?.calculateCost
                 });
-                if (!costCompletion.costStatus && hasNonZeroTokenUsage(tokens)) {
-                    costCompletion = { ...costCompletion, costStatus: 'unpriced' };
-                }
+                costCompletion = ensureInvokeBillingCostStatus(costCompletion, tokens);
                 const routerMetaForCost = routerResponse?.metadata || {};
                 const routingMetadataSlice = pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig);
                 const effectiveModelConfig = pickEffectiveModelConfigForMetadata(mergedConfig);

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayFallbackAttempt, GatewayTraceRequestIds, GatewayTraceAttempt, GatewayTraceUsageSummary, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export type { GatewayOperationalMode } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
@@ -40,6 +40,9 @@ export type { GatewayLoggerConfig } from './logger-factory.js';
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
+/** Re-export @x12i/ai-tools invoke orchestrator (≥ 2.5.0) for engine callers. */
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export type { AiToolsClientBundle, AiToolsInvokeClient, InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, } from './ai-tools-client.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
 export type { Logxer, LogMeta, RuntimeIdentity, LogRuntimeContext, GetJobLogsInput, GetJobLogsResult, QueryableLogLine, LogDiagnostics, DiagnosticEvidence, ScopeCriteria, ScopeLogsResult, StackLoggingOptions, PackageLogLevelsConfig, PackageLogLevelSetting } from '@x12i/logxer';

package/dist/index.js

@@ -17,7 +17,7 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, ensureInvokeBillingCostStatus, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
 export { getGatewayOperationalMode, isProdGatewayMode, parseModelProviderSpec } from './gateway-mode.js';
 export { DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS, GATEWAY_DEFAULT_FREQUENCY_PENALTY, GATEWAY_DEFAULT_PRESENCE_PENALTY, GATEWAY_DEFAULT_RETRY, GATEWAY_DEFAULT_TEMPERATURE, GATEWAY_DEFAULT_TOP_P, resolveRetryConfig } from './gateway-defaults.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
@@ -33,6 +33,8 @@ export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityId
 export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
+/** Re-export @x12i/ai-tools invoke orchestrator (≥ 2.5.0) for engine callers. */
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist/openrouter-routing.d.ts

@@ -1,17 +1,8 @@
 /**
- * OpenRouter API key and gateway-level "prefer OpenRouter" flag.
- * Provider/model routing (openrouter vs vendor) is resolved by @x12i/ai-tools in mergeConfig.
+ * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
  */
+import { readPreferOpenRouterFromEnv } from '@x12i/ai-tools';
 import type { GatewayConfig } from './types.js';
+export { readPreferOpenRouterFromEnv };
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
-/**
- * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
- * Returns undefined when neither is set.
- */
-export declare function readPreferOpenRouterFromEnv(): boolean | undefined;
-/**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
- * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
- * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
- */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;

package/dist/openrouter-routing.js

@@ -1,37 +1,11 @@
 /**
- * OpenRouter API key and gateway-level "prefer OpenRouter" flag.
- * Provider/model routing (openrouter vs vendor) is resolved by @x12i/ai-tools in mergeConfig.
+ * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
  */
+import { readPreferOpenRouterFromEnv, resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouter as resolvePreferFromTools, } from '@x12i/ai-tools';
+export { readPreferOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
-    const explicit = config.openrouter?.apiKey;
-    if (typeof explicit === 'string' && explicit.trim() && !explicit.startsWith('ENV.')) {
-        return explicit.trim();
-    }
-    const env = process.env.OPENROUTER_API_KEY?.trim();
-    return env || undefined;
+    return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
-/**
- * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
- * Returns undefined when neither is set.
- */
-export function readPreferOpenRouterFromEnv() {
-    const prefer = process.env.PREFER_OPENROUTER?.trim();
-    if (prefer === 'false' || prefer === '0')
-        return false;
-    if (prefer === 'true' || prefer === '1')
-        return true;
-    const legacy = process.env.USE_OPENROUTER?.trim();
-    if (legacy === 'false' || legacy === '0')
-        return false;
-    if (legacy === 'true' || legacy === '1')
-        return true;
-    return undefined;
-}
-/**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
- * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
- * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
- */
 export function resolvePreferOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
@@ -41,8 +15,5 @@ export function resolvePreferOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    const fromEnv = readPreferOpenRouterFromEnv();
-    if (fromEnv !== undefined)
-        return fromEnv;
-    return true;
+    return resolvePreferFromTools();
 }

package/dist/types.d.ts

@@ -9,6 +9,7 @@ type AIModel = string;
 export type UsageTier = string;
 import type { Activix } from '@x12i/activix';
 import type { SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from '@x12i/rendrix';
+import type { ProfileCatalogLane } from '@x12i/ai-profiles';
 import type { Logxer, PackageLogLevelsConfig } from '@x12i/logxer';
 /**
  * Diagnostics options for opt-in authoritative tracing.
@@ -415,10 +416,21 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
         cacheTtlMs?: number;
         /** Use bundled catalog JSON only (offline / tests). */
         bundledOnly?: boolean;
+        /**
+         * Catalog lane for model resolution and cost lookup (`text`, `image`, …).
+         * @default `"text"` in ai-tools when omitted.
+         */
+        catalogLane?: ProfileCatalogLane;
         /** @default true */
         resolveModels?: boolean;
+        /**
+         * When true (default), reject profile/choice keys and shortcuts (`cheap/default`, `cheapest`, …).
+         * Only concrete catalog model ids are accepted; ai-tools still normalizes aliases and routing.
+         */
+        modelsOnly?: boolean;
         /** @default true */
         calculateCost?: boolean;
+        /** @default false — when true, priced results may include prompt/completion breakdown. */
         costIncludeBreakdown?: boolean;
     };
     /**