@x12i/ai-gateway 10.0.1 → 10.0.4

package/README.md

@@ -13,7 +13,7 @@ Unified gateway for LLM provider routing, structured logging, optional Activix a
 | **Activix** | Optional Mongo-backed activity rows (`ai-actions`, `bad-requests`, `skill-executions`) with root billing fields and `outer` I/O. |
 | **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt billing when priced. |
 
-Pinned dependency versions are in `package.json` (currently **Activix ^7.2**, **ai-tools ^2**).
+Pinned dependency versions are in `package.json` (currently **Activix ^8.5**, **ai-tools ^2.5**, **ai-providers-router ^4.9**).
 
 ---
 
@@ -79,7 +79,7 @@ const response = await gateway.invoke({
     agentId: 'agent-456'
   },
   workingMemory: { input: 'Hello!' },
-  config: { model: 'cheap', provider: 'openrouter' }
+  config: { model: 'openai/gpt-4o-mini', provider: 'openrouter', maxTokens: 256 }
 });
 
 console.log(response.content, response.metadata?.costUsd, response.metadata?.tokens);
@@ -87,7 +87,7 @@ console.log(response.content, response.metadata?.costUsd, response.metadata?.tok
 
 ### Providers without manual `register()`
 
-- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env`. The gateway always passes this key to the router when set. **By default, OpenRouter is preferred** for routing (including when you also have direct keys such as `OPENAI_API_KEY`). **`@x12i/ai-tools` ≥ 2.1** resolves model + provider agnostically (`openrouter` + `cheap` or `openai` + `gpt-4o` — same pipeline). Profile aliases (`cheap`, `balanced`, …) set `routedViaOpenRouter` from env. You do not need `USE_OPENROUTER=true` when the key is present.
+- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env`. The gateway always passes this key to the router when set. **By default, OpenRouter is preferred** for routing (including when you also have direct keys such as `OPENAI_API_KEY`). **`@x12i/ai-tools`** resolves concrete model ids + provider via `resolveInvokeModel()` (catalog normalization, OpenRouter vs direct transport, router proxy flags). Pass catalog model ids such as `openai/gpt-4o-mini` or `gpt-4o` — not profile shortcuts (`cheapest`, `cheap/default`) unless you set `aiTools.modelsOnly: false`.
 - **`USE_OPENROUTER=false`:** Do **not** prefer OpenRouter when a direct provider API key exists — use the direct provider instead. OpenRouter is **still** used as **fallback** when the request targets a provider without a direct key (e.g. `anthropic` without `ANTHROPIC_API_KEY`). It does not disable OpenRouter while `OPENROUTER_API_KEY` is set.
 - **Direct providers:** Set `OPENAI_API_KEY`, `GROK_API_KEY`, etc. Registered lazily on first invoke.
 
@@ -188,7 +188,7 @@ Instructions must be **complete caller text** — the gateway no longer injects
 | `AI_GATEWAY_LOGS_LEVEL` | Log threshold for gateway diagnostics (`AI_GATEWAY` prefix): `error` … `verbose` |
 | `AI_GATEWAY_VERBOSE` | Full payload lines (still requires `AI_GATEWAY_LOGS_LEVEL=verbose`) |
 | `LOGXER_PACKAGE_LEVELS` | Bulk stack levels, e.g. `AI_GATEWAY:info,AI_PROVIDER_ROUTER:debug` |
-| `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for profile/OpenRouter routes) |
+| `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for OpenRouter transport) |
 | `USE_OPENROUTER` | Optional; default **prefer** OpenRouter when key is set. `false` = use direct provider keys when present; OpenRouter still used as fallback when a provider has no key |
 | Other provider keys | `OPENAI_API_KEY`, `GROK_API_KEY`, etc. |
 
@@ -212,9 +212,12 @@ Exports: `GATEWAY_LOGXER_PACKAGE`, `GATEWAY_LOG_ENV_PREFIX`, `createGatewayLogge
 
 - **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional `bundledOnly`).
 - **`aiTools.enabled`** — bootstrap catalog client + calculator.
-- **`aiTools.resolveModels`** — `mergeConfig()` resolves model ids (strict in **`mode: 'dev'`**).
+- **`aiTools.resolveModels`** — `mergeConfig()` calls `resolveInvokeModel()` (catalog + OpenRouter/direct routing).
+- **`aiTools.modelsOnly`** — **`true` by default** — reject profile shortcuts (`cheapest`, `cheap/default`, …); pass concrete model ids only.
 - **`aiTools.calculateCost`** — prices usage before Activix `completeRecord` when the router did not mark the call priced.
 
+Gateway exports the orchestrator from `@x12i/ai-tools` ≥ **2.5.0** (`resolveInvokeModel`, …) — see [AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md](./docs/upstream-reports/AI_TOOLS_INVOKE_MODEL_RESOLUTION_ORCHESTRATOR_SPEC.md).
+
 Gateway helpers (also exported): `resolveCostCompletionWithAiTools`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
 ---
@@ -276,7 +279,7 @@ Adds **`metadata.attempts`**, **`metadata.usage`**, **`metadata.requestIds`**, a
 
 Set via constructor `mode` or env `mode` / `MODE`. **Downstream hosts should document and expose `mode`** so graph/skill callers know resolution behavior.
 
-Every mode requires an explicit **`model`** on the request. Unresolved catalog profiles throw (e.g. `ModelProfileUnroutableError` in dev when profile has no routable target).
+Every mode requires an explicit **`model`** on the request (concrete catalog id when `aiTools.modelsOnly` is true). Unknown models throw `ModelResolutionError`. Profile keys only work when `aiTools.modelsOnly: false`.
 
 ---
 
@@ -291,7 +294,7 @@ Every mode requires an explicit **`model`** on the request. Unresolved catalog p
 | `npm run test:flex-md-esm-regression` | ESM build regression for flex-md |
 | `npm run test:prepublish` | `build` + `npm test` |
 
-Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `cheap`, an ai-tools profile alias). Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
+Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `openai/gpt-4o-mini`). Set `LIVE_TEST_PROFILES=1` to run legacy profile-key invokes. Set `LIVE_SKIP_INVOKE=1` to skip the LLM call.
 
 ---
 

package/dist/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/ai-tools-client.js

@@ -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/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/gateway-utils.js

@@ -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/gateway.js

@@ -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/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/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, 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;