@x12i/ai-gateway 10.1.0 → 10.2.1

package/README.md

@@ -13,7 +13,7 @@ Unified gateway for LLM provider routing, structured logging, optional Activix a
 | **Activix** | Optional Mongo-backed activity rows; billing written from gateway-computed slice on **`completeRecord`** (`outer.cost` + root fields). No Activix **`autoCost`** re-pricing. |
 | **Trace mode** | `diagnostics.mode === 'trace'` adds `metadata.attempts[]`, `metadata.usage`, and per-attempt **`costUsd`** / **`costStatus`**. |
 
-Pinned dependency versions are in `package.json` (currently **Activix ^8.6**, **ai-tools ^3.0**, **ai-providers-router ^4.9**).
+Pinned dependency versions are in `package.json` (currently **Activix ^8.6**, **ai-tools ^3.1**, **ai-profiles ^3.2**, **ai-providers-router ^4.9**).
 
 ---
 
@@ -87,8 +87,8 @@ 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`** 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.
+- **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 `{ provider: 'openrouter', model: 'deepseek/deepseek-v4-pro' }`. Composite display slugs like `openrouter/deepseek/deepseek-v4-pro` are split at ingress (see **Invoke model ingress** below). Profile/choice aliases (`cheap/default`, …) must be resolved upstream (ai-tasks / `resolveAIProfile`) — the gateway rejects them with **`GATEWAY_ALIAS_MODEL_REJECTED`**.
+- **`PREFER_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.
 
 Details: [OpenRouter env](./docs/OPENROUTER_ENV.md).
@@ -146,7 +146,7 @@ import {
 } from '@x12i/ai-gateway';
 ```
 
-**Required on every invoke:** `config.model` (or `modelConfig.model`) and `maxTokens` (`request.config`, `modelConfig`, `GatewayConfig`, or `internalSystemActions`). Missing model → `ModelRequiredError` (`code: 'MODEL_REQUIRED'`). Missing `maxTokens` → `MaxTokensRequiredError` (`code: 'MAX_TOKENS_REQUIRED'`). There is **no** packaged default model, **no** flex-md / Optimixer auto-fill, and **no** `GATEWAY_DEFAULT_MAX_TOKENS`. Use [@x12i/optimixer](https://www.npmjs.com/package/@x12i/optimixer) in the **client** that wraps this gateway if you want adaptive completion budgets.
+**Required on every invoke:** `config.model` (or `modelConfig.model`) and `maxTokens` (`request.config`, `modelConfig`, `GatewayConfig`, or `internalSystemActions`). Missing model → `ModelRequiredError` (`code: 'MODEL_REQUIRED'`). Missing `maxTokens` → `MaxTokensRequiredError` (`code: 'MAX_TOKENS_REQUIRED'`). Profile/choice alias at invoke → `GatewayAliasModelRejectedError` (`code: 'GATEWAY_ALIAS_MODEL_REJECTED'`). There is **no** packaged default model, **no** flex-md / Optimixer auto-fill, and **no** `GATEWAY_DEFAULT_MAX_TOKENS`. Use [@x12i/optimixer](https://www.npmjs.com/package/@x12i/optimixer) in the **client** that wraps this gateway if you want adaptive completion budgets.
 
 **Rate limiting:** removed from the gateway. See [upstream rate-limit spec](./docs/upstream-reports/AI_PROVIDER_ROUTER_RATE_LIMITING.md) — implement in `@x12i/ai-providers-router`.
 
@@ -191,7 +191,7 @@ Instructions must be **complete caller text** — the gateway no longer injects
 | `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 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 |
+| `PREFER_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. |
 
 Logging details: [Logger initialization](./docs/LOGGER_INITIALIZATION.md). Package identity and audit checklist: [LOGXER_INTEGRATION_CHECKLIST.md](./docs/LOGXER_INTEGRATION_CHECKLIST.md).
@@ -210,7 +210,21 @@ Exports: `GATEWAY_LOGXER_PACKAGE`, `GATEWAY_LOG_ENV_PREFIX`, `createGatewayLogge
 
 ---
 
-## @x12i/ai-tools v2 (models + cost)
+## Invoke model ingress (v10.2+)
+
+Before catalog lookup, **`mergeConfig()`** normalizes the invoke wire shape via **`normalizeInvokeModel`** from **`@x12i/ai-profiles`** (defense in depth — idempotent when upstream already fixed):
+
+| Input | Result |
+|-------|--------|
+| `model: 'openrouter/deepseek/deepseek-v4-pro'`, `provider: 'unspecified'` | `{ provider: 'openrouter', model: 'deepseek/deepseek-v4-pro' }` → catalog lookup |
+| `{ provider: 'openrouter', model: 'deepseek/deepseek-v4-pro' }` | Pass-through unchanged |
+| `model: 'cheap/default'` (profile/choice alias) | **`GATEWAY_ALIAS_MODEL_REJECTED`** — resolve upstream via ai-tasks / `resolveAIProfile` |
+
+Exported helpers: `normalizeInvokeModelAtIngress`, `GatewayAliasModelRejectedError`.
+
+---
+
+## @x12i/ai-tools v3 (models + cost)
 
 Engine-owned catalog bootstrap and post-call billing. Consumers read **`metadata.costUsd`** / **`costStatus`** only — no direct `@x12i/ai-tools` dependency for cost.
 
