@x12i/ai-gateway 9.6.3 → 9.6.5

package/README.md

@@ -87,8 +87,11 @@ console.log(response.content, response.metadata?.costUsd, response.metadata?.tok
 
 ### Providers without manual `register()`
 
-- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env` (unless `USE_OPENROUTER=false`). The gateway passes this key into the router on init and lazy-registers on first invoke. **`OPEN_ROUTER_KEY`** is a legacy alias still read if `OPENROUTER_API_KEY` is unset — prefer **`OPENROUTER_API_KEY`** so **`@x12i/ai-tools`** model resolution sets `routedViaOpenRouter` correctly (ai-tools does not read `OPEN_ROUTER_KEY`).
-- **Direct providers:** Set `OPENAI_API_KEY`, `GROK_API_KEY`, etc. Same lazy registration.
+- **OpenRouter:** Set **`OPENROUTER_API_KEY`** in `.env`. The gateway always passes this key to the router when set. **By default, OpenRouter is preferred** for routing (including when you also have direct keys such as `OPENAI_API_KEY`). **`@x12i/ai-tools` ≥ 2.1** resolves model + provider agnostically (`openrouter` + `cheap` or `openai` + `gpt-4o` — same pipeline). Profile aliases (`cheap`, `balanced`, …) set `routedViaOpenRouter` from env. You do not need `USE_OPENROUTER=true` when the key is present.
+- **`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.
+
+Details: [OpenRouter env](./docs/OPENROUTER_ENV.md).
 
 Load `.env` before constructing the gateway if another package creates it first.
 
@@ -130,7 +133,9 @@ Defaults load from `defaults/model-config.json`, `instructions-blocks.json`, and
 | `mode` / `MODE` | Operational mode (`dev`, `debug`, `prod`) |
 | `AI_GATEWAY_LOGS_LEVEL` | Log level when using default logger (`AI_GATEWAY` prefix) |
 | `FLEX_MD_MIN_COMPLIANCE_LEVEL` | `L0`–`L3` output-format validation (default `L0`) |
-| Provider API keys | OpenRouter, OpenAI, etc. |
+| `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for profile/OpenRouter routes) |
+| `USE_OPENROUTER` | Optional; default **prefer** OpenRouter when key is set. `false` = use direct provider keys when present; OpenRouter still used as fallback when a provider has no key |
+| Other provider keys | `OPENAI_API_KEY`, `GROK_API_KEY`, etc. |
 
 Logging details: [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
 
@@ -230,6 +235,8 @@ Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` +
 | [LOGGER_INITIALIZATION.md](./docs/LOGGER_INITIALIZATION.md) | Logxer setup |
 | [flex-md-compliance.md](./docs/flex-md-compliance.md) | Output format levels |
 | [PROMPT_TEMPLATE_USAGE.md](./docs/PROMPT_TEMPLATE_USAGE.md) | Rendrix templates |
+| [OPENROUTER_ENV.md](./docs/OPENROUTER_ENV.md) | `OPENROUTER_API_KEY` and `USE_OPENROUTER` semantics |
+| [UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md](./docs/UPSTREAM_PROFILE_RESOLUTION_AND_OPENROUTER_FALLBACK.md) | Profile routing and OpenRouter fallback checklist |
 | [upstream-reports/README.md](./docs/upstream-reports/README.md) | Upstream issues (one file per package/gap) |
 | [UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md](./docs/UPSTREAM_TEMPLATE_RENDERING_AND_PARSER_V4.md) | Parser v4 |
 | [RUNTIME_OBJECTS_OBSERVABILITY.md](./docs/RUNTIME_OBJECTS_OBSERVABILITY.md) | Runtime object keys |

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

@@ -1,13 +1,18 @@
 /**
  * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
  */
-import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess } from '@x12i/ai-tools';
+import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess, type ModelResolverOptions, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
 import type { Logxer } from '@x12i/logxer';
 import type { ChatRequest, GatewayConfig } from './types.js';
 export type AiToolsClientBundle = {
     catalog: AiModelsCatalogClient;
     calculator: CostCalculator;
+    routingEnv: OpenRouterRoutingConfig;
 };
