@x12i/ai-gateway 10.0.7 → 10.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @x12i/ai-gateway
 
-Unified gateway for LLM provider routing, structured logging, optional Activix activity persistence, and cost/model resolution via **@x12i/ai-tools** v2. Built on **@x12i/ai-providers-router**, **@x12i/logxer**, **@x12i/rendrix** (templates), and **@x12i/flex-md** (output-format hints and max-token lookup).
+Unified gateway for LLM provider routing, structured logging, optional Activix activity persistence, and cost/model resolution via **@x12i/ai-tools** v3. Built on **@x12i/ai-providers-router**, **@x12i/logxer**, **@x12i/rendrix** (templates), and **@x12i/flex-md** (output-format hints and max-token lookup).
 
 ## What this package does
 
@@ -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.5**, **ai-tools ^2.5**, **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,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`** 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`.
+- **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`**.
 - **`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.
 
@@ -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`.
 
@@ -184,7 +184,8 @@ Instructions must be **complete caller text** — the gateway no longer injects
 
 | Variable | Role |
 |----------|------|
-| `MONGO_URI`, `MONGO_LOGS_DB` / `MONGO_DB` | Activix when no custom tracker |
+| `MONGO_URI`, `MONGO_LOGS_DB` / `MONGO_DB` / `MONGO_AI_LOGS_DB` | Activix when no custom tracker |
+| `ACTIVIX_DB_NAME` | Activix database override (falls back to `MONGO_AI_LOGS_DB` → `MONGO_LOGS_DB` → `MONGO_DB`) |
 | `mode` / `MODE` | Operational mode (`dev`, `debug`, `prod`) — expose to downstream clients |
 | `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`) |
@@ -209,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.
 
@@ -233,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`, …) |
@@ -241,13 +256,13 @@ 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` ≥ **2.5.0** (`resolveInvokeModel`, …).
+Gateway exports the model orchestrator from `@x12i/ai-tools` ≥ **3.0.0** (`resolveInvokeModel`, `useOpenRouter`, …). 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`.
 
 ---
 
-## Activity tracking (@x12i/activix 8.x)
+## Activity tracking (@x12i/activix 8.6)
 
 When tracking is enabled and no custom tracker is supplied, the gateway constructs Activix with fixed collection names (see `src/config/activity-tracking-config.ts`):
 
@@ -261,12 +276,14 @@ When tracking is enabled and no custom tracker is supplied, the gateway construc
 
 **Successful completion** (no duplicate billing on `outer.metadata`):
 
-- Root: `cost`, `costUsd`, `costStatus`, **`metadata`** (routing + billing mirror for Activix 7.x)
+- Root: `cost`, `costUsd`, `costStatus`, **`metadata`** (routing + billing mirror; **`metadata.modelUsed`** for studio)
 - `outer.metadata`: routing only (`modelUsed`, `provider`, …)
 - `outer.cost`: Activix cost shape (`usd`, `tokens`, `provider`, `model`, `details`)
 - `response.metadata`: same billing slice as returned to callers
 
-Gateway resolves billing **before** `completeRecord` and sets **`outer.cost`** from that slice. Activix **`autoCost`** is **not** used on the default activity manager (no second pricing path).
+Activix **8.6** runs **`materializeRecordRoutingAndBilling`** on persist (root **`config`** mirror from routing metadata). Gateway resolves billing **before** `completeRecord` and sets **`outer.cost`** from that slice.
+
+**`autoCost`:** Activix 8.6 default is **`false`**. The gateway keeps **`autoCost: false`** on the default activity manager so billing is not recomputed via ai-tools at persist time (no second pricing path). Custom **`activityTracker`** instances may opt in to Activix **`autoCost`** (uses **@x12i/ai-tools** v3 **`calculateFromRecord`** when enabled).
 
 Mongo env: `MONGO_URI` + `MONGO_LOGS_DB` or `MONGO_DB`.
 
@@ -314,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).
 
 ---
 
@@ -329,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.
 
 ---
 

package/dist/activity-manager.d.ts

@@ -32,8 +32,8 @@ export interface ActivityManagerConfig {
     customTracker?: Activix;
     logger: Logxer;
     /**
-     * Activix 7.2+ {@link ActivixAutoCostOptions}: fill `outer.cost` via @x12i/ai-tools when the gateway
-     * did not supply a valid cost. Ignored when `customTracker` is provided.
+     * Activix 8.6+ {@link ActivixAutoCostOptions}: optional persist-time cost via @x12i/ai-tools v3.
+     * Default gateway manager leaves this off — billing is set before completeRecord.
      */
     autoCost?: boolean | ActivixAutoCostOptions;
 }

package/dist/activity-manager.js