@@ -234,7 +248,7 @@ Implemented in **`resolveCostCompletionWithAiTools`** only ( **`CostCalculator.c
 | **`enabled`** | `true` | Bootstrap **`AiModelsCatalogClient`** + **`CostCalculator`** |
 | **`calculateCost`** | `true` | Run post-call catalog pricing when router did not price |
 | **`resolveModels`** | `true` | **`mergeConfig()`** → **`resolveInvokeModel()`** |
-| **`modelsOnly`** | `true` | Reject profile shortcuts (`cheapest`, `cheap/default`, …) |
+| **`modelsOnly`** | `true` | Reject profile shortcuts at catalog resolution (`cheapest`, …). Aliases are **always** rejected at ingress regardless of this flag. |
 | **`bundledOnly`** | `false` | Offline bundled catalogs only |
 | **`costIncludeBreakdown`** | `false` | Include prompt/completion breakdown on priced results |
 | **`catalogLane`** | `"text"` (ai-tools default) | Catalog lane for resolution + cost lookup (`text`, `image`, …) |
@@ -242,7 +256,7 @@ Implemented in **`resolveCostCompletionWithAiTools`** only ( **`CostCalculator.c
 
 - **No Catalox / Firestore** — catalogs come from ai-tools open-assets JSON (optional **`bundledOnly`**).
 
-Gateway exports the model orchestrator from `@x12i/ai-tools` ≥ **3.0.0** (`resolveInvokeModel`, `useOpenRouter`, …). v3 requires **`profile/choice`** keys (e.g. `cheap/default`) or concrete catalog ids — shortcuts like `cheapest` / bare `cheap` are rejected.
+Gateway exports the model orchestrator from `@x12i/ai-tools` ≥ **3.3.0** (`resolveInvokeModel`, `preferOpenRouter`, …). Profile/choice keys (`cheap/default`, …) must be resolved **before** invoke — the gateway does not run alias resolution. Shortcuts like `cheapest` / bare `cheap` are rejected at ingress or catalog resolution.
 
 Gateway billing helpers (exported for tests/integrators): `resolveCostCompletionWithAiTools`, `buildGatewayPricingRecord`, `catalogPricingSucceeded`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
@@ -317,7 +331,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 (concrete catalog id when `aiTools.modelsOnly` is true). Unknown models throw `ModelResolutionError`. Profile keys only work when `aiTools.modelsOnly: false`.
+Every mode requires an explicit **`model`** on the request (concrete catalog id or normalized OpenRouter slug). Unknown models throw `ModelResolutionError`. Profile/choice aliases throw `GatewayAliasModelRejectedError` at ingress — resolve them upstream (ai-tasks).
 
 ---
 
@@ -332,7 +346,7 @@ Every mode requires an explicit **`model`** on the request (concrete catalog id
 | `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` + `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.
+Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` + `openai/gpt-4o-mini`). Set `LIVE_SKIP_INVOKE=1` to skip the LLM call. Profile alias invokes (`LIVE_TEST_PROFILES=1`) are **no longer supported** — resolve profiles upstream (ai-tasks) before calling the gateway.
 
 ---
 
@@ -344,7 +358,7 @@ Full index: **[docs/README.md](./docs/README.md)**. Upstream gaps: **[docs/upstr
 |----------|--------|
 | [AI_GATEWAY_INVOKE_EXECUTION_METADATA.md](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md) | Metadata, cost, trace, Activix completion |
 | [IDENTITY_OBJECT_CONTRACT.md](./docs/IDENTITY_OBJECT_CONTRACT.md) | Identity / `runContext` |
-| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `USE_OPENROUTER` |
+| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `PREFER_OPENROUTER` |
 | [UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md](./docs/UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md) | Profile routing + OpenRouter fallback |
 | [UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md](./docs/UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md) | Parser v4 + `template-rendering.json` |
 | [GRAPH_EXECUTION_SUPPORT.md](./docs/GRAPH_EXECUTION_SUPPORT.md) | Graph / node identity |

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

@@ -9,7 +9,7 @@ export type AiToolsClientBundle = AiToolsInvokeClient;
 export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
 export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
+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;

package/dist/ai-tools-client.js

@@ -4,11 +4,11 @@
  */
 import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-import { resolveUseOpenRouter } from './openrouter-routing.js';
+import { resolvePreferOpenRouter } from './openrouter-routing.js';
 export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
 export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
+export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 let bootstrapFailedLogged = false;
 function invokeClientOptions(config) {
     return {
@@ -29,7 +29,7 @@ function withCatalogLaneCalculator(client, config) {
             resolverOptions: buildInvokeModelResolverOptions({
                 routingEnv: client.routingEnv,
                 catalogLane: lane,
-                useOpenRouter: resolveUseOpenRouter(config),
+                preferOpenRouter: resolvePreferOpenRouter(config),
             })
         })
     };
@@ -38,7 +38,7 @@ function withCatalogLaneCalculator(client, config) {
 export function buildModelResolverOptions(config, routingEnv) {
     return buildInvokeModelResolverOptions({
         routingEnv,
-        useOpenRouter: resolveUseOpenRouter(config),
+        preferOpenRouter: resolvePreferOpenRouter(config),
     });
 }
 /**

package/dist/gateway-config.d.ts

@@ -37,6 +37,6 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
-    useOpenRouter: boolean;
+    preferOpenRouter: boolean;
     openRouterApiKey?: string;
 };

package/dist/gateway-config.js

@@ -5,7 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { resolveOpenRouterApiKey, resolveUseOpenRouter, } from './openrouter-routing.js';
+import { resolveOpenRouterApiKey, resolvePreferOpenRouter, } from './openrouter-routing.js';
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
@@ -154,14 +154,14 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     const openRouterKey = resolveOpenRouterApiKey(config);
-    const useOpenRouter = resolveUseOpenRouter(config);
+    const preferOpenRouter = resolvePreferOpenRouter(config);
     if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
         routerConfig.openRouter = {
             enabled: true,
-            prefer: useOpenRouter,
+            prefer: preferOpenRouter,
         };
-        if (useOpenRouter) {
+        if (preferOpenRouter) {
             routerConfig.defaultMode = 'openrouter';
         }
     }
@@ -190,7 +190,7 @@ export function initializeGatewayComponents(config) {
         activityManager,
         usageTracker,
         messageBuilderConfig,
-        useOpenRouter,
+        preferOpenRouter,
         openRouterApiKey: openRouterKey,
     };
 }

package/dist/gateway-utils.d.ts

@@ -17,7 +17,7 @@ export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
     openRouterApiKey?: string;
-    useOpenRouter?: boolean;
+    preferOpenRouter?: boolean;
 };
 export { MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, } from '@x12i/ai-tools';
 /**

package/dist/gateway-utils.js

@@ -7,7 +7,8 @@ import { FallbackExhaustedError } from '@x12i/ai-providers-router';
 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 { MaxTokensRequiredError, ModelRequiredError, } from './instruction-errors.js';
+import { normalizeInvokeModelAtIngress } from './invoke-model-ingress.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 ?? '';
@@ -93,18 +94,34 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         provider: modelConfigAsConfig?.provider || request.config?.provider || internalDefaults?.engine || config.defaultEngine
     };
     const explicitModel = merged.model;
-    const originalProvider = merged.provider;
-    const originalModel = explicitModel;
+    let originalProvider = merged.provider;
+    let originalModel = explicitModel;
     if (!explicitModel) {
         throw new ModelRequiredError();
     }
+    const ingress = normalizeInvokeModelAtIngress(merged.provider, explicitModel, {
+        preferOpenRouter: mergeOptions?.preferOpenRouter,
+    });
+    if (ingress.changed) {
+        logger.verbose('Invoke model normalized at ingress', {
+            jobId: request.identity.jobId,
+            originalProvider,
+            originalModel,
+            provider: ingress.provider,
+            model: ingress.model,
+        });
+    }
+    merged.provider = ingress.provider;
+    merged.model = ingress.model;
+    originalProvider = merged.provider;
+    originalModel = merged.model;
     if (resolveModels && mergeOptions?.catalog) {
         try {
-            const resolved = await resolveInvokeModel({ provider: merged.provider, model: explicitModel }, {
+            const resolved = await resolveInvokeModel({ provider: merged.provider, model: merged.model }, {
                 catalog: mergeOptions.catalog,
                 routingEnv: mergeOptions.routingEnv,
                 openRouterApiKey: mergeOptions.openRouterApiKey,
-                useOpenRouter: mergeOptions.useOpenRouter,
+                preferOpenRouter: mergeOptions.preferOpenRouter,
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
@@ -142,11 +159,11 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         }
     }
     else if (mergeOptions?.openRouterApiKey) {
-        const resolved = await resolveInvokeModel({ provider: merged.provider, model: explicitModel }, {
+        const resolved = await resolveInvokeModel({ provider: merged.provider, model: merged.model }, {
             resolveModels: false,
             routingEnv: mergeOptions.routingEnv,
             openRouterApiKey: mergeOptions.openRouterApiKey,
-            useOpenRouter: mergeOptions.useOpenRouter,
+            preferOpenRouter: mergeOptions.preferOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;

package/dist/gateway.d.ts

@@ -18,7 +18,7 @@ export declare class AIGateway {
     private messageBuilderConfig?;
     private _autoRegisterDone;
     private _aiToolsClient;
-    private readonly useOpenRouter;
+    private readonly preferOpenRouter;
     private readonly openRouterApiKey?;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**

package/dist/gateway.js

@@ -59,7 +59,7 @@ export class AIGateway {
     messageBuilderConfig;
     _autoRegisterDone = false;
     _aiToolsClient = null;
-    useOpenRouter;
+    preferOpenRouter;
     openRouterApiKey;
     constructor(config = {}, activityManager) {
         this.config = config;
@@ -69,7 +69,7 @@ export class AIGateway {
         this.router = components.router;
         this.activityManager = components.activityManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
-        this.useOpenRouter = components.useOpenRouter;
+        this.preferOpenRouter = components.preferOpenRouter;
         this.openRouterApiKey = components.openRouterApiKey;
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
@@ -100,7 +100,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                useOpenRouter: this.useOpenRouter,
+                preferOpenRouter: this.preferOpenRouter,
             });
             // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
             request._mergedRouterConfig = mergedConfig;
@@ -288,7 +288,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                useOpenRouter: this.useOpenRouter,
+                preferOpenRouter: this.preferOpenRouter,
             });
             request._mergedRouterConfig = mergedConfig;
             logResolvedModelRouting(this.logger, request, mergedConfig);

package/dist/index.d.ts

@@ -14,7 +14,8 @@ export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers
 export type { UsageTracker } from '@x12i/ai-providers-router';
 export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
-export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
+export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, } from './instruction-errors.js';
+export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.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, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
@@ -41,7 +42,7 @@ export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFI
 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 (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, 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';

package/dist/index.js

@@ -15,7 +15,8 @@ export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-provider
 export * from '@x12i/ai-providers-router';
 // Export enhanced gateway
 export { AIGateway } from './gateway.js';
-export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
+export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, } from './instruction-errors.js';
+export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, 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';
@@ -34,7 +35,7 @@ export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-fact
 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 (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, 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/instruction-errors.d.ts

@@ -9,6 +9,11 @@ export declare class MaxTokensRequiredError extends Error {
     readonly code = "MAX_TOKENS_REQUIRED";
     constructor(message?: string);
 }
+export declare class GatewayAliasModelRejectedError extends Error {
+    readonly aliasModel: string;
+    readonly code = "GATEWAY_ALIAS_MODEL_REJECTED";
+    constructor(aliasModel: string, message?: string);
+}
 export declare class InstructionNotFoundError extends Error {
     key: string;
     backend: string;

package/dist/instruction-errors.js

@@ -15,6 +15,16 @@ export class MaxTokensRequiredError extends Error {
         this.name = 'MaxTokensRequiredError';
     }
 }
+export class GatewayAliasModelRejectedError extends Error {
+    aliasModel;
+    code = 'GATEWAY_ALIAS_MODEL_REJECTED';
+    constructor(aliasModel, message) {
+        super(message ??
+            `Profile/choice alias "${aliasModel}" cannot be used at invoke ingress. Resolve the alias upstream (ai-tasks / resolveAIProfile) before calling the gateway.`);
+        this.aliasModel = aliasModel;
+        this.name = 'GatewayAliasModelRejectedError';
+    }
+}
 export class InstructionNotFoundError extends Error {
     key;
     backend;

package/dist/invoke-model-ingress.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Invoke model ingress normalization (@x12i/ai-profiles `normalizeInvokeModel`).
+ * Defense in depth before catalog lookup / `resolveInvokeModel`.
+ */
+export type InvokeModelIngressOptions = {
+    preferOpenRouter?: boolean;
+};
+export type InvokeModelIngressResult = {
+    provider: string;
+    model: string;
+    changed: boolean;
+};
+/**
+ * Normalizes invoke wire shape at gateway ingress. Idempotent when upstream already fixed.
+ * Rejects profile/choice aliases — callers must resolve via ai-tasks / `resolveAIProfile`.
+ */
+export declare function normalizeInvokeModelAtIngress(provider: string | undefined, model: string, options?: InvokeModelIngressOptions): InvokeModelIngressResult;

package/dist/invoke-model-ingress.js

@@ -0,0 +1,56 @@
+/**
+ * Invoke model ingress normalization (@x12i/ai-profiles `normalizeInvokeModel`).
+ * Defense in depth before catalog lookup / `resolveInvokeModel`.
+ */
+import { AIProfilesError, normalizeInvokeModel } from '@x12i/ai-profiles';
+import { GatewayAliasModelRejectedError } from './instruction-errors.js';
+function looksLikeOpenRouterCompositeSlug(model, provider) {
+    const trimmed = model.trim();
+    if (trimmed.startsWith('openrouter/'))
+        return true;
+    const providerHint = provider?.trim().toLowerCase();
+    if ((!providerHint || providerHint === 'unspecified') && trimmed.includes('/')) {
+        return true;
+    }
+    return false;
+}
+function augmentShapeInvalidMessage(err, model, provider) {
+    if (err.code !== 'INVOKE_MODEL_SHAPE_INVALID')
+        return err;
+    if (!looksLikeOpenRouterCompositeSlug(model, provider))
+        return err;
+    return new AIProfilesError(err.code, `${err.message} Model looks like openrouter/vendor/model composite — split into provider + model.`, err.details);
+}
+/**
+ * Normalizes invoke wire shape at gateway ingress. Idempotent when upstream already fixed.
+ * Rejects profile/choice aliases — callers must resolve via ai-tasks / `resolveAIProfile`.
+ */
+export function normalizeInvokeModelAtIngress(provider, model, options = {}) {
+    const inputProvider = provider?.trim();
+    const inputModel = model.trim();
+    try {
+        const normalized = normalizeInvokeModel({
+            model: inputModel,
+            provider: inputProvider,
+            routing: 'auto',
+            preferOpenRouter: options.preferOpenRouter,
+        }, { preferOpenRouter: options.preferOpenRouter });
+        const changed = normalized.provider !== (inputProvider?.toLowerCase() ?? inputProvider) ||
+            normalized.model !== inputModel;
+        return {
+            provider: normalized.provider,
+            model: normalized.model,
+            changed,
+        };
+    }
+    catch (err) {
+        if (err instanceof AIProfilesError) {
+            if (err.code === 'INVOKE_MODEL_ALIAS_AT_GATEWAY') {
+                const alias = typeof err.details?.model === 'string' ? err.details.model : inputModel;
+                throw new GatewayAliasModelRejectedError(alias);
+            }
+            throw augmentShapeInvalidMessage(err, inputModel, inputProvider);
+        }
+        throw err;
+    }
+}

package/dist/openrouter-routing.d.ts

@@ -1,16 +1,12 @@
 /**
- * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
+ * Gateway-level OpenRouter key + PREFER_OPENROUTER flags mapped to @x12i/ai-tools invoke helpers.
  */
-import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
+import { readPreferOpenRouterFromEnv } from '@x12i/ai-profiles';
 import type { GatewayConfig } from './types.js';
-export { readUseOpenRouterFromEnv };
+export { readPreferOpenRouterFromEnv };
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
 /**
- * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
- * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `preferOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `PREFER_OPENROUTER`.
  */
-export declare function resolveUseOpenRouter(config?: GatewayConfig): boolean;
-/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;
-/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
-export declare function readPreferOpenRouterFromEnv(): boolean;

package/dist/openrouter-routing.js

@@ -1,17 +1,17 @@
 /**
- * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
+ * Gateway-level OpenRouter key + PREFER_OPENROUTER flags mapped to @x12i/ai-tools invoke helpers.
  */
-import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolveUseOpenRouterPreference, } from '@x12i/ai-tools';
-import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
-export { readUseOpenRouterFromEnv };
+import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouterPreference, } from '@x12i/ai-tools';
+import { readPreferOpenRouterFromEnv } from '@x12i/ai-profiles';
+export { readPreferOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
     return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
 /**
- * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
- * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `preferOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `PREFER_OPENROUTER`.
  */
-export function resolveUseOpenRouter(config = {}) {
+export function resolvePreferOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
     if (config.openRouter?.prefer === false)
@@ -20,13 +20,5 @@ export function resolveUseOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    return resolveUseOpenRouterPreference();
-}
-/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
-export function resolvePreferOpenRouter(config = {}) {
-    return resolveUseOpenRouter(config);
-}
-/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
-export function readPreferOpenRouterFromEnv() {
-    return readUseOpenRouterFromEnv() ?? true;
+    return resolvePreferOpenRouterPreference();
 }

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

@@ -4,11 +4,11 @@
  */
 import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-import { resolveUseOpenRouter } from './openrouter-routing.js';
+import { resolvePreferOpenRouter } from './openrouter-routing.js';
 export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
 export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
+export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 let bootstrapFailedLogged = false;
 function invokeClientOptions(config) {
     return {
@@ -29,7 +29,7 @@ function withCatalogLaneCalculator(client, config) {
             resolverOptions: buildInvokeModelResolverOptions({
                 routingEnv: client.routingEnv,
                 catalogLane: lane,
-                useOpenRouter: resolveUseOpenRouter(config),
+                preferOpenRouter: resolvePreferOpenRouter(config),
             })
         })
     };
@@ -38,7 +38,7 @@ function withCatalogLaneCalculator(client, config) {
 export function buildModelResolverOptions(config, routingEnv) {
     return buildInvokeModelResolverOptions({
         routingEnv,
-        useOpenRouter: resolveUseOpenRouter(config),
+        preferOpenRouter: resolvePreferOpenRouter(config),
     });
 }
 /**

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

@@ -9,7 +9,7 @@ export type AiToolsClientBundle = AiToolsInvokeClient;
 export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
 export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
+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;

package/dist-cjs/gateway-config.cjs

@@ -5,7 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { resolveOpenRouterApiKey, resolveUseOpenRouter, } from './openrouter-routing.js';
+import { resolveOpenRouterApiKey, resolvePreferOpenRouter, } from './openrouter-routing.js';
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
 import { createGatewayLogger } from './logger-factory.js';
 import { ActivityManager } from './activity-manager.js';
@@ -154,14 +154,14 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     const openRouterKey = resolveOpenRouterApiKey(config);
-    const useOpenRouter = resolveUseOpenRouter(config);
+    const preferOpenRouter = resolvePreferOpenRouter(config);
     if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
         routerConfig.openRouter = {
             enabled: true,
-            prefer: useOpenRouter,
+            prefer: preferOpenRouter,
         };
-        if (useOpenRouter) {
+        if (preferOpenRouter) {
             routerConfig.defaultMode = 'openrouter';
         }
     }
@@ -190,7 +190,7 @@ export function initializeGatewayComponents(config) {
         activityManager,
         usageTracker,
         messageBuilderConfig,
-        useOpenRouter,
+        preferOpenRouter,
         openRouterApiKey: openRouterKey,
     };
 }

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

@@ -37,6 +37,6 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
-    useOpenRouter: boolean;
+    preferOpenRouter: boolean;
     openRouterApiKey?: string;
 };

package/dist-cjs/gateway-utils.cjs

@@ -7,7 +7,8 @@ import { FallbackExhaustedError } from '@x12i/ai-providers-router';
 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 { MaxTokensRequiredError, ModelRequiredError, } from './instruction-errors.js';
+import { normalizeInvokeModelAtIngress } from './invoke-model-ingress.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 ?? '';
@@ -93,18 +94,34 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         provider: modelConfigAsConfig?.provider || request.config?.provider || internalDefaults?.engine || config.defaultEngine
     };
     const explicitModel = merged.model;
-    const originalProvider = merged.provider;
-    const originalModel = explicitModel;
+    let originalProvider = merged.provider;
+    let originalModel = explicitModel;
     if (!explicitModel) {
         throw new ModelRequiredError();
     }
+    const ingress = normalizeInvokeModelAtIngress(merged.provider, explicitModel, {
+        preferOpenRouter: mergeOptions?.preferOpenRouter,
+    });
+    if (ingress.changed) {
+        logger.verbose('Invoke model normalized at ingress', {
+            jobId: request.identity.jobId,
+            originalProvider,
+            originalModel,
+            provider: ingress.provider,
+            model: ingress.model,
+        });
+    }
+    merged.provider = ingress.provider;
+    merged.model = ingress.model;
+    originalProvider = merged.provider;
+    originalModel = merged.model;
     if (resolveModels && mergeOptions?.catalog) {
         try {
-            const resolved = await resolveInvokeModel({ provider: merged.provider, model: explicitModel }, {
+            const resolved = await resolveInvokeModel({ provider: merged.provider, model: merged.model }, {
                 catalog: mergeOptions.catalog,
                 routingEnv: mergeOptions.routingEnv,
                 openRouterApiKey: mergeOptions.openRouterApiKey,
-                useOpenRouter: mergeOptions.useOpenRouter,
+                preferOpenRouter: mergeOptions.preferOpenRouter,
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
@@ -142,11 +159,11 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         }
     }
     else if (mergeOptions?.openRouterApiKey) {
-        const resolved = await resolveInvokeModel({ provider: merged.provider, model: explicitModel }, {
+        const resolved = await resolveInvokeModel({ provider: merged.provider, model: merged.model }, {
             resolveModels: false,
             routingEnv: mergeOptions.routingEnv,
             openRouterApiKey: mergeOptions.openRouterApiKey,
-            useOpenRouter: mergeOptions.useOpenRouter,
+            preferOpenRouter: mergeOptions.preferOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;

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

@@ -17,7 +17,7 @@ export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
     openRouterApiKey?: string;
-    useOpenRouter?: boolean;
+    preferOpenRouter?: boolean;
 };
 export { MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, } from '@x12i/ai-tools';
 /**

package/dist-cjs/gateway.cjs

@@ -59,7 +59,7 @@ export class AIGateway {
     messageBuilderConfig;
     _autoRegisterDone = false;
     _aiToolsClient = null;
-    useOpenRouter;
+    preferOpenRouter;
     openRouterApiKey;
     constructor(config = {}, activityManager) {
         this.config = config;
@@ -69,7 +69,7 @@ export class AIGateway {
         this.router = components.router;
         this.activityManager = components.activityManager;
         this.messageBuilderConfig = components.messageBuilderConfig;
-        this.useOpenRouter = components.useOpenRouter;
+        this.preferOpenRouter = components.preferOpenRouter;
         this.openRouterApiKey = components.openRouterApiKey;
         setGatewayRuntimeClients({
             activix: this.activityManager?.getTracker(),
@@ -100,7 +100,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                useOpenRouter: this.useOpenRouter,
+                preferOpenRouter: this.preferOpenRouter,
             });
             // Activix start snapshot must match what the router receives (modelConfig-only callers omit request.config.model).
             request._mergedRouterConfig = mergedConfig;
@@ -288,7 +288,7 @@ export class AIGateway {
                 catalog: aiTools?.catalog ?? null,
                 routingEnv: aiTools?.routingEnv,
                 openRouterApiKey: this.openRouterApiKey,
-                useOpenRouter: this.useOpenRouter,
+                preferOpenRouter: this.preferOpenRouter,
             });
             request._mergedRouterConfig = mergedConfig;
             logResolvedModelRouting(this.logger, request, mergedConfig);

package/dist-cjs/gateway.d.ts

@@ -18,7 +18,7 @@ export declare class AIGateway {
     private messageBuilderConfig?;
     private _autoRegisterDone;
     private _aiToolsClient;
-    private readonly useOpenRouter;
+    private readonly preferOpenRouter;
     private readonly openRouterApiKey?;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**

package/dist-cjs/index.cjs

@@ -15,7 +15,8 @@ export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-provider
 export * from '@x12i/ai-providers-router';
 // Export enhanced gateway
 export { AIGateway } from './gateway.js';
-export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
+export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, } from './instruction-errors.js';
+export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, tryExtractFallbackAttemptsFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, buildGatewayPricingRecord, mapAiCostResultToResolvedActivityCost, catalogPricingSucceeded, 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';
@@ -34,7 +35,7 @@ export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-fact
 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 (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, 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

@@ -14,7 +14,8 @@ export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers
 export type { UsageTracker } from '@x12i/ai-providers-router';
 export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
-export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError } from './instruction-errors.js';
+export { InstructionNotFoundError, InstructionBackendError, ModelRequiredError, MaxTokensRequiredError, GatewayAliasModelRejectedError, } from './instruction-errors.js';
+export { normalizeInvokeModelAtIngress } from './invoke-model-ingress.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, catalogPricingSucceeded, extractUsageExtrasFromRouterResponse, buildTraceUsageSummary, enrichTraceAttemptsWithBilling, hasNonZeroTokenUsage, MODEL_PROFILE_UNROUTABLE, ModelProfileUnroutableError, ModelProfileInputRejectedError, buildGatewayFallbackAttemptsFromTrace, formatFallbackExhaustionMessage, logResolvedModelRouting, mapGatewayFallbackAttemptsToRouter } from './gateway-utils.js';
@@ -41,7 +42,7 @@ export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFI
 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 (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, 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';

package/dist-cjs/instruction-errors.cjs

@@ -15,6 +15,16 @@ export class MaxTokensRequiredError extends Error {
         this.name = 'MaxTokensRequiredError';
     }
 }
+export class GatewayAliasModelRejectedError extends Error {
+    aliasModel;
+    code = 'GATEWAY_ALIAS_MODEL_REJECTED';
+    constructor(aliasModel, message) {
+        super(message ??
+            `Profile/choice alias "${aliasModel}" cannot be used at invoke ingress. Resolve the alias upstream (ai-tasks / resolveAIProfile) before calling the gateway.`);
+        this.aliasModel = aliasModel;
+        this.name = 'GatewayAliasModelRejectedError';
+    }
+}
 export class InstructionNotFoundError extends Error {
     key;
     backend;

package/dist-cjs/instruction-errors.d.ts

@@ -9,6 +9,11 @@ export declare class MaxTokensRequiredError extends Error {
     readonly code = "MAX_TOKENS_REQUIRED";
     constructor(message?: string);
 }
+export declare class GatewayAliasModelRejectedError extends Error {
+    readonly aliasModel: string;
+    readonly code = "GATEWAY_ALIAS_MODEL_REJECTED";
+    constructor(aliasModel: string, message?: string);
+}
 export declare class InstructionNotFoundError extends Error {
     key: string;
     backend: string;

package/dist-cjs/invoke-model-ingress.cjs

@@ -0,0 +1,56 @@
+/**
+ * Invoke model ingress normalization (@x12i/ai-profiles `normalizeInvokeModel`).
+ * Defense in depth before catalog lookup / `resolveInvokeModel`.
+ */
+import { AIProfilesError, normalizeInvokeModel } from '@x12i/ai-profiles';
+import { GatewayAliasModelRejectedError } from './instruction-errors.js';
+function looksLikeOpenRouterCompositeSlug(model, provider) {
+    const trimmed = model.trim();
+    if (trimmed.startsWith('openrouter/'))
+        return true;
+    const providerHint = provider?.trim().toLowerCase();
+    if ((!providerHint || providerHint === 'unspecified') && trimmed.includes('/')) {
+        return true;
+    }
+    return false;
+}
+function augmentShapeInvalidMessage(err, model, provider) {
+    if (err.code !== 'INVOKE_MODEL_SHAPE_INVALID')
+        return err;
+    if (!looksLikeOpenRouterCompositeSlug(model, provider))
+        return err;
+    return new AIProfilesError(err.code, `${err.message} Model looks like openrouter/vendor/model composite — split into provider + model.`, err.details);
+}
+/**
+ * Normalizes invoke wire shape at gateway ingress. Idempotent when upstream already fixed.
+ * Rejects profile/choice aliases — callers must resolve via ai-tasks / `resolveAIProfile`.
+ */
+export function normalizeInvokeModelAtIngress(provider, model, options = {}) {
+    const inputProvider = provider?.trim();
+    const inputModel = model.trim();
+    try {
+        const normalized = normalizeInvokeModel({
+            model: inputModel,
+            provider: inputProvider,
+            routing: 'auto',
+            preferOpenRouter: options.preferOpenRouter,
+        }, { preferOpenRouter: options.preferOpenRouter });
+        const changed = normalized.provider !== (inputProvider?.toLowerCase() ?? inputProvider) ||
+            normalized.model !== inputModel;
+        return {
+            provider: normalized.provider,
+            model: normalized.model,
+            changed,
+        };
+    }
+    catch (err) {
+        if (err instanceof AIProfilesError) {
+            if (err.code === 'INVOKE_MODEL_ALIAS_AT_GATEWAY') {
+                const alias = typeof err.details?.model === 'string' ? err.details.model : inputModel;
+                throw new GatewayAliasModelRejectedError(alias);
+            }
+            throw augmentShapeInvalidMessage(err, inputModel, inputProvider);
+        }
+        throw err;
+    }
+}

package/dist-cjs/invoke-model-ingress.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Invoke model ingress normalization (@x12i/ai-profiles `normalizeInvokeModel`).
+ * Defense in depth before catalog lookup / `resolveInvokeModel`.
+ */
+export type InvokeModelIngressOptions = {
+    preferOpenRouter?: boolean;
+};
+export type InvokeModelIngressResult = {
+    provider: string;
+    model: string;
+    changed: boolean;
+};
+/**
+ * Normalizes invoke wire shape at gateway ingress. Idempotent when upstream already fixed.
+ * Rejects profile/choice aliases — callers must resolve via ai-tasks / `resolveAIProfile`.
+ */
+export declare function normalizeInvokeModelAtIngress(provider: string | undefined, model: string, options?: InvokeModelIngressOptions): InvokeModelIngressResult;

package/dist-cjs/openrouter-routing.cjs

@@ -1,17 +1,17 @@
 /**
- * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
+ * Gateway-level OpenRouter key + PREFER_OPENROUTER flags mapped to @x12i/ai-tools invoke helpers.
  */
-import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolveUseOpenRouterPreference, } from '@x12i/ai-tools';
-import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
-export { readUseOpenRouterFromEnv };
+import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouterPreference, } from '@x12i/ai-tools';
+import { readPreferOpenRouterFromEnv } from '@x12i/ai-profiles';
+export { readPreferOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
     return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
 /**
- * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
- * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `preferOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `PREFER_OPENROUTER`.
  */
-export function resolveUseOpenRouter(config = {}) {
+export function resolvePreferOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
     if (config.openRouter?.prefer === false)
@@ -20,13 +20,5 @@ export function resolveUseOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    return resolveUseOpenRouterPreference();
-}
-/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
-export function resolvePreferOpenRouter(config = {}) {
-    return resolveUseOpenRouter(config);
-}
-/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
-export function readPreferOpenRouterFromEnv() {
-    return readUseOpenRouterFromEnv() ?? true;
+    return resolvePreferOpenRouterPreference();
 }

package/dist-cjs/openrouter-routing.d.ts

@@ -1,16 +1,12 @@
 /**
- * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
+ * Gateway-level OpenRouter key + PREFER_OPENROUTER flags mapped to @x12i/ai-tools invoke helpers.
  */
-import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
+import { readPreferOpenRouterFromEnv } from '@x12i/ai-profiles';
 import type { GatewayConfig } from './types.js';
-export { readUseOpenRouterFromEnv };
+export { readPreferOpenRouterFromEnv };
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
 /**
- * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
- * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `preferOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `PREFER_OPENROUTER`.
  */
-export declare function resolveUseOpenRouter(config?: GatewayConfig): boolean;
-/** @deprecated Use {@link resolveUseOpenRouter} (ai-tools v3 renamed prefer → useOpenRouter). */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;
-/** @deprecated Use {@link readUseOpenRouterFromEnv} from `@x12i/ai-profiles`. */
-export declare function readPreferOpenRouterFromEnv(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.1.0",
+  "version": "10.2.1",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -41,9 +41,10 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/activix": "^8.6.0",
+    "@x12i/activix": "^8.6.2",
+    "@x12i/ai-profiles": "^3.3.0",
     "@x12i/ai-providers-router": "^4.9.2",
-    "@x12i/ai-tools": "^3.0.0",
+    "@x12i/ai-tools": "^3.3.0",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^4.6.0",
     "@x12i/rendrix": "^4.3.0"