+/**
+ * Per-invoke resolver options: ai-tools decides OpenRouter vs direct from env + optional gateway prefer override.
+ */
+export declare function buildModelResolverOptions(config: GatewayConfig, routingEnv?: OpenRouterRoutingConfig): ModelResolverOptions;
 /**
  * Returns catalog + calculator, or null when disabled or bootstrap fails.
  */
@@ -15,6 +20,25 @@ export declare function getAiToolsClient(config: GatewayConfig, logger: Logxer):
 /** Reset singleton (tests). */
 export declare function resetAiToolsClientForTests(): void;
 /**
- * Map catalog resolution to router config provider/model fields.
+ * Map catalog resolution to router `{ provider, model }` (agnostic to openrouter vs vendor input).
+ */
+export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string, inputModel?: string): void;
+type RouterConfigSlice = {
+    provider?: string;
+    model?: string;
+    allowOpenRouterProxy?: boolean;
+    providerProxy?: string;
+};
+type ModelResolutionMeta = {
+    routedViaOpenRouter?: boolean;
+};
+/**
+ * Router invoke flags after mergeConfig + ai-tools resolution (OpenRouter vs direct transport).
  */
-export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string): void;
+export declare function applyOpenRouterInvokePolicy(merged: RouterConfigSlice, options: {
+    openRouterApiKey?: string;
+    preferOpenRouter?: boolean;
+    routingEnv?: OpenRouterRoutingConfig;
+    resolution?: ModelResolutionMeta;
+}): void;
+export {};

package/dist/ai-tools-client.js

@@ -1,14 +1,26 @@
 /**
  * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
  */
-import { AiModelsCatalogClient, CostCalculator } from '@x12i/ai-tools';
+import { AiModelsCatalogClient, CostCalculator, isEffectiveOpenRouterTransport, loadOpenRouterRoutingEnv, resolveModelVendorFromResolution } from '@x12i/ai-tools';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+import { resolvePreferOpenRouter } from './openrouter-routing.js';
 let sharedClientPromise = null;
 let sharedConfigKey;
 let bootstrapFailedLogged = false;
 function configKey(config) {
     return `${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}:${config.aiTools?.bundledOnly ?? ''}`;
 }
+/**
+ * Per-invoke resolver options: ai-tools decides OpenRouter vs direct from env + optional gateway prefer override.
+ */
+export function buildModelResolverOptions(config, routingEnv) {
+    const env = routingEnv ?? loadOpenRouterRoutingEnv();
+    const prefer = resolvePreferOpenRouter(config);
+    return {
+        routingEnv: env,
+        ...(prefer ? { routeViaOpenRouter: true } : {}),
+    };
+}
 /**
  * Returns catalog + calculator, or null when disabled or bootstrap fails.
  */
@@ -34,33 +46,43 @@ export function resetAiToolsClientForTests() {
 }
 async function bootstrapAiTools(config, logger) {
     try {
+        const routingEnv = loadOpenRouterRoutingEnv();
         const catalog = new AiModelsCatalogClient({
             cacheTtlMs: config.aiTools?.cacheTtlMs,
-            ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {})
+            ...(config.aiTools?.bundledOnly ? { bundledOnly: true } : {}),
+            resolverOptions: { routingEnv },
         });
         const calculator = new CostCalculator(catalog, {
-            includeBreakdown: config.aiTools?.costIncludeBreakdown === true
+            includeBreakdown: config.aiTools?.costIncludeBreakdown === true,
         });
         logger.debug('ai-tools catalog client ready', {
-            debugKind: gatewayLogDebug.state
+            debugKind: gatewayLogDebug.state,
         });
-        return { catalog, calculator };
+        return { catalog, calculator, routingEnv };
     }
     catch (error) {
         if (!bootstrapFailedLogged) {
             bootstrapFailedLogged = true;
             logger.warn('ai-tools catalog bootstrap failed; model resolution and catalog cost calculation disabled', withActivityIdentity(undefined, {
                 error: error instanceof Error ? error.message : String(error),
-                debugKind: gatewayLogDebug.anomaly
+                debugKind: gatewayLogDebug.anomaly,
             }));
         }
         return null;
     }
 }
 /**
- * Map catalog resolution to router config provider/model fields.
+ * Map catalog resolution to router `{ provider, model }` (agnostic to openrouter vs vendor input).
  */
