@x12i/ai-gateway 10.1.0 → 10.2.0

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,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`.
 
@@ -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.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`.
 
@@ -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.
 
 ---
 

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,14 +94,30 @@ 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,
@@ -142,7 +159,7 @@ 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,

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';

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';

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-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,14 +94,30 @@ 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,
@@ -142,7 +159,7 @@ 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,

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';

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';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "10.1.0",
+  "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.6.0",
+    "@x12i/activix": "^8.6.1",
+    "@x12i/ai-profiles": "^3.2.0",
     "@x12i/ai-providers-router": "^4.9.2",
-    "@x12i/ai-tools": "^3.0.0",
+    "@x12i/ai-tools": "^3.1.0",
     "@x12i/flex-md": "^4.8.0",
     "@x12i/logxer": "^4.6.0",
     "@x12i/rendrix": "^4.3.0"