@x12i/ai-gateway 10.2.0 → 10.2.1

package/README.md

@@ -88,7 +88,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 `{ 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.
+- **`PREFER_OPENROUTER=false`:** Do **not** prefer OpenRouter when a direct provider API key exists — use the direct provider instead. OpenRouter is **still** used as **fallback** when the request targets a provider without a direct key (e.g. `anthropic` without `ANTHROPIC_API_KEY`). It does not disable OpenRouter while `OPENROUTER_API_KEY` is set.
 - **Direct providers:** Set `OPENAI_API_KEY`, `GROK_API_KEY`, etc. Registered lazily on first invoke.
 
 Details: [OpenRouter env](./docs/OPENROUTER_ENV.md).
@@ -191,7 +191,7 @@ Instructions must be **complete caller text** — the gateway no longer injects
 | `AI_GATEWAY_VERBOSE` | Full payload lines (still requires `AI_GATEWAY_LOGS_LEVEL=verbose`) |
 | `LOGXER_PACKAGE_LEVELS` | Bulk stack levels, e.g. `AI_GATEWAY:info,AI_PROVIDER_ROUTER:debug` |
 | `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for OpenRouter transport) |
-| `USE_OPENROUTER` | Optional; default **prefer** OpenRouter when key is set. `false` = use direct provider keys when present; OpenRouter still used as fallback when a provider has no key |
+| `PREFER_OPENROUTER` | Optional; default **prefer** OpenRouter when key is set. `false` = use direct provider keys when present; OpenRouter still used as fallback when a provider has no key |
 | Other provider keys | `OPENAI_API_KEY`, `GROK_API_KEY`, etc. |
 
 Logging details: [Logger initialization](./docs/LOGGER_INITIALIZATION.md). Package identity and audit checklist: [LOGXER_INTEGRATION_CHECKLIST.md](./docs/LOGXER_INTEGRATION_CHECKLIST.md).
