@x12i/ai-providers-router 4.8.0 → 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/errors.d.ts

@@ -5,18 +5,19 @@ import type { ProviderId } from './types.js';
 export declare class ProviderNotFoundError extends Error {
     constructor(providerName: ProviderId | string);
 }
+export type FallbackAttempt = {
+    provider: ProviderId | string;
+    model?: string;
+    httpStatus?: number;
+    error: Error;
+    responsePreview?: string;
+};
 /**
  * Error thrown when all providers in the fallback chain have failed
  */
 export declare class FallbackExhaustedError extends Error {
-    attempts: Array<{
-        provider: ProviderId;
-        error: Error;
-    }>;
-    constructor(attempts: Array<{
-        provider: ProviderId;
-        error: Error;
-    }>);
+    attempts: FallbackAttempt[];
+    constructor(attempts: FallbackAttempt[]);
 }
 /**
  * Error thrown when a provider package is not installed

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/index.d.ts

@@ -1,8 +1,10 @@
 export { LLMProviderRouter } from './router.js';
-export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, } from './router.js';
+export type { RouterConfig, HealthCheckResult, ProviderId, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, NormalizedRouterOutput, ProviderModelRef, } from './router.js';
 export { createRouter, createRouterFromConfig } from './factory.js';
 export type { CreateRouterConfig } from './factory.js';
 export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError, ProviderTimeoutError } from './errors.js';
+export type { FallbackAttempt } from './errors.js';
+export type { PartialRouterPayload } from './router/partialErrorPayload.js';
 export type { RequestInterceptor, ResponseInterceptor } from './interceptors.js';
 export type { UsageTracker, AdapterLoader, ProviderInit } from './types.js';
 export { Logger, getLogger, createLogger } from './logger.js';

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/providers/OpenRouterProvider.js

@@ -4,6 +4,21 @@
  */
 import { OpenRouter } from '@openrouter/sdk';
 import { ProviderTimeoutError } from '../errors.js';
+function preservePartialResponseOnError(error) {
+    if (error == null || typeof error !== 'object')
+        return;
+    const e = error;
+    if (e.rawResponse !== undefined)
+        return;
+    const response = e.response;
+    if (response == null || typeof response !== 'object')
+        return;
+    const resp = response;
+    const body = resp.data ?? resp.body ?? resp;
+    if (body != null && typeof body === 'object') {
+        e.rawResponse = body;
+    }
+}
 /**
  * Create OpenRouter ProviderModule using @openrouter/sdk directly
  */
@@ -124,6 +139,7 @@ export function createOpenRouterProvider(config) {
                 if (timedOut && typeof timeoutMs === 'number') {
                     throw new ProviderTimeoutError('openrouter', timeoutMs, operation);
                 }
+                preservePartialResponseOnError(error);
                 throw error;
             }
             finally {
@@ -223,6 +239,7 @@ export function createOpenRouterProvider(config) {
                 if (timedOut && typeof timeoutMs === 'number') {
                     throw new ProviderTimeoutError('openrouter', timeoutMs, operation);
                 }
+                preservePartialResponseOnError(error);
                 throw error;
             }
             finally {

package/dist/router/Router.d.ts

@@ -1,6 +1,6 @@
 import type { ProviderRegistry } from '../registry/ProviderRegistry.js';
 import type { AdapterRegistry } from '../registry/AdapterRegistry.js';
-import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem } from './RouterTypes.js';
+import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, RouterConfig } from './RouterTypes.js';
 /**
  * Main router class
  * Orchestrates provider execution using ProviderModules and router-side adapters
@@ -8,7 +8,12 @@ import type { AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBat
 export declare class AIRouter {
     private providers;
     private adapters;
-    constructor(providers: ProviderRegistry, adapters: AdapterRegistry);
+    private routerConfig;
+    constructor(providers: ProviderRegistry, adapters: AdapterRegistry, routerConfig?: RouterConfig);
+    /**
+     * Resolve provider module name for a specific fallback candidate.
+     */
+    private resolveProviderNameForCandidate;
     /**
      * Resolve provider name from request, checking OpenRouter mode first
      */

package/dist/router/Router.js

