@x12i/ai-gateway 10.0.1 → 10.0.4

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

@@ -417,6 +417,11 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
         bundledOnly?: boolean;
         /** @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;
         costIncludeBreakdown?: boolean;

package/dist-cjs/ai-tools-client.cjs

@@ -1,25 +1,35 @@
 /**
- * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ * @x12i/ai-tools invoke client bootstrap for the gateway.
+ * Model resolution orchestration lives in ai-tools ≥ 2.5.0 (`resolveInvokeModel`).
  */
-import { AiModelsCatalogClient, CostCalculator, isEffectiveOpenRouterTransport, loadOpenRouterRoutingEnv, resolveModelVendorFromResolution } from '@x12i/ai-tools';
+import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { resolvePreferOpenRouter } from './openrouter-routing.js';
-let sharedClientPromise = null;
-let sharedConfigKey;
+export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
+export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv } from './openrouter-routing.js';
 let bootstrapFailedLogged = false;
-function configKey(config) {
-    return `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`;
+function invokeClientOptions(config) {
+    return {
+        cacheTtlMs: config.aiTools?.cacheTtlMs,
+        ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
+        ...(config.aiTools?.costIncludeBreakdown ? { costIncludeBreakdown: true } : {}),
+        cacheKey: `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`,
+    };
+}
+/** @deprecated Use buildInvokeModelResolverOptions */
+export function buildModelResolverOptions(config, routingEnv) {
+    return buildInvokeModelResolverOptions({
+        routingEnv,
+        preferOpenRouter: resolvePreferOpenRouter(config),
+    });
 }
 /**
- * Per-invoke resolver options: ai-tools decides OpenRouter vs direct from env + optional gateway prefer override.
+ * @deprecated Use mapResolutionToRouterConfig from @x12i/ai-tools
  */
-export function buildModelResolverOptions(config, routingEnv) {
-    const env = routingEnv ?? loadOpenRouterRoutingEnv();
-    const prefer = resolvePreferOpenRouter(config);
-    return {
-        routingEnv: env,
-        ...(prefer ? { routeViaOpenRouter: true } : {}),
-    };
+export function applyModelResolution(merged, resolution, gatewayDefaultEngine, inputModel) {
+    const mapped = mapResolutionToRouterConfig(resolution, { provider: merged.provider, model: inputModel ?? merged.model ?? '' }, gatewayDefaultEngine);
+    merged.provider = mapped.provider;
+    merged.model = mapped.model;
 }
 /**
  * Returns catalog + calculator, or null when disabled or bootstrap fails.
@@ -28,102 +38,26 @@ export async function getAiToolsClient(config, logger) {
     if (config.aiTools?.enabled === false) {
         return null;
     }
-    const key = configKey(config);
-    if (sharedClientPromise && sharedConfigKey !== key) {
-        sharedClientPromise = null;
-    }
-    sharedConfigKey = key;
-    if (!sharedClientPromise) {
-        sharedClientPromise = bootstrapAiTools(config, logger);
-    }
-    return sharedClientPromise;
-}
-/** Reset singleton (tests). */
-export function resetAiToolsClientForTests() {
-    sharedClientPromise = null;
-    sharedConfigKey = undefined;
-    bootstrapFailedLogged = false;
-}
-async function bootstrapAiTools(config, logger) {
-    try {
-        const routingEnv = loadOpenRouterRoutingEnv();
-        const catalog = new AiModelsCatalogClient({
-            cacheTtlMs: config.aiTools?.cacheTtlMs,
-            ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
-            resolverOptions: { routingEnv },
-        });
-        const calculator = new CostCalculator(catalog, {
-            includeBreakdown: config.aiTools?.costIncludeBreakdown === true,
-        });
+    const client = await getAiToolsInvokeClient(invokeClientOptions(config), {
+        warn: (msg, err) => {
+            if (!bootstrapFailedLogged) {
+                bootstrapFailedLogged = true;
+                logger.warn(msg, withActivityIdentity(undefined, {
+                    error: err instanceof Error ? err.message : String(err),
+                    debugKind: gatewayLogDebug.anomaly,
+                }));
+            }
+        },
+    });
+    if (client) {
         logger.debug('ai-tools catalog client ready', {
             debugKind: gatewayLogDebug.state,
         });
-        return { catalog, calculator, routingEnv };
-    }
-    catch (error) {
-        if (!bootstrapFailedLogged) {
-            bootstrapFailedLogged = true;
-            logger.warn('ai-tools catalog bootstrap failed; model resolution and catalog cost calculation disabled', withActivityIdentity(undefined, {
-                error: error instanceof Error ? error.message : String(error),
-                debugKind: gatewayLogDebug.anomaly,
-            }));
-        }
-        return null;
     }
+    return client;
 }
-/**
- * Map catalog resolution to router `{ provider, model }` (agnostic to openrouter vs vendor input).
- */
-export function applyModelResolution(merged, resolution, gatewayDefaultEngine, inputModel) {
-    const ref = resolveModelVendorFromResolution(resolution, inputModel ?? merged.model ?? '', {
-        asOpenRouter: resolution.routedViaOpenRouter,
-    });
-    if (ref) {
-        merged.provider = ref.provider;
-        merged.model = ref.model;
-        return;
-    }
-    if (resolution.routedViaOpenRouter) {
-        merged.provider = 'openrouter';
-        merged.model = resolution.modelId;
-        return;
-    }
-    const slash = resolution.modelId.indexOf('/');
-    if (slash > 0) {
-        merged.provider = resolution.record?.providerId ?? resolution.modelId.slice(0, slash);
-        merged.model = resolution.modelId.slice(slash + 1);
-    }
-    else {
-        merged.model = resolution.modelId;
-        if (resolution.record?.providerId) {
-            merged.provider = resolution.record.providerId;
-        }
-    }
-    if (!merged.provider && gatewayDefaultEngine) {
-        merged.provider = gatewayDefaultEngine;
-    }
-}
-/**
- * Router invoke flags after mergeConfig + ai-tools resolution (OpenRouter vs direct transport).
- */
-export function applyOpenRouterInvokePolicy(merged, options) {
-    if (!options.openRouterApiKey?.trim())
-        return;
-    const routingEnv = options.routingEnv ?? loadOpenRouterRoutingEnv();
-    const viaOpenRouter = options.resolution?.routedViaOpenRouter === true ||
-        (options.resolution?.routedViaOpenRouter !== false &&
-            isEffectiveOpenRouterTransport(routingEnv, {
-                provider: merged.provider,
-                modelId: merged.model,
-                routeViaOpenRouter: options.preferOpenRouter ? true : undefined,
-            }));
-    if (viaOpenRouter) {
-        merged.allowOpenRouterProxy = true;
-        if (merged.provider && merged.provider !== 'openrouter') {
-            merged.providerProxy = 'openrouter';
-        }
-    }
-    else {
-        merged.allowOpenRouterProxy = false;
-    }
+/** Reset singleton (tests). */
+export function resetAiToolsClientForTests() {
+    resetAiToolsInvokeClientForTestsUpstream();
+    bootstrapFailedLogged = false;
 }

package/dist-cjs/ai-tools-client.d.ts

@@ -1,44 +1,26 @@
 /**
- * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ * @x12i/ai-tools invoke client bootstrap for the gateway.
+ * Model resolution orchestration lives in ai-tools ≥ 2.5.0 (`resolveInvokeModel`).
  */
-import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess, type ModelResolverOptions, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
+import { type AiToolsInvokeClient, type ModelResolutionSuccess, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
 import type { Logxer } from '@x12i/logxer';
-import type { ChatRequest, GatewayConfig } from './types.js';
-export type AiToolsClientBundle = {
-    catalog: AiModelsCatalogClient;
-    calculator: CostCalculator;
-    routingEnv: OpenRouterRoutingConfig;
-};
+import type { GatewayConfig } from './types.js';
+export type AiToolsClientBundle = AiToolsInvokeClient;
+export { resolveInvokeModel, applyOpenRouterInvokePolicy, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
+export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv } from './openrouter-routing.js';
+export type { InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, AiToolsInvokeClient, } from '@x12i/ai-tools';
+/** @deprecated Use buildInvokeModelResolverOptions */
+export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): import("@x12i/ai-tools").ModelResolverOptions;
 /**
- * Per-invoke resolver options: ai-tools decides OpenRouter vs direct from env + optional gateway prefer override.
+ * @deprecated Use mapResolutionToRouterConfig from @x12i/ai-tools
  */
-export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): ModelResolverOptions;
+export declare function applyModelResolution(merged: {
+    provider?: string;
+    model?: string;
+}, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string, inputModel?: string): void;
 /**
  * Returns catalog + calculator, or null when disabled or bootstrap fails.
  */
 export declare function getAiToolsClient(config: GatewayConfig, logger: Logxer): Promise<AiToolsClientBundle | null>;
 /** Reset singleton (tests). */
 export declare function resetAiToolsClientForTests(): void;
-/**
- * Map catalog resolution to router `{ provider, model }` (agnostic to openrouter vs vendor input).
- */
-export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string, inputModel?: string): void;
-type RouterConfigSlice = {
-    provider?: string;
-    model?: string;
-    allowOpenRouterProxy?: boolean;
-    providerProxy?: string;
-};
-type ModelResolutionMeta = {
-    routedViaOpenRouter?: boolean;
-};
-/**
- * Router invoke flags after mergeConfig + ai-tools resolution (OpenRouter vs direct transport).
- */
-export declare function applyOpenRouterInvokePolicy(merged: RouterConfigSlice, options: {
-    openRouterApiKey?: string;
-    preferOpenRouter?: boolean;
-    routingEnv?: OpenRouterRoutingConfig;
-    resolution?: ModelResolutionMeta;
-}): void;
-export {};

package/dist-cjs/gateway-utils.cjs

@@ -4,11 +4,10 @@
  */
 import * as crypto from 'crypto';
 import { FallbackExhaustedError } from '@x12i/ai-providers-router';
-import { ModelResolutionError, isKnownProfileOrShortcut } 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,62 @@ 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,
+            });
+            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();
     }