-export function applyModelResolution(merged, resolution, gatewayDefaultEngine) {
+export function applyModelResolution(merged, resolution, gatewayDefaultEngine, inputModel) {
+    const ref = resolveModelVendorFromResolution(resolution, inputModel ?? merged.model ?? '', {
+        asOpenRouter: resolution.routedViaOpenRouter,
+    });
+    if (ref) {
+        merged.provider = ref.provider;
+        merged.model = ref.model;
+        return;
+    }
     if (resolution.routedViaOpenRouter) {
         merged.provider = 'openrouter';
         merged.model = resolution.modelId;
@@ -81,3 +103,27 @@ export function applyModelResolution(merged, resolution, gatewayDefaultEngine) {
         merged.provider = gatewayDefaultEngine;
     }
 }
+/**
+ * Router invoke flags after mergeConfig + ai-tools resolution (OpenRouter vs direct transport).
+ */
+export function applyOpenRouterInvokePolicy(merged, options) {
+    if (!options.openRouterApiKey?.trim())
+        return;
+    const routingEnv = options.routingEnv ?? loadOpenRouterRoutingEnv();
+    const viaOpenRouter = options.resolution?.routedViaOpenRouter === true ||
+        (options.resolution?.routedViaOpenRouter !== false &&
+            isEffectiveOpenRouterTransport(routingEnv, {
+                provider: merged.provider,
+                modelId: merged.model,
+                routeViaOpenRouter: options.preferOpenRouter ? true : undefined,
+            }));
+    if (viaOpenRouter) {
+        merged.allowOpenRouterProxy = true;
+        if (merged.provider && merged.provider !== 'openrouter') {
+            merged.providerProxy = 'openrouter';
+        }
+    }
+    else {
+        merged.allowOpenRouterProxy = false;
+    }
+}

package/dist/gateway-config.d.ts

@@ -51,4 +51,6 @@ export declare function initializeGatewayComponents(config: GatewayConfig): {
     usageTracker: UsageTracker;
     messageBuilderConfig: MessageBuilderConfig;
     defaultModelConfig: Record<string, unknown>;
+    preferOpenRouter: boolean;
+    openRouterApiKey?: string;
 };

package/dist/gateway-config.js

@@ -5,6 +5,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
+import { resolveOpenRouterApiKey, resolvePreferOpenRouter, } from './openrouter-routing.js';
 /** Resolve current module directory across ESM/CJS builds. */
 function getModuleDir() {
     if (typeof __dirname !== 'undefined') {
@@ -193,16 +194,19 @@ export function initializeGatewayComponents(config) {
         routerConfig.autoDiscover = config.autoDiscover;
     if (config.usageTracker !== undefined)
         routerConfig.usageTracker = config.usageTracker;
-    // OpenRouter: enable when key is set and not explicitly disabled (so consumers get a working default without registering providers).
-    // Prefer explicit config from consumer (e.g. ai-skills) to avoid env-loading timing; fall back to process.env.
-    const explicitOpenRouterKey = config.openrouter?.apiKey;
-    const isExplicitKey = typeof explicitOpenRouterKey === 'string' && !explicitOpenRouterKey.startsWith('ENV.');
-    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPENROUTER_API_KEY ?? process.env.OPEN_ROUTER_KEY);
-    const useOpenRouter = config.openRouter?.enabled !== undefined ? config.openRouter?.enabled : process.env.USE_OPENROUTER;
-    if (openRouterKey && useOpenRouter !== false && useOpenRouter !== 'false') {
-        routerConfig.openRouter = { enabled: true };
+    // OpenRouter: always pass apiKey when set (fallback for providers without direct keys).
+    // USE_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
+    const openRouterKey = resolveOpenRouterApiKey(config);
+    const preferOpenRouter = resolvePreferOpenRouter(config);
+    if (openRouterKey) {
         routerConfig.openrouter = { apiKey: openRouterKey };
-        routerConfig.defaultMode = 'openrouter';
+        routerConfig.openRouter = {
+            enabled: true,
+            prefer: preferOpenRouter,
+        };
+        if (preferOpenRouter) {
+            routerConfig.defaultMode = 'openrouter';
+        }
     }
     const router = new LLMProviderRouter(routerConfig);
     // Set up BETWEEN-CALLS rate limiting as a request interceptor (applies to all provider calls)
@@ -302,6 +306,8 @@ export function initializeGatewayComponents(config) {
         optimixerManager,
         usageTracker,
         messageBuilderConfig,
-        defaultModelConfig
+        defaultModelConfig,
+        preferOpenRouter,
+        openRouterApiKey: openRouterKey,
     };
 }

package/dist/gateway-log-meta.d.ts

@@ -1,11 +1,15 @@
 /**
  * Maps gateway {@link ActivityIdentity} into Logxer {@link LogMeta} fields for correlation and querying.
  */
-import type { LogMeta } from '@x12i/logxer';
+import type { LogMeta, LogRuntimeContext } from '@x12i/logxer';
 import type { ActivityIdentity } from './types.js';
 /** Subset of identity forwarded on every structured log line (plus full envelope under `identity`). */
 export declare function activityIdentityToLogMeta(identity: Partial<ActivityIdentity> | undefined): LogMeta;
 export declare function withActivityIdentity(identity: Partial<ActivityIdentity> | undefined, data?: LogMeta, debugKind?: LogMeta['debugKind']): LogMeta;
+/** Map gateway identity into Logxer ALS correlation context (`runWithLogContext`). */
+export declare function activityIdentityToLogContext(identity: Partial<ActivityIdentity> | undefined): LogRuntimeContext;
+/** Run gateway work with Logxer correlation context for `getJobLogs` and structured envelopes. */
+export declare function withGatewayLogContext<T>(identity: Partial<ActivityIdentity> | undefined, fn: () => T | Promise<T>): Promise<T>;
 export declare const gatewayLogDebug: {
     readonly anomaly: "ANOMALY";
     readonly trace: "TRACE";

package/dist/gateway-log-meta.js

@@ -1,4 +1,4 @@
-import { DebugLogAbstract } from '@x12i/logxer';
+import { DebugLogAbstract, runWithLogContext } from '@x12i/logxer';
 /** Subset of identity forwarded on every structured log line (plus full envelope under `identity`). */
 export function activityIdentityToLogMeta(identity) {
     if (!identity) {
@@ -27,6 +27,24 @@ export function withActivityIdentity(identity, data, debugKind) {
         ...(debugKind !== undefined ? { debugKind } : {})
     };
 }
+/** Map gateway identity into Logxer ALS correlation context (`runWithLogContext`). */
+export function activityIdentityToLogContext(identity) {
+    if (!identity) {
+        return {};
+    }
+    return {
+        jobId: identity.jobId,
+        taskId: identity.taskId,
+        graphId: identity.graphId,
+        nodeId: identity.nodeId,
+        sessionId: identity.sessionId,
+        correlationId: identity.aiRequestId
+    };
+}
+/** Run gateway work with Logxer correlation context for `getJobLogs` and structured envelopes. */
+export function withGatewayLogContext(identity, fn) {
+    return runWithLogContext(activityIdentityToLogContext(identity), fn);
+}
 export const gatewayLogDebug = {
     anomaly: DebugLogAbstract.ANOMALY,
     trace: DebugLogAbstract.TRACE,

package/dist/gateway-provider-auto-register.js

@@ -146,7 +146,7 @@ export async function autoRegisterProviders(router, logger) {
             optionalEnvVars: PROVIDER_CONFIGS
                 .filter(p => p.optional)
                 .map(p => p.envVar),
-            openRouter: 'Set OPENROUTER_API_KEY (and do not set USE_OPENROUTER=false) to use OpenRouter without registering a provider. Legacy OPEN_ROUTER_KEY is still accepted.',
+            openRouter: 'Set OPENROUTER_API_KEY for OpenRouter (default route when set). USE_OPENROUTER=false prefers direct provider keys when present; OpenRouter is still used when a requested provider has no key.',
             note: 'You can still manually register providers using gateway.register(provider)'
         });
     }

package/dist/gateway-utils.d.ts

@@ -4,7 +4,7 @@
  */
 import type { AIInvokeRequest, ChatRequest, GatewayConfig, GatewayFallbackAttempt, GatewayInvokeRejectionMetadata, GatewayTraceAttempt, GatewayTraceMergedConfig, GatewayTraceRequestIds, GatewayTraceUsageSummary, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
-import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator } from '@x12i/ai-tools';
+import { type AiCostResult, type AiModelsCatalogClient, type CostCalculator, type OpenRouterRoutingConfig } from '@x12i/ai-tools';
 /**
  * Generates MD5 hash of a string
  */
@@ -16,6 +16,7 @@ export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer):
 export type MergeConfigOptions = {
     defaultModelConfig?: Record<string, unknown>;
     catalog?: AiModelsCatalogClient | null;
+    routingEnv?: OpenRouterRoutingConfig;
 };
 /**
  * True when any caller-controlled config source set `maxTokens` (Optimixer should not override).

package/dist/gateway-utils.js

@@ -9,7 +9,7 @@ import { extractHttpStatusCode } from './gateway-retry.js';
 import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 import { getPreParsedInstructions } from './gateway-instructions.js';
 import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
-import { applyModelResolution } from './ai-tools-client.js';
+import { applyModelResolution, buildModelResolverOptions } from './ai-tools-client.js';
 import { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, warnDefaultModelSubstitution } from './gateway-mode.js';
 /**
  * Generates MD5 hash of a string
@@ -65,14 +65,15 @@ async function tryResolveSubstitutedDefaultModel(merged, request, config, logger
         return;
     }
     try {
+        const resolverOptions = buildModelResolverOptions(config, mergeOptions?.routingEnv);
         const resolution = await catalog.resolveModel({
             provider: merged.provider,
-            model: merged.model
-        });
+            model: merged.model,
+        }, resolverOptions);
         if (!resolution.found) {
             return;
         }
-        applyModelResolution(merged, resolution, config.defaultEngine);
+        applyModelResolution(merged, resolution, config.defaultEngine, merged.model);
         request._modelResolution = {
             modelId: resolution.modelId,
             routedViaOpenRouter: resolution.routedViaOpenRouter,
@@ -182,12 +183,13 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     }
     else if (resolveModels && mergeOptions?.catalog) {
         try {
+            const resolverOptions = buildModelResolverOptions(config, mergeOptions?.routingEnv);
             const resolution = await mergeOptions.catalog.resolveModel({
                 provider: merged.provider,
-                model: explicitModel
-            });
+                model: explicitModel,
+            }, resolverOptions);
             if (resolution.found) {
-                applyModelResolution(merged, resolution, config.defaultEngine);
+                applyModelResolution(merged, resolution, config.defaultEngine, explicitModel);
                 request._modelResolution = {
                     modelId: resolution.modelId,
                     routedViaOpenRouter: resolution.routedViaOpenRouter,

package/dist/gateway.d.ts

@@ -20,6 +20,8 @@ export declare class AIGateway {
     private defaultModelConfig;
     private _autoRegisterDone;
     private _aiToolsClient;
+    private readonly preferOpenRouter;
+    private readonly openRouterApiKey?;
     constructor(config?: GatewayConfig, activityManager?: ActivityManager);
     /**
      * Invoke chat request (without structured output requirements)