@x12i/ai-providers-router 4.8.2 → 4.8.4

package/dist/adapters/openrouter/OpenRouterAdapter.js

@@ -1,4 +1,5 @@
 import { openRouterCatalog } from '../../openrouter-catalog.js';
+import { resolveModelVendorSlug } from '../../utils/openrouterModelVendor.js';
 import { extractCostUsdFromProviderUsage } from '../../normalization/cost.js';
 import { getReasoningCapabilitiesFromRegistry, hasReasoningParamInCatalog } from './reasoning-capabilities.js';
 /**
@@ -258,13 +259,12 @@ export class OpenRouterAdapter {
         const { requestId, mode, request, exec } = input;
         // Extract model from request (could be in request.model or request.config.model)
         let model = request.model || request.config?.model || 'openai/gpt-4o-mini';
-        // Determine the original provider name from the request context
-        // When OpenRouter mode is enabled, the interceptor sets request.config.provider
-        // to preserve the original provider name (e.g., "openai", "grok") for model mapping
+        // Determine the model vendor slug for normalization (not the OpenRouter transport id).
         const originalProvider = request.config?.provider;
+        const modelVendor = resolveModelVendorSlug(model, originalProvider);
         // Normalize model name for OpenRouter using catalog data
         // (e.g., "gpt-4o" + provider="openai" → "openai/gpt-4o")
-        model = await this.normalizeModelName(model, originalProvider);
+        model = await this.normalizeModelName(model, modelVendor);
         // Validate model is available in OpenRouter catalog
         try {
             const isAvailable = await openRouterCatalog.isModelAvailable(model);

package/dist/factory.js

@@ -1,5 +1,6 @@
 import { LLMProviderRouter } from './router/RouterWrapper.js';
 import dns from 'node:dns';
+import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC } from './utils/openrouterEnv.js';
 import dotenv from 'dotenv';
 // Fix IPv6-first DNS resolution issue on Windows (forces IPv4-first to avoid connect timeouts)
 // This prevents undici from trying IPv6 first on networks that silently drop IPv6 traffic
@@ -114,9 +115,9 @@ export async function createRouter(config) {
                 apiKey: 'ENV.GOOGLE_API_KEY',
             },
             openrouter: {
-                apiKey: 'ENV.OPEN_ROUTER_KEY',
-                httpReferer: 'ENV.OPEN_ROUTER_HTTP_REFERER',
-                xTitle: 'ENV.OPEN_ROUTER_X_TITLE',
+                apiKey: OPENROUTER_API_KEY_ERC,
+                httpReferer: 'ENV.OPENROUTER_HTTP_REFERER||ENV.OPEN_ROUTER_HTTP_REFERER',
+                xTitle: 'ENV.OPENROUTER_X_TITLE||ENV.OPEN_ROUTER_X_TITLE',
                 useOpenRouter: 'ENV.USE_OPENROUTER',
             },
         },
@@ -125,6 +126,10 @@ export async function createRouter(config) {
     const ercResult = {
         config: resolveEnvPlaceholders(ercConfig)
     };
+    const resolvedOpenRouterKey = resolveOpenRouterApiKey();
+    if (resolvedOpenRouterKey && ercResult.config.providers?.openrouter) {
+        ercResult.config.providers.openrouter.apiKey = resolvedOpenRouterKey;
+    }
     // Use explicit config if provided (Advanced Mode), otherwise use ERC auto-discovered config (Zero-Config Mode)
     const finalConfig = Object.keys(config || {}).length > 0 ? config : {
         logLevel: ercResult.config.router.logLevel,
@@ -136,13 +141,14 @@ export async function createRouter(config) {
     // Configure providers from ERC auto-detected config OR explicit config
     const providerConfigs = config?.providerConfigs || ercResult.config.providers;
     // Check if OpenRouter mode should be enabled
-    // Default: true if OPEN_ROUTER_KEY is present, else false
+    // Default: true if OPENROUTER_API_KEY (or legacy OPEN_ROUTER_KEY) is present, else false
     // Can be explicitly disabled with USE_OPENROUTER=false
-    const openRouterKey = providerConfigs.openrouter?.apiKey;
+    const openRouterKey = providerConfigs.openrouter?.apiKey ?? resolvedOpenRouterKey;
     const useOpenRouterEnv = providerConfigs.openrouter?.useOpenRouter;
     // Check if API key is valid (not placeholder, not empty)
     const hasValidKey = openRouterKey &&
         openRouterKey !== 'ENV.OPEN_ROUTER_KEY' &&
+        openRouterKey !== OPENROUTER_API_KEY_ERC &&
         typeof openRouterKey === 'string' &&
         openRouterKey.trim() !== '';
     // Determine if OpenRouter should be enabled

package/dist/openrouter-catalog.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { getDirname } from './utils/esm-compat.js';
+import { inferVendorSlugFromBareModel, isOpenRouterTransportProvider, resolveModelVendorSlug, } from './utils/openrouterModelVendor.js';
 // Get __dirname equivalent for ESM
 const __dirname = getDirname(import.meta.url);
 /**
@@ -184,43 +185,51 @@ export class OpenRouterCatalogLoader {
      */
     async normalizeModelName(modelName, providerHint) {
         const models = await this.getModels();
-        // If already in OpenRouter format (contains '/'), validate it
-        if (modelName.includes('/')) {
-            const model = models.find(m => m.openrouterId === modelName);
-            if (model) {
-                return model.openrouterId;
+        const trimmed = modelName.trim();
+        const vendorHint = isOpenRouterTransportProvider(providerHint) ? undefined : providerHint;
+        // Already vendor-qualified (`openai/gpt-5.4`, etc.)
+        if (trimmed.includes('/')) {
+            const catalogMatch = models.find((m) => m.openrouterId === trimmed);
+            if (catalogMatch)
+                return catalogMatch.openrouterId;
+            const aliasMatch = models.find((m) => m.aliases.includes(trimmed));
+            if (aliasMatch)
+                return aliasMatch.openrouterId;
+            const [prefix] = trimmed.split('/');
+            if (prefix && !isOpenRouterTransportProvider(prefix)) {
+                const isKnownVendor = (await this.findProviderBySlug(prefix)) != null ||
+                    (await this.findProviderByVendorId(prefix)) != null;
+                if (isKnownVendor)
+                    return trimmed;
             }
-            // If not found but contains '/', it might be an alias, continue to check
+            // Never double-prefix vendor/model strings (e.g. openrouter + openai/gpt-5.4)
+            return trimmed;
         }
-        // Try to find by exact alias match
-        const aliasMatch = models.find(m => m.aliases.includes(modelName));
-        if (aliasMatch) {
+        // Bare alias (`gpt-4o`, tier keys resolved upstream, etc.)
+        const aliasMatch = models.find((m) => m.aliases.includes(trimmed));
+        if (aliasMatch)
             return aliasMatch.openrouterId;
-        }
-        // If provider hint provided, try to construct OpenRouter ID
-        if (providerHint) {
-            const candidateId = `${providerHint}/${modelName}`;
-            const model = models.find(m => m.openrouterId === candidateId);
-            if (model) {
+        const resolvedVendor = resolveModelVendorSlug(trimmed, providerHint) ?? vendorHint;
+        if (resolvedVendor) {
+            const candidateId = `${resolvedVendor}/${trimmed}`;
+            const model = models.find((m) => m.openrouterId === candidateId);
+            if (model)
                 return model.openrouterId;
-            }
+            return candidateId;
         }
-        // Fallback: try to infer provider and construct ID
-        const inferredProvider = await this.inferProviderFromModel(modelName);
+        const inferredProvider = await this.inferProviderFromModel(trimmed);
         if (inferredProvider) {
-            const candidateId = `${inferredProvider}/${modelName}`;
-            const model = models.find(m => m.openrouterId === candidateId);
-            if (model) {
+            const candidateId = `${inferredProvider}/${trimmed}`;
+            const model = models.find((m) => m.openrouterId === candidateId);
+            if (model)
                 return model.openrouterId;
-            }
+            return candidateId;
         }
-        // Best-effort fallback: if we have a provider hint and the model is bare,
-        // still prefix it (helps with very new models like `gpt-5.5` before catalog refresh).
-        if (providerHint && !modelName.includes('/')) {
-            return `${providerHint}/${modelName}`;
+        const patternVendor = inferVendorSlugFromBareModel(trimmed);
+        if (patternVendor) {
+            return `${patternVendor}/${trimmed}`;
         }
-        // Last resort: return as-is (might be a direct model name)
-        return modelName;
+        return trimmed;
     }
 }
 // Export singleton instance

package/dist/router/Router.js

@@ -3,6 +3,7 @@ import { applyResponseNormalization } from '../normalization/applyResponseNormal
 import { extractCostUsdFromRouterResponse } from '../normalization/cost.js';
 import { FallbackExhaustedError } from '../errors.js';
 import { buildCandidateRequest, buildFallbackCandidates, isRetryableError, summarizeError, toError, } from './fallbackUtils.js';
+import { hasOpenRouterApiKey } from '../utils/openrouterEnv.js';
 import { attachPartialRouterPayload, buildPartialRouterPayload } from './partialErrorPayload.js';
 /**
  * Main router class
@@ -36,10 +37,8 @@ export class AIRouter {
     resolveProviderName(input) {
         const hasOpenRouterAdapter = this.adapters.has('openrouter');
         const hasOpenRouterProvider = this.providers.has('openrouter');
-        // Check if OPEN_ROUTER_KEY is set in environment (completely automatic detection)
-        const hasOpenRouterKey = !!(process.env.OPEN_ROUTER_KEY &&
-            process.env.OPEN_ROUTER_KEY.trim() !== '' &&
-            !process.env.OPEN_ROUTER_KEY.startsWith('ENV.'));
+        // Check if OpenRouter API key is set (OPENROUTER_API_KEY canonical; OPEN_ROUTER_KEY legacy)
+        const hasOpenRouterKey = hasOpenRouterApiKey();
         // Normalize config.provider (handle string, trim whitespace)
         const cfgProviderRaw = input.request?.config?.provider;
         const cfgProvider = typeof cfgProviderRaw === 'string' ? cfgProviderRaw.trim() : undefined;
@@ -71,7 +70,7 @@ export class AIRouter {
                 // Check if OpenRouter mode could work automatically
                 if (hasOpenRouterAdapter && !hasOpenRouterKey) {
                     throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. ` +
-                        `OpenRouter adapter is available - set OPEN_ROUTER_KEY environment variable to enable automatic OpenRouter mode. ` +
+                        `OpenRouter adapter is available - set OPENROUTER_API_KEY environment variable to enable automatic OpenRouter mode. ` +
                         `Available providers: ${available || '(none)'}`);
                 }
                 throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. Available providers: ${available || '(none)'}`);
@@ -90,10 +89,10 @@ export class AIRouter {
             if (hasProviderInConfig && hasOpenRouterAdapter && !hasRegisteredProviders) {
                 if (!hasOpenRouterKey) {
                     throw new Error('OpenRouter adapter available and config.provider specified, but OpenRouter provider module not registered. ' +
-                        'Set OPEN_ROUTER_KEY environment variable to enable automatic OpenRouter mode (works with both createRouter() and manual initialization).');
+                        'Set OPENROUTER_API_KEY environment variable to enable automatic OpenRouter mode (works with both createRouter() and manual initialization).');
                 }
                 throw new Error('OpenRouter adapter available and config.provider specified, but OpenRouter provider module not registered. ' +
-                    'OPEN_ROUTER_KEY is set but provider module initialization failed. Check that @x12i/ai-provider-openai is installed.');
+                    'OPENROUTER_API_KEY is set but provider module initialization failed. Check that @x12i/ai-provider-openai is installed.');
             }
             if (hasProviderInConfig && !hasOpenRouterAdapter) {
                 throw new Error(`Provider '${input.request?.config?.provider}' specified in config but no providers registered and OpenRouter adapter not available.`);
@@ -101,7 +100,7 @@ export class AIRouter {
             // Final fallback error with OpenRouter suggestion
             if (hasOpenRouterAdapter && !hasOpenRouterKey) {
                 throw new Error('No provider specified and no providers registered. ' +
-                    'OpenRouter adapter is available - set OPEN_ROUTER_KEY environment variable to enable automatic OpenRouter mode.');
+                    'OpenRouter adapter is available - set OPENROUTER_API_KEY environment variable to enable automatic OpenRouter mode.');
             }
             throw new Error('No provider specified and no providers registered');
         }

package/dist/router/RouterWrapper.js

@@ -5,6 +5,8 @@ import { OpenAIAdapter } from '../adapters/openai/OpenAIAdapter.js';
 import { GrokAdapter } from '../adapters/grok/GrokAdapter.js';
 import { OpenRouterAdapter } from '../adapters/openrouter/OpenRouterAdapter.js';
 import { getLogger } from '../logger.js';
+import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC } from '../utils/openrouterEnv.js';
+import { resolveModelVendorSlug } from '../utils/openrouterModelVendor.js';
 /**
  * Resolve ENV. placeholders to actual environment variable values
  * Replaces nx-config2 functionality to avoid ESM/CommonJS compatibility issues
@@ -373,9 +375,18 @@ export class LLMProviderRouter {
      * Used by ensureProvidersRegistered() and by the OpenRouter retry path when the first run skipped registration.
      */
     async tryRegisterOpenRouter(config) {
-        const openRouterKey = (this.config?.openrouter?.apiKey && typeof this.config.openrouter.apiKey === 'string' && !this.config.openrouter.apiKey.startsWith('ENV.'))
+        const configuredKey = this.config?.openrouter?.apiKey &&
+            typeof this.config.openrouter.apiKey === 'string' &&
+            !this.config.openrouter.apiKey.startsWith('ENV.')
             ? this.config.openrouter.apiKey
-            : config.openrouter?.apiKey;
+            : undefined;
+        const resolvedConfigKey = config.openrouter?.apiKey &&
+            typeof config.openrouter.apiKey === 'string' &&
+            !config.openrouter.apiKey.startsWith('ENV.') &&
+            !config.openrouter.apiKey.includes('||')
+            ? config.openrouter.apiKey
+            : undefined;
+        const openRouterKey = configuredKey ?? resolvedConfigKey ?? resolveOpenRouterApiKey();
         const hasOpenRouterKey = openRouterKey &&
             typeof openRouterKey === 'string' &&
             openRouterKey.trim() !== '' &&
@@ -409,27 +420,29 @@ export class LLMProviderRouter {
                         newRequest.request.config.provider = callerProvider;
                         return newRequest;
                     }
-                    let effectiveProvider = originalProvider;
-                    if (!effectiveProvider) {
-                        const model = newRequest.request.config?.model || newRequest.request?.model;
+                    let effectiveProvider = originalProvider ?? callerProvider;
+                    const model = newRequest.request.config?.model || newRequest.request?.model;
+                    const inferredFromModel = typeof model === 'string' ? resolveModelVendorSlug(model, effectiveProvider) : undefined;
+                    if (inferredFromModel) {
+                        effectiveProvider = inferredFromModel;
+                    }
+                    else if (!effectiveProvider || effectiveProvider === 'openrouter') {
                         if (model && typeof model === 'string') {
                             if (model.startsWith('gpt-') || model.startsWith('openai/'))
                                 effectiveProvider = 'openai';
                             else if (model.startsWith('claude-') || model.startsWith('anthropic/'))
                                 effectiveProvider = 'anthropic';
                             else if (model.startsWith('grok-') || model.startsWith('xai/'))
-                                effectiveProvider = 'grok';
+                                effectiveProvider = 'x-ai';
                             else if (model.startsWith('gemini-') || model.startsWith('google/'))
                                 effectiveProvider = 'google';
                         }
-                        if (!effectiveProvider)
+                        if (!effectiveProvider || effectiveProvider === 'openrouter') {
                             effectiveProvider = 'openai';
+                        }
                     }
                     newRequest.request.config.provider = effectiveProvider;
-                    if (effectiveProvider !== 'openrouter') {
-                        this.logger?.warn?.(`[OpenRouterProxy] Forcing provider=openrouter (effectiveProvider=${effectiveProvider}, originalProvider=${originalProvider ?? newRequest.provider}, model=${newRequest.request?.config?.model ?? newRequest.request?.model ?? 'unknown'})`);
-                        newRequest.provider = 'openrouter';
-                    }
+                    newRequest.provider = 'openrouter';
                     return newRequest;
                 });
                 this.logger.info('Auto-registered OpenRouter provider and enabled OpenRouter mode');
@@ -450,8 +463,11 @@ export class LLMProviderRouter {
             if (this.providerRegistry.has('openrouter'))
                 return;
             // Retry OpenRouter only: key may be available now (e.g. from this.config passed by gateway)
-            const detectionConfig = { providers: { openrouter: { apiKey: 'ENV.OPEN_ROUTER_KEY' } } };
+            const detectionConfig = { providers: { openrouter: { apiKey: OPENROUTER_API_KEY_ERC } } };
             const resolved = resolveEnvPlaceholders(detectionConfig);
+            if (resolved.providers?.openrouter && resolveOpenRouterApiKey()) {
+                resolved.providers.openrouter.apiKey = resolveOpenRouterApiKey();
+            }
             await this.tryRegisterOpenRouter(resolved.providers);
             return;
         }
@@ -468,12 +484,15 @@ export class LLMProviderRouter {
                     baseURL: 'ENV.XAI_API_BASE',
                 },
                 openrouter: {
-                    apiKey: 'ENV.OPEN_ROUTER_KEY',
+                    apiKey: OPENROUTER_API_KEY_ERC,
                 },
             }
         };
         const resolvedConfig = resolveEnvPlaceholders(detectionConfig);
         const config = resolvedConfig.providers;
+        if (config.openrouter && resolveOpenRouterApiKey()) {
+            config.openrouter.apiKey = resolveOpenRouterApiKey();
+        }
         await this.tryRegisterOpenRouter(config);
         // If OpenRouter is being used, we SKIP auto-registering other providers
         // to avoid global state conflicts (e.g. ai-provider-openai singleton config).

package/dist/utils/openrouterEnv.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonical OpenRouter API key env var is OPENROUTER_API_KEY (ai-tools / gateway).
+ * OPEN_ROUTER_KEY is accepted for backward compatibility only.
+ */
+export declare function resolveOpenRouterApiKey(): string | undefined;
+export declare function hasOpenRouterApiKey(): boolean;
+/** ERC placeholder resolution: prefer canonical name, fall back to legacy. */
+export declare const OPENROUTER_API_KEY_ERC = "ENV.OPENROUTER_API_KEY||ENV.OPEN_ROUTER_KEY";

package/dist/utils/openrouterEnv.js

@@ -0,0 +1,18 @@
+/**
+ * Canonical OpenRouter API key env var is OPENROUTER_API_KEY (ai-tools / gateway).
+ * OPEN_ROUTER_KEY is accepted for backward compatibility only.
+ */
+export function resolveOpenRouterApiKey() {
+    for (const envVar of ['OPENROUTER_API_KEY', 'OPEN_ROUTER_KEY']) {
+        const value = process.env[envVar];
+        if (typeof value === 'string' && value.trim() !== '' && !value.startsWith('ENV.')) {
+            return value.trim();
+        }
+    }
+    return undefined;
+}
+export function hasOpenRouterApiKey() {
+    return resolveOpenRouterApiKey() !== undefined;
+}
+/** ERC placeholder resolution: prefer canonical name, fall back to legacy. */
+export const OPENROUTER_API_KEY_ERC = 'ENV.OPENROUTER_API_KEY||ENV.OPEN_ROUTER_KEY';

package/dist/utils/openrouterModelVendor.d.ts

@@ -0,0 +1,10 @@
+/** OpenRouter module id — transport, not a model vendor slug. */
+export declare const OPENROUTER_TRANSPORT_PROVIDER = "openrouter";
+export declare function isOpenRouterTransportProvider(provider?: string): boolean;
+/**
+ * Resolve the model vendor slug used in OpenRouter ids (`vendor/model`).
+ * When config.provider is `openrouter`, infer from the model string instead.
+ */
+export declare function resolveModelVendorSlug(model: string, providerHint?: string): string | undefined;
+/** Pattern fallback for bare model ids not yet in the bundled catalog. */
+export declare function inferVendorSlugFromBareModel(modelName: string): string | undefined;

package/dist/utils/openrouterModelVendor.js

@@ -0,0 +1,40 @@
+/** OpenRouter module id — transport, not a model vendor slug. */
+export const OPENROUTER_TRANSPORT_PROVIDER = 'openrouter';
+export function isOpenRouterTransportProvider(provider) {
+    return provider === OPENROUTER_TRANSPORT_PROVIDER;
+}
+/**
+ * Resolve the model vendor slug used in OpenRouter ids (`vendor/model`).
+ * When config.provider is `openrouter`, infer from the model string instead.
+ */
+export function resolveModelVendorSlug(model, providerHint) {
+    const trimmed = typeof model === 'string' ? model.trim() : '';
+    if (!trimmed)
+        return undefined;
+    if (trimmed.includes('/')) {
+        const prefix = trimmed.split('/')[0]?.trim();
+        if (prefix && !isOpenRouterTransportProvider(prefix)) {
+            return prefix;
+        }
+        return undefined;
+    }
+    if (providerHint && !isOpenRouterTransportProvider(providerHint)) {
+        return providerHint;
+    }
+    return inferVendorSlugFromBareModel(trimmed);
+}
+/** Pattern fallback for bare model ids not yet in the bundled catalog. */
+export function inferVendorSlugFromBareModel(modelName) {
+    if (modelName.startsWith('gpt-') || modelName.startsWith('o1-') || modelName.startsWith('o3-') || modelName.startsWith('o4-')) {
+        return 'openai';
+    }
+    if (modelName.startsWith('claude-'))
+        return 'anthropic';
+    if (modelName.startsWith('grok-'))
+        return 'x-ai';
+    if (modelName.startsWith('gemini-'))
+        return 'google';
+    if (modelName.startsWith('llama-'))
+        return 'meta-llama';
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.8.2",
+  "version": "4.8.4",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",