@@ -679,31 +696,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 (isKnownProfileOrShortcut(explicitModel)) {
-        return new ModelProfileUnroutableError(explicitModel, provider, base);
-    }
-    return base;
-}
 /**
  * Build rejection-metadata fallback attempts from trace-mode {@link GatewayTraceAttempt}s.
  */
@@ -772,7 +764,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 +772,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-cjs/gateway-utils.d.ts

@@ -16,7 +16,10 @@ export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer):
 export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
+    openRouterApiKey?: string;
+    preferOpenRouter?: boolean;
 };
+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
@@ -149,14 +152,6 @@ export declare function pickEffectiveModelConfigFromInvokeRequest(request: Pick<
  */
 export declare function tryExtractRouterLikePayloadFromErrorChain(error: unknown, maxDepth?: number): unknown;
 export declare function pickRequestIdsFromRouterLike(gatewayAiRequestId: string | undefined, routerLike: unknown): GatewayTraceRequestIds | undefined;
-/** Error code hint when a bundled profile name cannot be routed to a catalog target. */
-export declare const MODEL_PROFILE_UNROUTABLE = "MODEL_PROFILE_UNROUTABLE";
-export declare class ModelProfileUnroutableError extends Error {
-    readonly profileAlias: string;
-    readonly provider: string | undefined;
-    readonly code = "MODEL_PROFILE_UNROUTABLE";
-    constructor(profileAlias: string, provider: string | undefined, cause?: unknown);
-}
 type ModelResolutionCandidate = {
     provider: string;
     model: string;
@@ -175,7 +170,7 @@ export declare function mapGatewayFallbackAttemptsToRouter(attempts: GatewayFall
     responsePreview?: string;
 }>;
 /**
- * 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 declare function logResolvedModelRouting(logger: Logxer, request: ChatRequest, mergedConfig: ChatRequest['config']): void;
 /**

package/dist-cjs/gateway.cjs

@@ -14,7 +14,6 @@ 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, 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);
@@ -292,14 +287,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';

package/dist-cjs/index.cjs

@@ -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, 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-cjs/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, 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-cjs/openrouter-routing.cjs

@@ -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();
 }