@@ -256,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`, …). 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 exports the model orchestrator from `@x12i/ai-tools` ≥ **3.3.0** (`resolveInvokeModel`, `preferOpenRouter`, …). Profile/choice keys (`cheap/default`, …) must be resolved **before** invoke — the gateway does not run alias resolution. Shortcuts like `cheapest` / bare `cheap` are rejected at ingress or catalog resolution.
 
 Gateway billing helpers (exported for tests/integrators): `resolveCostCompletionWithAiTools`, `buildGatewayPricingRecord`, `catalogPricingSucceeded`, `buildTraceUsageSummary`, `enrichTraceAttemptsWithBilling`.
 
@@ -358,7 +358,7 @@ Full index: **[docs/README.md](./docs/README.md)**. Upstream gaps: **[docs/upstr
 |----------|--------|
 | [AI_GATEWAY_INVOKE_EXECUTION_METADATA.md](./docs/AI_GATEWAY_INVOKE_EXECUTION_METADATA.md) | Metadata, cost, trace, Activix completion |
 | [IDENTITY_OBJECT_CONTRACT.md](./docs/IDENTITY_OBJECT_CONTRACT.md) | Identity / `runContext` |
-| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `USE_OPENROUTER` |
+| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `PREFER_OPENROUTER` |
 | [UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md](./docs/UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md) | Profile routing + OpenRouter fallback |
 | [UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md](./docs/UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md) | Parser v4 + `template-rendering.json` |
 | [GRAPH_EXECUTION_SUPPORT.md](./docs/GRAPH_EXECUTION_SUPPORT.md) | Graph / node identity |

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

@@ -9,7 +9,7 @@ export type AiToolsClientBundle = AiToolsInvokeClient;
 export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
 export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
+export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 export type { InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, AiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use buildInvokeModelResolverOptions */
 export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): import("@x12i/ai-tools").ModelResolverOptions;

package/dist/ai-tools-client.js

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

package/dist/gateway-config.d.ts

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

package/dist/gateway-config.js

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

package/dist/gateway-utils.d.ts

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

package/dist/gateway-utils.js

@@ -100,7 +100,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         throw new ModelRequiredError();
     }
     const ingress = normalizeInvokeModelAtIngress(merged.provider, explicitModel, {
-        useOpenRouter: mergeOptions?.useOpenRouter,
+        preferOpenRouter: mergeOptions?.preferOpenRouter,
     });
     if (ingress.changed) {
         logger.verbose('Invoke model normalized at ingress', {
@@ -121,7 +121,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 catalog: mergeOptions.catalog,
                 routingEnv: mergeOptions.routingEnv,
                 openRouterApiKey: mergeOptions.openRouterApiKey,
-                useOpenRouter: mergeOptions.useOpenRouter,
+                preferOpenRouter: mergeOptions.preferOpenRouter,
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
@@ -163,7 +163,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             resolveModels: false,
             routingEnv: mergeOptions.routingEnv,
             openRouterApiKey: mergeOptions.openRouterApiKey,
-            useOpenRouter: mergeOptions.useOpenRouter,
+            preferOpenRouter: mergeOptions.preferOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;

package/dist/gateway.d.ts

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

package/dist/gateway.js

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

package/dist/index.d.ts

@@ -42,7 +42,7 @@ export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFI
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
 /** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 export type { AiToolsClientBundle, AiToolsInvokeClient, InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, } from './ai-tools-client.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist/index.js

@@ -35,7 +35,7 @@ export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-fact
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 /** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

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

@@ -3,7 +3,7 @@
  * Defense in depth before catalog lookup / `resolveInvokeModel`.
  */
 export type InvokeModelIngressOptions = {
-    useOpenRouter?: boolean;
+    preferOpenRouter?: boolean;
 };
 export type InvokeModelIngressResult = {
     provider: string;

package/dist/invoke-model-ingress.js

@@ -33,8 +33,8 @@ export function normalizeInvokeModelAtIngress(provider, model, options = {}) {
             model: inputModel,
             provider: inputProvider,
             routing: 'auto',
-            useOpenRouter: options.useOpenRouter,
-        }, { useOpenRouter: options.useOpenRouter });
+            preferOpenRouter: options.preferOpenRouter,
+        }, { preferOpenRouter: options.preferOpenRouter });
         const changed = normalized.provider !== (inputProvider?.toLowerCase() ?? inputProvider) ||
             normalized.model !== inputModel;
         return {

package/dist/openrouter-routing.d.ts

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

package/dist/openrouter-routing.js

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

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

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

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

@@ -9,7 +9,7 @@ export type AiToolsClientBundle = AiToolsInvokeClient;
 export { resolveInvokeModel, applyOpenRouterInvokeRouting, buildInvokeModelResolverOptions, enrichModelResolutionError, mapResolutionToRouterConfig, ModelProfileUnroutableError, ModelProfileInputRejectedError, MODEL_PROFILE_UNROUTABLE, getAiToolsInvokeClient, resetAiToolsInvokeClientForTests as resetAiToolsInvokeClientForTestsUpstream, createAiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use `applyOpenRouterInvokeRouting` (ai-tools v3). */
 export { applyOpenRouterInvokeRouting as applyOpenRouterInvokePolicy } from '@x12i/ai-tools';
-export { resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
+export { resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, } from './openrouter-routing.js';
 export type { InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, AiToolsInvokeClient, } from '@x12i/ai-tools';
 /** @deprecated Use buildInvokeModelResolverOptions */
 export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): import("@x12i/ai-tools").ModelResolverOptions;

package/dist-cjs/gateway-config.cjs

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

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

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

package/dist-cjs/gateway-utils.cjs

@@ -100,7 +100,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
         throw new ModelRequiredError();
     }
     const ingress = normalizeInvokeModelAtIngress(merged.provider, explicitModel, {
-        useOpenRouter: mergeOptions?.useOpenRouter,
+        preferOpenRouter: mergeOptions?.preferOpenRouter,
     });
     if (ingress.changed) {
         logger.verbose('Invoke model normalized at ingress', {
@@ -121,7 +121,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
                 catalog: mergeOptions.catalog,
                 routingEnv: mergeOptions.routingEnv,
                 openRouterApiKey: mergeOptions.openRouterApiKey,
-                useOpenRouter: mergeOptions.useOpenRouter,
+                preferOpenRouter: mergeOptions.preferOpenRouter,
                 defaultProvider: config.defaultEngine,
                 resolveModels: true,
                 modelsOnly: config.aiTools?.modelsOnly !== false,
@@ -163,7 +163,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
             resolveModels: false,
             routingEnv: mergeOptions.routingEnv,
             openRouterApiKey: mergeOptions.openRouterApiKey,
-            useOpenRouter: mergeOptions.useOpenRouter,
+            preferOpenRouter: mergeOptions.preferOpenRouter,
             defaultProvider: config.defaultEngine,
         });
         merged.provider = resolved.router.provider;

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

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

package/dist-cjs/gateway.cjs

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

package/dist-cjs/gateway.d.ts

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

package/dist-cjs/index.cjs

@@ -35,7 +35,7 @@ export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-fact
 export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 /** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

package/dist-cjs/index.d.ts

@@ -42,7 +42,7 @@ export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFI
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
 /** Re-export @x12i/ai-tools invoke orchestrator (≥ 3.0.0) for engine callers. */
-export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolveUseOpenRouter, resolvePreferOpenRouter, readUseOpenRouterFromEnv, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
+export { resolveInvokeModel, applyModelResolution, applyOpenRouterInvokeRouting, applyOpenRouterInvokePolicy, mapResolutionToRouterConfig, buildInvokeModelResolverOptions, buildModelResolverOptions, enrichModelResolutionError, getAiToolsClient, resetAiToolsClientForTests, resolveOpenRouterApiKey, resolvePreferOpenRouter, readPreferOpenRouterFromEnv, getAiToolsInvokeClient, createAiToolsInvokeClient, } from './ai-tools-client.js';
 export type { AiToolsClientBundle, AiToolsInvokeClient, InvokeModelResolutionDiagnostics, InvokeModelResolutionInput, InvokeModelResolutionOptions, InvokeModelResolutionResult, InvokeRouterConfigSlice, } from './ai-tools-client.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
 export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';

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

@@ -33,8 +33,8 @@ export function normalizeInvokeModelAtIngress(provider, model, options = {}) {
             model: inputModel,
             provider: inputProvider,
             routing: 'auto',
-            useOpenRouter: options.useOpenRouter,
-        }, { useOpenRouter: options.useOpenRouter });
+            preferOpenRouter: options.preferOpenRouter,
+        }, { preferOpenRouter: options.preferOpenRouter });
         const changed = normalized.provider !== (inputProvider?.toLowerCase() ?? inputProvider) ||
             normalized.model !== inputModel;
         return {

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

@@ -3,7 +3,7 @@
  * Defense in depth before catalog lookup / `resolveInvokeModel`.
  */
 export type InvokeModelIngressOptions = {
-    useOpenRouter?: boolean;
+    preferOpenRouter?: boolean;
 };
 export type InvokeModelIngressResult = {
     provider: string;

package/dist-cjs/openrouter-routing.cjs

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

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

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

package/package.json

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