@@ -165,7 +165,7 @@ function pickActivixUsageTokens(response) {
     };
 }
 /**
- * Activix 7.x `outer.cost` from gateway billing + routing (Run Analysis G8).
+ * Activix 8.x `outer.cost` from gateway billing + routing (Run Analysis G8).
  * Uses Activix {@link normalizeToActivixCostShape} so the shape matches package validators.
  */
 function buildActivixOuterCost(routingMeta, billing, response) {
@@ -193,7 +193,7 @@ function buildActivixOuterCost(routingMeta, billing, response) {
     };
     return normalizeToActivixCostShape(candidate, 'gateway.outer.cost') ?? undefined;
 }
-/** Run-level record metadata (Activix 7.x top-level `metadata`, sibling to `outer`). */
+/** Run-level record metadata (Activix 8.x top-level `metadata`, sibling to `outer`). */
 function buildActivixRecordMetadata(response, billing) {
     const out = {
         ...pickActivixCompletionRoutingMetadata(response)

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

@@ -6,8 +6,10 @@ import { type AiToolsInvokeClient, type ModelResolutionSuccess, type OpenRouterR
 import type { Logxer } from '@x12i/logxer';
 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 { 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 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,9 +4,11 @@
  */
 import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-import { resolvePreferOpenRouter } from './openrouter-routing.js';
-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';
+import { resolveUseOpenRouter } 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';
 let bootstrapFailedLogged = false;
 function invokeClientOptions(config) {
     return {
@@ -26,7 +28,8 @@ function withCatalogLaneCalculator(client, config) {
             ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
             resolverOptions: buildInvokeModelResolverOptions({
                 routingEnv: client.routingEnv,
-                catalogLane: lane
+                catalogLane: lane,
+                useOpenRouter: resolveUseOpenRouter(config),
             })
         })
     };
@@ -35,7 +38,7 @@ function withCatalogLaneCalculator(client, config) {
 export function buildModelResolverOptions(config, routingEnv) {
     return buildInvokeModelResolverOptions({
         routingEnv,
-        preferOpenRouter: resolvePreferOpenRouter(config),
+        useOpenRouter: resolveUseOpenRouter(config),
     });
 }
 /**

package/dist/gateway-config.d.ts

@@ -37,6 +37,6 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     activityManager: ActivityManager;
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
-    preferOpenRouter: boolean;
+    useOpenRouter: 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, resolvePreferOpenRouter, } from './openrouter-routing.js';
+import { resolveOpenRouterApiKey, resolveUseOpenRouter, } 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 preferOpenRouter = resolvePreferOpenRouter(config);
+    const useOpenRouter = resolveUseOpenRouter(config);
     if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
         routerConfig.openRouter = {
             enabled: true,
-            prefer: preferOpenRouter,
+            prefer: useOpenRouter,
         };
-        if (preferOpenRouter) {
+        if (useOpenRouter) {
             routerConfig.defaultMode = 'openrouter';
         }
     }
@@ -190,7 +190,7 @@ export function initializeGatewayComponents(config) {
         activityManager,
         usageTracker,
         messageBuilderConfig,
-        preferOpenRouter,
+        useOpenRouter,
         openRouterApiKey: openRouterKey,
     };
 }

package/dist/gateway-utils.d.ts

@@ -17,7 +17,7 @@ export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
     openRouterApiKey?: string;
-    preferOpenRouter?: boolean;
+    useOpenRouter?: 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, {
+        useOpenRouter: mergeOptions?.useOpenRouter,
+    });
+    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,
-                preferOpenRouter: mergeOptions.preferOpenRouter,
+                useOpenRouter: mergeOptions.useOpenRouter,
                 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,
-            preferOpenRouter: mergeOptions.preferOpenRouter,
+            useOpenRouter: mergeOptions.useOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;
@@ -512,7 +529,14 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         options?.calculator &&
         hasNonZeroTokenUsage(tokens)) {
         try {
-            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const record = routerResponse != null && typeof routerResponse === 'object'
+                ? {
+                    ...routerResponse,
+                    ...(options.mergedConfig != null ? { config: options.mergedConfig } : {})
+                }
+                : options.mergedConfig != null
+                    ? { config: options.mergedConfig, metadata: { tokens } }
+                    : { metadata: { tokens } };
             const result = await options.calculator.calculateFromRecord(record);
             billing = mapAiCostResultToResolvedActivityCost(billing, result);
         }

package/dist/gateway.d.ts

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

package/dist/gateway.js

@@ -59,7 +59,7 @@ export class AIGateway {
     messageBuilderConfig;
     _autoRegisterDone = false;
     _aiToolsClient = null;
-    preferOpenRouter;
+    useOpenRouter;
     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.preferOpenRouter = components.preferOpenRouter;
+        this.useOpenRouter = components.useOpenRouter;
         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,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             // 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,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             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';
@@ -40,8 +41,8 @@ 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';
+/** 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 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';
@@ -33,8 +34,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 @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';
 // 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 = {
+    useOpenRouter?: 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',
+            useOpenRouter: options.useOpenRouter,
+        }, { useOpenRouter: options.useOpenRouter });
+        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,8 +1,16 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
 import type { GatewayConfig } from './types.js';
-export { readPreferOpenRouterFromEnv };
+export { readUseOpenRouterFromEnv };
 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`.
+ */
+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,12 +1,17 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv, resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouter as resolvePreferFromTools, } from '@x12i/ai-tools';
-export { readPreferOpenRouterFromEnv };
+import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolveUseOpenRouterPreference, } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
+export { readUseOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
     return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
-export function resolvePreferOpenRouter(config = {}) {
+/**
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ */
+export function resolveUseOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
     if (config.openRouter?.prefer === false)
@@ -15,5 +20,13 @@ export function resolvePreferOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    return resolvePreferFromTools();
+    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;
 }

package/dist-cjs/activity-manager.cjs

@@ -165,7 +165,7 @@ function pickActivixUsageTokens(response) {
     };
 }
 /**
- * Activix 7.x `outer.cost` from gateway billing + routing (Run Analysis G8).
+ * Activix 8.x `outer.cost` from gateway billing + routing (Run Analysis G8).
  * Uses Activix {@link normalizeToActivixCostShape} so the shape matches package validators.
  */
 function buildActivixOuterCost(routingMeta, billing, response) {
@@ -193,7 +193,7 @@ function buildActivixOuterCost(routingMeta, billing, response) {
     };
     return normalizeToActivixCostShape(candidate, 'gateway.outer.cost') ?? undefined;
 }
-/** Run-level record metadata (Activix 7.x top-level `metadata`, sibling to `outer`). */
+/** Run-level record metadata (Activix 8.x top-level `metadata`, sibling to `outer`). */
 function buildActivixRecordMetadata(response, billing) {
     const out = {
         ...pickActivixCompletionRoutingMetadata(response)

package/dist-cjs/activity-manager.d.ts

@@ -32,8 +32,8 @@ export interface ActivityManagerConfig {
     customTracker?: Activix;
     logger: Logxer;
     /**
-     * Activix 7.2+ {@link ActivixAutoCostOptions}: fill `outer.cost` via @x12i/ai-tools when the gateway
-     * did not supply a valid cost. Ignored when `customTracker` is provided.
+     * Activix 8.6+ {@link ActivixAutoCostOptions}: optional persist-time cost via @x12i/ai-tools v3.
+     * Default gateway manager leaves this off — billing is set before completeRecord.
      */
     autoCost?: boolean | ActivixAutoCostOptions;
 }

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

@@ -4,9 +4,11 @@
  */
 import { getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, CostCalculator, } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
-import { resolvePreferOpenRouter } from './openrouter-routing.js';
-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';
+import { resolveUseOpenRouter } 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';
 let bootstrapFailedLogged = false;
 function invokeClientOptions(config) {
     return {
@@ -26,7 +28,8 @@ function withCatalogLaneCalculator(client, config) {
             ...(config.aiTools?.costIncludeBreakdown ? { includeBreakdown: true } : {}),
             resolverOptions: buildInvokeModelResolverOptions({
                 routingEnv: client.routingEnv,
-                catalogLane: lane
+                catalogLane: lane,
+                useOpenRouter: resolveUseOpenRouter(config),
             })
         })
     };
@@ -35,7 +38,7 @@ function withCatalogLaneCalculator(client, config) {
 export function buildModelResolverOptions(config, routingEnv) {
     return buildInvokeModelResolverOptions({
         routingEnv,
-        preferOpenRouter: resolvePreferOpenRouter(config),
+        useOpenRouter: resolveUseOpenRouter(config),
     });
 }
 /**

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

@@ -6,8 +6,10 @@ import { type AiToolsInvokeClient, type ModelResolutionSuccess, type OpenRouterR
 import type { Logxer } from '@x12i/logxer';
 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 { 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 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, resolvePreferOpenRouter, } from './openrouter-routing.js';
+import { resolveOpenRouterApiKey, resolveUseOpenRouter, } 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 preferOpenRouter = resolvePreferOpenRouter(config);
+    const useOpenRouter = resolveUseOpenRouter(config);
     if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
         routerConfig.openRouter = {
             enabled: true,
-            prefer: preferOpenRouter,
+            prefer: useOpenRouter,
         };
-        if (preferOpenRouter) {
+        if (useOpenRouter) {
             routerConfig.defaultMode = 'openrouter';
         }
     }
@@ -190,7 +190,7 @@ export function initializeGatewayComponents(config) {
         activityManager,
         usageTracker,
         messageBuilderConfig,
-        preferOpenRouter,
+        useOpenRouter,
         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;
-    preferOpenRouter: boolean;
+    useOpenRouter: 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, {
+        useOpenRouter: mergeOptions?.useOpenRouter,
+    });
+    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,
-                preferOpenRouter: mergeOptions.preferOpenRouter,
+                useOpenRouter: mergeOptions.useOpenRouter,
                 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,
-            preferOpenRouter: mergeOptions.preferOpenRouter,
+            useOpenRouter: mergeOptions.useOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;
@@ -512,7 +529,14 @@ export async function resolveCostCompletionWithAiTools(routerResponse, tokens, o
         options?.calculator &&
         hasNonZeroTokenUsage(tokens)) {
         try {
-            const record = buildGatewayPricingRecord(routerResponse, tokens, options.mergedConfig);
+            const record = routerResponse != null && typeof routerResponse === 'object'
+                ? {
+                    ...routerResponse,
+                    ...(options.mergedConfig != null ? { config: options.mergedConfig } : {})
+                }
+                : options.mergedConfig != null
+                    ? { config: options.mergedConfig, metadata: { tokens } }
+                    : { metadata: { tokens } };
             const result = await options.calculator.calculateFromRecord(record);
             billing = mapAiCostResultToResolvedActivityCost(billing, result);
         }

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

@@ -17,7 +17,7 @@ export type MergeConfigOptions = {
     catalog?: AiModelsCatalogClient | null;
     routingEnv?: OpenRouterRoutingConfig;
     openRouterApiKey?: string;
-    preferOpenRouter?: boolean;
+    useOpenRouter?: 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;
-    preferOpenRouter;
+    useOpenRouter;
     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.preferOpenRouter = components.preferOpenRouter;
+        this.useOpenRouter = components.useOpenRouter;
         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,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             // 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,
-                preferOpenRouter: this.preferOpenRouter,
+                useOpenRouter: this.useOpenRouter,
             });
             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 preferOpenRouter;
+    private readonly useOpenRouter;
     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';
@@ -33,8 +34,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 @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';
 // 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';
@@ -40,8 +41,8 @@ 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';
+/** 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 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',
+            useOpenRouter: options.useOpenRouter,
+        }, { useOpenRouter: options.useOpenRouter });
+        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 = {
+    useOpenRouter?: 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,12 +1,17 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv, resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolvePreferOpenRouter as resolvePreferFromTools, } from '@x12i/ai-tools';
-export { readPreferOpenRouterFromEnv };
+import { resolveOpenRouterApiKey as resolveOpenRouterApiKeyFromTools, resolveUseOpenRouterPreference, } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
+export { readUseOpenRouterFromEnv };
 export function resolveOpenRouterApiKey(config = {}) {
     return resolveOpenRouterApiKeyFromTools(config.openrouter?.apiKey);
 }
-export function resolvePreferOpenRouter(config = {}) {
+/**
+ * Effective OpenRouter preference for invoke-time routing (ai-tools `useOpenRouter`).
+ * Constructor `openRouter.prefer` / `openRouter.enabled` override env `USE_OPENROUTER`.
+ */
+export function resolveUseOpenRouter(config = {}) {
     if (config.openRouter?.prefer === true)
         return true;
     if (config.openRouter?.prefer === false)
@@ -15,5 +20,13 @@ export function resolvePreferOpenRouter(config = {}) {
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    return resolvePreferFromTools();
+    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;
 }

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

@@ -1,8 +1,16 @@
 /**
- * Gateway-level OpenRouter key + prefer flags mapped to @x12i/ai-tools invoke helpers.
+ * Gateway-level OpenRouter key + USE_OPENROUTER flags mapped to @x12i/ai-tools v3 invoke helpers.
  */
-import { readPreferOpenRouterFromEnv } from '@x12i/ai-tools';
+import { readUseOpenRouterFromEnv } from '@x12i/ai-profiles';
 import type { GatewayConfig } from './types.js';
-export { readPreferOpenRouterFromEnv };
+export { readUseOpenRouterFromEnv };
 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`.
+ */
+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.0.7",
+  "version": "10.2.0",
   "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.5.0",
+    "@x12i/activix": "^8.6.1",
+    "@x12i/ai-profiles": "^3.2.0",
     "@x12i/ai-providers-router": "^4.9.2",
-    "@x12i/ai-tools": "^2.5.0",
+    "@x12i/ai-tools": "^3.1.0",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^4.6.0",
     "@x12i/rendrix": "^4.3.0"