@@ -1,14 +1,35 @@
 import { newId } from '../utils/ids.js';
 import { applyResponseNormalization } from '../normalization/applyResponseNormalization.js';
 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
  * Orchestrates provider execution using ProviderModules and router-side adapters
  */
 export class AIRouter {
-    constructor(providers, adapters) {
+    constructor(providers, adapters, routerConfig = {}) {
         this.providers = providers;
         this.adapters = adapters;
+        this.routerConfig = routerConfig;
+    }
+    /**
+     * Resolve provider module name for a specific fallback candidate.
+     */
+    resolveProviderNameForCandidate(input, candidateProvider) {
+        const candidateInput = {
+            ...input,
+            request: {
+                ...input.request,
+                config: {
+                    ...(input.request?.config ?? {}),
+                    provider: candidateProvider,
+                },
+            },
+        };
+        return this.resolveProviderName(candidateInput);
     }
     /**
      * Resolve provider name from request, checking OpenRouter mode first
@@ -16,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;
@@ -51,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)'}`);
@@ -70,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.`);
@@ -81,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');
         }
@@ -93,12 +112,15 @@ export class AIRouter {
     async runSync(input) {
         const requestId = input.requestId ?? newId();
         const primaryProviderName = this.resolveProviderName(input);
-        const fallbackProvidersRaw = input.request?.config?.fallbackProviders;
-        const fallbackProviders = Array.isArray(fallbackProvidersRaw)
-            ? fallbackProvidersRaw.filter((p) => typeof p === 'string' && p.trim().length > 0).map((p) => p.trim())
-            : [];
-        // Candidates are ordered: primary, then fallbacks.
-        const providerCandidates = [primaryProviderName, ...fallbackProviders.filter((p) => p !== primaryProviderName)];
+        const requestConfig = input.request?.config;
+        const primaryModel = (typeof requestConfig?.model === 'string' ? requestConfig.model : undefined) ??
+            (typeof input.request?.model === 'string' ? input.request.model : undefined);
+        const fallbackCandidates = buildFallbackCandidates({
+            primaryProvider: primaryProviderName,
+            primaryModel,
+            requestConfig: requestConfig && typeof requestConfig === 'object' ? requestConfig : undefined,
+            routerFallbackChain: this.routerConfig.fallbackChain,
+        });
         const maxRetries = Math.max(0, Math.min(10, Number(input.exec?.retries ?? 0) || 0));
         const attempts = [];
         const normalizeUsage = (usage) => {
@@ -129,61 +151,73 @@ export class AIRouter {
                 (typeof args.maxTokens === 'number' ? args.maxTokens : undefined);
             return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
         };
-        const summarizeError = (err) => {
-            const e = err instanceof Error ? err : new Error(String(err));
-            const name = typeof e.name === 'string' ? e.name : 'Error';
-            const message = typeof e.message === 'string' ? e.message : String(err);
-            // Size cap to avoid shipping huge provider payloads.
-            const capped = message.length > 500 ? message.slice(0, 500) : message;
-            return { name, message: capped };
-        };
         const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-        const isRetryableError = (err) => {
-            const msg = err instanceof Error ? err.message : String(err);
-            const name = err instanceof Error ? err.name : '';
-            const combined = `${name} ${msg}`.toLowerCase();
-            return (combined.includes('timeout') ||
-                combined.includes('timed out') ||
-                combined.includes('rate limit') ||
-                combined.includes('429') ||
-                combined.includes('econnreset') ||
-                combined.includes('etimedout') ||
-                combined.includes('503') ||
-                combined.includes('502') ||
-                combined.includes('504') ||
-                combined.includes('temporarily unavailable'));
-        };
         const backoffMs = (retryIndex) => {
             const base = 250 * Math.pow(2, Math.max(0, retryIndex));
             const jitter = Math.floor(Math.random() * 100);
             return Math.min(5000, base + jitter);
         };
         let lastError = undefined;
-        for (let fallbackIndex = 0; fallbackIndex < providerCandidates.length; fallbackIndex++) {
-            const providerName = providerCandidates[fallbackIndex];
+        const failedAttemptErrors = [];
+        let lastPartialPayload;
+        for (let fallbackIndex = 0; fallbackIndex < fallbackCandidates.length; fallbackIndex++) {
+            const candidate = fallbackCandidates[fallbackIndex];
+            const candidateInput = buildCandidateRequest(input, candidate);
+            const providerName = this.resolveProviderNameForCandidate(candidateInput, candidate.provider);
+            if (!this.providers.has(providerName)) {
+                const err = new Error(`Provider not registered: ${providerName}. Available: ${this.providers.list().join(', ')}`);
+                lastError = err;
+                failedAttemptErrors.push(err);
+                const partialPayload = buildPartialRouterPayload({
+                    requestId,
+                    engineProvider: candidate.provider,
+                    providerModule: providerName,
+                    modelUsed: candidate.model,
+                    attempts,
+                    providerError: err,
+                });
+                lastPartialPayload = partialPayload;
+                attachPartialRouterPayload(err, partialPayload);
+                attempts.push({
+                    ok: false,
+                    routing: {
+                        provider: candidate.provider,
+                        retryIndex: 0,
+                        fallbackIndex,
+                        requestIds: { routerRequestId: requestId },
+                    },
+                    modelUsed: candidate.model,
+                    error: summarizeError(err),
+                });
+                continue;
+            }
             const provider = this.providers.get(providerName);
             const adapter = this.adapters.get(providerName);
             // Check capabilities
             if (!provider.capabilities.modes.sync) {
                 throw new Error(`Provider '${providerName}' does not support sync mode`);
             }
-            // Build call spec (once per provider candidate; retries reuse the same spec)
+            // Build call spec (once per fallback candidate; retries reuse the same spec)
             const spec = await adapter.buildCallSpec({
                 requestId,
                 mode: 'sync',
-                request: input.request,
+                request: candidateInput.request,
                 exec: input.exec,
             });
             const maxTokensRequested = extractMaxTokensRequested(spec);
-            const requestedModel = spec?.args?.model ?? input.request?.config?.model ?? input.request?.model;
+            const requestedModel = spec?.args?.model ??
+                candidate.model ??
+                candidateInput.request?.config?.model ??
+                candidateInput.request?.model;
             for (let retryIndex = 0; retryIndex <= maxRetries; retryIndex++) {
                 const startedAt = Date.now();
+                let execResult;
                 try {
-                    const execResult = await provider.execute(spec);
+                    execResult = await provider.execute(spec);
                     const endedAt = Date.now();
                     const parsed = adapter.parseResponse({
                         requestId,
-                        request: { ...input.request, _callSpec: spec }, // Include call spec for adapter access
+                        request: { ...candidateInput.request, _callSpec: spec },
                         execResult,
                     });
                     const usage = normalizeUsage(parsed.usage);
@@ -203,7 +237,7 @@ export class AIRouter {
                     const attempt = {
                         ok: true,
                         routing: {
-                            provider: providerName,
+                            provider: candidate.provider,
                             retryIndex,
                             fallbackIndex,
                             requestIds: {
@@ -242,24 +276,42 @@ export class AIRouter {
                         usage,
                         metadata: mergedMetadata,
                     };
-                    return applyResponseNormalization(baseResponse, input.request);
+                    return applyResponseNormalization(baseResponse, candidateInput.request);
                 }
                 catch (err) {
                     const endedAt = Date.now();
                     lastError = err;
+                    failedAttemptErrors.push(err);
+                    const modelUsed = typeof requestedModel === 'string'
+                        ? requestedModel
+                        : candidate.model;
+                    const timing = { startedAt, endedAt, durationMs: endedAt - startedAt };
                     attempts.push({
                         ok: false,
                         routing: {
-                            provider: providerName,
+                            provider: candidate.provider,
                             retryIndex,
                             fallbackIndex,
                             requestIds: { routerRequestId: requestId },
                         },
-                        timing: { startedAt, endedAt, durationMs: endedAt - startedAt },
+                        timing,
                         maxTokensRequested,
-                        modelUsed: typeof requestedModel === 'string' ? requestedModel : undefined,
+                        modelUsed,
                         error: summarizeError(err),
                     });
+                    const partialPayload = buildPartialRouterPayload({
+                        requestId,
+                        engineProvider: candidate.provider,
+                        providerModule: providerName,
+                        modelUsed,
+                        maxTokensRequested,
+                        timing,
+                        attempts,
+                        execResult,
+                        providerError: err,
+                    });
+                    lastPartialPayload = partialPayload;
+                    attachPartialRouterPayload(err, partialPayload);
                     const shouldRetry = retryIndex < maxRetries && isRetryableError(err);
                     if (shouldRetry) {
                         await sleep(backoffMs(retryIndex));
@@ -269,10 +321,19 @@ export class AIRouter {
                 }
             }
         }
-        // Fallback chain exhausted
-        const error = lastError instanceof Error ? lastError : new Error(String(lastError ?? 'Unknown error'));
-        error.attempts = attempts;
-        throw error;
+        const failedTraces = attempts.filter((a) => !a.ok);
+        const exhaustedAttempts = failedTraces.map((trace, i) => ({
+            provider: trace.routing.provider,
+            model: trace.modelUsed,
+            httpStatus: trace.error?.httpStatus,
+            error: toError(failedAttemptErrors[i] ?? lastError),
+            ...(trace.error?.responsePreview !== undefined ? { responsePreview: trace.error.responsePreview } : {}),
+        }));
+        const exhaustedError = new FallbackExhaustedError(exhaustedAttempts);
+        if (lastPartialPayload) {
+            attachPartialRouterPayload(exhaustedError, lastPartialPayload);
+        }
+        throw exhaustedError;
     }
     /**
      * Execute a streaming request

package/dist/router/RouterTypes.d.ts

@@ -18,6 +18,14 @@ export type AttemptTiming = {
 export type AttemptErrorSummary = {
     name: string;
     message: string;
+    httpStatus?: number;
+    responsePreview?: string;
+};
+/** Provider + model reference used in fallback chains (`engine` is a gateway alias for `provider`). */
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
 };
 export type AttemptRouting = {
     provider: string;
@@ -93,6 +101,8 @@ export interface RouterConfig {
         httpReferer?: string;
         xTitle?: string;
     };
+    /** Default provider/model fallback chain when request config does not specify one. */
+    fallbackChain?: ProviderModelRef[];
 }
 /**
  * Router request - the input to the router

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
@@ -60,7 +62,7 @@ export class LLMProviderRouter {
         this.adapterRegistry.register(new GrokAdapter());
         this.adapterRegistry.register(new OpenRouterAdapter());
         // Create router
-        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry);
+        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry, this.config);
         this.logger.info('Router initialized with ProviderModule architecture', {
             verbose: this.logger.verbose,
             logLevel: this.logger.level,
@@ -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/router/fallbackUtils.d.ts

@@ -0,0 +1,38 @@
+import type { AttemptErrorSummary } from './RouterTypes.js';
+export type FallbackCandidate = {
+    provider: string;
+    model?: string;
+};
+export type ProviderModelRef = {
+    engine?: string;
+    provider?: string;
+    model?: string;
+};
+export declare function extractHttpStatus(err: unknown): number | undefined;
+export declare function extractResponsePreview(err: unknown): string | undefined;
+export declare function toError(err: unknown): Error;
+export declare function summarizeError(err: unknown): AttemptErrorSummary;
+export declare function isModelNotFoundError(err: unknown): boolean;
+/** Transient failures — retry the same provider/model candidate. */
+export declare function isRetryableError(err: unknown): boolean;
+/** Failures that should advance to the next fallback candidate (not retry same candidate). */
+export declare function isFallbackEligibleError(err: unknown): boolean;
+export declare function buildFallbackCandidates(input: {
+    primaryProvider: string;
+    primaryModel?: string;
+    requestConfig?: Record<string, unknown>;
+    routerFallbackChain?: ProviderModelRef[];
+}): FallbackCandidate[];
+export declare function buildCandidateRequest(input: AIRouterRequestLike, candidate: FallbackCandidate): AIRouterRequestLike;
+type AIRouterRequestLike = {
+    request?: {
+        config?: Record<string, unknown>;
+        model?: string;
+        [key: string]: unknown;
+    };
+    provider?: string;
+    mode?: string;
+    exec?: unknown;
+    requestId?: string;
+};
+export {};

package/dist/router/fallbackUtils.js

@@ -0,0 +1,176 @@
+const PREVIEW_CAP = 500;
+export function extractHttpStatus(err) {
+    const e = err;
+    if (!e)
+        return undefined;
+    for (const key of ['status', 'statusCode', 'httpStatus']) {
+        const v = e[key];
+        if (typeof v === 'number' && Number.isFinite(v))
+            return v;
+    }
+    const response = e.response;
+    if (response && typeof response.status === 'number')
+        return response.status;
+    const msg = err instanceof Error ? err.message : String(err);
+    const httpMatch = msg.match(/\bHTTP\s+(\d{3})\b/i);
+    if (httpMatch)
+        return Number(httpMatch[1]);
+    return undefined;
+}
+export function extractResponsePreview(err) {
+    const e = err;
+    if (!e)
+        return undefined;
+    const raw = e.body ??
+        e.responseBody ??
+        e.response?.data ??
+        e.data ??
+        e.error;
+    if (raw === undefined || raw === null)
+        return undefined;
+    let text;
+    if (typeof raw === 'string') {
+        text = raw;
+    }
+    else {
+        try {
+            text = JSON.stringify(raw);
+        }
+        catch {
+            text = String(raw);
+        }
+    }
+    return text.length > PREVIEW_CAP ? text.slice(0, PREVIEW_CAP) : text;
+}
+export function toError(err) {
+    return err instanceof Error ? err : new Error(String(err));
+}
+export function summarizeError(err) {
+    const e = toError(err);
+    const name = typeof e.name === 'string' ? e.name : 'Error';
+    const message = typeof e.message === 'string' ? e.message : String(err);
+    const capped = message.length > PREVIEW_CAP ? message.slice(0, PREVIEW_CAP) : message;
+    const httpStatus = extractHttpStatus(err);
+    const responsePreview = extractResponsePreview(err);
+    return {
+        name,
+        message: capped,
+        ...(httpStatus !== undefined ? { httpStatus } : {}),
+        ...(responsePreview !== undefined ? { responsePreview } : {}),
+    };
+}
+export function isModelNotFoundError(err) {
+    const status = extractHttpStatus(err);
+    if (status === 404)
+        return true;
+    const msg = err instanceof Error ? err.message : String(err);
+    const name = err instanceof Error ? err.name : '';
+    const combined = `${name} ${msg}`.toLowerCase();
+    return (combined.includes('model not found') ||
+        combined.includes('model_not_found') ||
+        combined.includes('model does not exist') ||
+        combined.includes('unknown model') ||
+        combined.includes('invalid model'));
+}
+/** Transient failures — retry the same provider/model candidate. */
+export function isRetryableError(err) {
+    if (isModelNotFoundError(err))
+        return false;
+    const msg = err instanceof Error ? err.message : String(err);
+    const name = err instanceof Error ? err.name : '';
+    const combined = `${name} ${msg}`.toLowerCase();
+    return (combined.includes('timeout') ||
+        combined.includes('timed out') ||
+        combined.includes('rate limit') ||
+        combined.includes('429') ||
+        combined.includes('econnreset') ||
+        combined.includes('etimedout') ||
+        combined.includes('503') ||
+        combined.includes('502') ||
+        combined.includes('504') ||
+        combined.includes('temporarily unavailable'));
+}
+/** Failures that should advance to the next fallback candidate (not retry same candidate). */
+export function isFallbackEligibleError(err) {
+    if (isModelNotFoundError(err))
+        return true;
+    const status = extractHttpStatus(err);
+    if (status !== undefined) {
+        if (status === 404)
+            return true;
+        if (status >= 500)
+            return false;
+        if (status === 429)
+            return false;
+    }
+    return !isRetryableError(err);
+}
+function parseProviderModelRef(entry) {
+    if (!entry || typeof entry !== 'object')
+        return undefined;
+    const ref = entry;
+    const providerRaw = ref.engine ?? ref.provider;
+    if (typeof providerRaw !== 'string' || !providerRaw.trim())
+        return undefined;
+    const provider = providerRaw.trim();
+    const model = typeof ref.model === 'string' && ref.model.trim() ? ref.model.trim() : undefined;
+    return { provider, model };
+}
+function dedupeCandidates(candidates) {
+    const seen = new Set();
+    const out = [];
+    for (const c of candidates) {
+        const key = `${c.provider}\0${c.model ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(c);
+    }
+    return out;
+}
+export function buildFallbackCandidates(input) {
+    const { primaryProvider, primaryModel, requestConfig, routerFallbackChain } = input;
+    const candidates = [{ provider: primaryProvider, model: primaryModel }];
+    const chainRaw = (Array.isArray(requestConfig?.fallbackChain) ? requestConfig.fallbackChain : undefined) ??
+        (Array.isArray(requestConfig?.fallbackEngines) ? requestConfig.fallbackEngines : undefined) ??
+        (Array.isArray(routerFallbackChain) ? routerFallbackChain : undefined);
+    if (Array.isArray(chainRaw) && chainRaw.length > 0) {
+        for (const entry of chainRaw) {
+            const parsed = parseProviderModelRef(entry);
+            if (parsed)
+                candidates.push(parsed);
+        }
+    }
+    else {
+        const fallbackProvidersRaw = requestConfig?.fallbackProviders;
+        const fallbackProviders = Array.isArray(fallbackProvidersRaw)
+            ? fallbackProvidersRaw
+                .filter((p) => typeof p === 'string' && p.trim().length > 0)
+                .map((p) => p.trim())
+            : [];
+        for (const provider of fallbackProviders) {
+            if (provider !== primaryProvider) {
+                candidates.push({ provider, model: primaryModel });
+            }
+        }
+    }
+    return dedupeCandidates(candidates);
+}
+export function buildCandidateRequest(input, candidate) {
+    const baseConfig = (input.request?.config && typeof input.request.config === 'object')
+        ? input.request.config
+        : {};
+    const model = candidate.model ?? (typeof baseConfig.model === 'string' ? baseConfig.model : undefined);
+    return {
+        ...input,
+        request: {
+            ...input.request,
+            ...(model !== undefined ? { model } : {}),
+            config: {
+                ...baseConfig,
+                provider: candidate.provider,
+                ...(model !== undefined ? { model } : {}),
+            },
+        },
+    };
+}

package/dist/router/partialErrorPayload.d.ts

@@ -0,0 +1,26 @@
+import type { ProviderSDKExecResult } from '@x12i/ai-provider-interface';
+import type { AttemptTrace, DiagnosticsMetadata, NormalizedUsage } from './RouterTypes.js';
+export type PartialRouterPayload = {
+    requestId: string;
+    provider: string;
+    usage?: NormalizedUsage;
+    metadata: DiagnosticsMetadata;
+    rawResponse?: unknown;
+};
+export declare function attachPartialRouterPayload(err: unknown, payload: PartialRouterPayload): void;
+export declare function normalizeUsageFromUnknown(usage: unknown): NormalizedUsage | undefined;
+export declare function buildPartialRouterPayload(args: {
+    requestId: string;
+    engineProvider: string;
+    providerModule?: string;
+    modelUsed?: string;
+    maxTokensRequested?: number;
+    timing?: {
+        startedAt: number;
+        endedAt: number;
+        durationMs: number;
+    };
+    attempts?: AttemptTrace[];
+    execResult?: ProviderSDKExecResult;
+    providerError?: unknown;
+}): PartialRouterPayload;

package/dist/router/partialErrorPayload.js

@@ -0,0 +1,133 @@
+export function attachPartialRouterPayload(err, payload) {
+    if (err == null || typeof err !== 'object')
+        return;
+    err.response = payload;
+}
+function firstString(...values) {
+    for (const v of values) {
+        if (typeof v === 'string' && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}
+export function normalizeUsageFromUnknown(usage) {
+    if (!usage || typeof usage !== 'object')
+        return undefined;
+    const u = usage;
+    const promptTokens = (typeof u.promptTokens === 'number' ? u.promptTokens : undefined) ??
+        (typeof u.inputTokens === 'number' ? u.inputTokens : undefined) ??
+        (typeof u.prompt_tokens === 'number' ? u.prompt_tokens : undefined) ??
+        (typeof u.input_tokens === 'number' ? u.input_tokens : undefined) ??
+        (typeof u.prompt === 'number' ? u.prompt : undefined);
+    const completionTokens = (typeof u.completionTokens === 'number' ? u.completionTokens : undefined) ??
+        (typeof u.outputTokens === 'number' ? u.outputTokens : undefined) ??
+        (typeof u.completion_tokens === 'number' ? u.completion_tokens : undefined) ??
+        (typeof u.output_tokens === 'number' ? u.output_tokens : undefined) ??
+        (typeof u.completion === 'number' ? u.completion : undefined);
+    const totalTokens = (typeof u.totalTokens === 'number' ? u.totalTokens : undefined) ??
+        (typeof u.total_tokens === 'number' ? u.total_tokens : undefined) ??
+        (typeof u.total === 'number' ? u.total : undefined);
+    if (promptTokens === undefined && completionTokens === undefined && totalTokens === undefined) {
+        return undefined;
+    }
+    const p = promptTokens ?? 0;
+    const c = completionTokens ?? 0;
+    return { promptTokens: p, completionTokens: c, totalTokens: totalTokens ?? p + c };
+}
+function extractIdsFromRaw(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const r = raw;
+    const id = firstString(r.id, r.request_id, r.requestId);
+    if (!id)
+        return {};
+    return { providerRequestId: id, openrouterRequestId: id };
+}
+function extractRawBody(err) {
+    if (err == null || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const response = e.response;
+    if (response != null && typeof response === 'object') {
+        const resp = response;
+        if (resp.data !== undefined)
+            return resp.data;
+        if (resp.body !== undefined)
+            return resp.body;
+    }
+    for (const key of ['rawResponse', 'body', 'data', 'lastResponse', 'routerResponse']) {
+        if (e[key] !== undefined)
+            return e[key];
+    }
+    const nestedError = e.error;
+    if (nestedError != null && typeof nestedError === 'object') {
+        return extractRawBody(nestedError);
+    }
+    return undefined;
+}
+function extractHeaderRequestId(err) {
+    if (err == null || typeof err !== 'object')
+        return undefined;
+    const e = err;
+    const response = e.response;
+    if (response == null || typeof response !== 'object')
+        return undefined;
+    const headers = response.headers;
+    if (headers == null || typeof headers !== 'object')
+        return undefined;
+    const h = headers;
+    return firstString(h['x-request-id'], h['x-openrouter-request-id'], h['request-id'], h['openrouter-request-id']);
+}
+function usageToGatewayTokens(usage) {
+    return {
+        prompt: usage.promptTokens,
+        completion: usage.completionTokens,
+        total: usage.totalTokens,
+    };
+}
+export function buildPartialRouterPayload(args) {
+    let usage = args.execResult?.rawResponse
+        ? normalizeUsageFromUnknown(args.execResult.rawResponse?.usage)
+        : undefined;
+    let rawResponse = args.execResult?.rawResponse;
+    let ids = rawResponse ? extractIdsFromRaw(rawResponse) : {};
+    const errorBody = extractRawBody(args.providerError);
+    if (errorBody !== undefined) {
+        rawResponse = rawResponse ?? errorBody;
+        usage = usage ?? normalizeUsageFromUnknown(errorBody?.usage);
+        const bodyIds = extractIdsFromRaw(errorBody);
+        ids = { ...bodyIds, ...ids };
+    }
+    const headerRequestId = extractHeaderRequestId(args.providerError);
+    if (headerRequestId) {
+        ids = {
+            providerRequestId: ids.providerRequestId ?? headerRequestId,
+            openrouterRequestId: ids.openrouterRequestId ?? headerRequestId,
+        };
+    }
+    const providerRequestId = ids.providerRequestId;
+    const openrouterRequestId = args.providerModule === 'openrouter' ? providerRequestId : ids.openrouterRequestId;
+    const metadata = {
+        provider: args.providerModule ?? args.engineProvider,
+        ...(args.modelUsed !== undefined ? { modelUsed: args.modelUsed } : {}),
+        ...(args.maxTokensRequested !== undefined ? { maxTokensRequested: args.maxTokensRequested } : {}),
+        requestIds: {
+            routerRequestId: args.requestId,
+            ...(providerRequestId ? { providerRequestId } : {}),
+            ...(openrouterRequestId ? { openrouterRequestId } : {}),
+        },
+        ...(args.timing ? { timing: args.timing, latencyMs: args.timing.durationMs } : {}),
+        ...(args.attempts ? { attempts: args.attempts } : {}),
+    };
+    if (usage) {
+        metadata.usage = usage;
+        metadata.tokens = usageToGatewayTokens(usage);
+    }
+    return {
+        requestId: args.requestId,
+        provider: args.engineProvider,
+        ...(usage ? { usage } : {}),
+        ...(rawResponse !== undefined ? { rawResponse } : {}),
+        metadata,
+    };
+}

package/dist/router.d.ts

@@ -1,5 +1,5 @@
 export { LLMProviderRouter } from './router/RouterWrapper.js';
-export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, ActivityCostStatus, NormalizedRouterOutput } from './router/RouterTypes.js';
+export type { RouterConfig, AIRouterRequest, AIResponse, AIStreamEvent, AIBatchResponse, AIBatchRequestItem, ActivityCostStatus, NormalizedRouterOutput, ProviderModelRef, } from './router/RouterTypes.js';
 export { ProviderRegistry } from './registry/ProviderRegistry.js';
 export { AdapterRegistry } from './registry/AdapterRegistry.js';
 export { OpenAIAdapter } from './adapters/openai/OpenAIAdapter.js';

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.0",
+  "version": "4.8.4",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",