@x12i/ai-providers-router 4.8.6 → 4.8.8

package/README.md

@@ -137,7 +137,7 @@ AIRouterRequest
 | ID | Role |
 |----|------|
 | `openrouter` | Explicit OpenRouter transport |
-| Any vendor ID | Routed through OpenRouter when OpenRouter mode is active |
+| Any vendor ID | Routed through OpenRouter when preferred (`USE_OPENROUTER=true`, default) or as fallback when no direct key |
 
 > **Grok ≠ Groq** — Grok is xAI (`grok` / `xai`). Groq is GroqCloud (`groq`).
 
@@ -145,7 +145,7 @@ AIRouterRequest
 
 ## OpenRouter mode
 
-OpenRouter is a unified API gateway. When enabled, calls can use familiar provider names (`openai`, `grok`, `anthropic`, …) while traffic routes through OpenRouter with automatic model mapping (e.g. `openai` + `gpt-4o` → `openai/gpt-4o`).
+OpenRouter is a unified API gateway. With an `OPENROUTER_API_KEY`, the router can reach models from many vendors through one key — using familiar provider names (`openai`, `grok`, `anthropic`, …) and automatic model mapping (e.g. `openai` + `gpt-4o` → `openai/gpt-4o`).
 
 ### Enable OpenRouter
 
@@ -157,26 +157,52 @@ export OPENROUTER_API_KEY=sk-or-your-key-here
 # export OPEN_ROUTER_KEY=sk-or-your-key-here
 ```
 
-OpenRouter mode activates automatically when a valid key is present. To disable explicitly:
+Optional ranking headers:
 
 ```bash
-export USE_OPENROUTER=false
+export OPENROUTER_HTTP_REFERER=https://your-site.com   # legacy: OPEN_ROUTER_HTTP_REFERER
+export OPENROUTER_X_TITLE=Your Site Name               # legacy: OPEN_ROUTER_X_TITLE
 ```
 
-Optional ranking headers:
+### `USE_OPENROUTER` — prefer vs fallback
+
+`USE_OPENROUTER` does **not** turn OpenRouter on or off. The router always registers OpenRouter when a key is present. This flag controls **whether OpenRouter is preferred over direct provider keys**.
+
+| `USE_OPENROUTER` | `OPENROUTER_API_KEY` | Direct provider key (e.g. `OPENAI_API_KEY`) | What happens |
+|------------------|----------------------|---------------------------------------------|--------------|
+| unset or `true` *(default)* | set | set or unset | **Prefer OpenRouter** — all vendor calls route through OpenRouter, even when a direct key exists |
+| unset or `true` | set | not set | Route through OpenRouter |
+| `false` | set | set for requested vendor | **Direct provider** — use the vendor's own key/API |
+| `false` | set | not set for requested vendor | **OpenRouter fallback** — e.g. request `anthropic` with no `ANTHROPIC_API_KEY` still works via OpenRouter |
+
+**Default:** prefer OpenRouter whenever `OPENROUTER_API_KEY` is set (`USE_OPENROUTER` defaults to `true`).
+
+To use direct provider keys when available, while keeping OpenRouter as fallback for vendors without keys:
 
 ```bash
-export OPENROUTER_HTTP_REFERER=https://your-site.com   # legacy: OPEN_ROUTER_HTTP_REFERER
-export OPENROUTER_X_TITLE=Your Site Name               # legacy: OPEN_ROUTER_X_TITLE
+export USE_OPENROUTER=false
+export OPENROUTER_API_KEY=sk-or-...
+export OPENAI_API_KEY=sk-...          # openai requests → direct OpenAI
+# no ANTHROPIC_API_KEY              # anthropic requests → OpenRouter fallback
 ```
 
-### Behavior
+Programmatic override:
 
+```ts
+const router = await createRouter({
+  useOpenRouter: false, // direct when keys exist; OpenRouter fallback otherwise
+});
+```
+
+### Behavior summary
+
+- **OpenRouter is always available** when `OPENROUTER_API_KEY` is set — used as the default transport or as fallback
+- **`USE_OPENROUTER=true` (default):** routes through OpenRouter even if `OPENAI_API_KEY`, `GROK_API_KEY`, etc. are also set; direct provider packages are not auto-registered (avoids singleton config conflicts)
+- **`USE_OPENROUTER=false`:** auto-registers direct providers when their API keys exist; OpenRouter handles any vendor without a direct key
 - Works with `createRouter()` and `new LLMProviderRouter()` — auto-registration on first call
-- Provider names stay the same in your code; the router handles routing internally
+- Provider names stay the same in your code; the router handles transport selection internally
 - Catalog data (`.metadata/openrouter_catalog_with_vendor_mapping.json`) drives model validation and provider inference
-- When OpenRouter mode is active, direct provider packages are **not** auto-registered (avoids singleton config conflicts)
-- Responses are parsed directly from OpenAI-compatible formats (no `ai-io-normalizer` on the OpenRouter path)
+- Responses on the OpenRouter path are parsed directly from OpenAI-compatible formats (no `ai-io-normalizer`)
 
 ### Examples
 
@@ -245,6 +271,7 @@ const router = await createRouter({
   logLevel: 'info',
   verbose: false,
   timeoutMs: 60_000,
+  useOpenRouter: true, // default: prefer OpenRouter when OPENROUTER_API_KEY is set
   fallbackChain: [{ provider: 'openai', model: 'gpt-4o-mini' }, { provider: 'grok', model: 'grok-2' }],
   openrouter: { apiKey: 'sk-or-...', httpReferer: 'https://example.com', xTitle: 'My App' },
   usageTracker: {
@@ -278,9 +305,9 @@ Passing any explicit config object to `createRouter(config)` overrides zero-conf
 | `GROK_API_KEY` | — | Required for direct Grok calls |
 | `XAI_API_BASE` | — | Custom xAI base URL |
 | **OpenRouter** | | |
-| `OPENROUTER_API_KEY` | — | Canonical OpenRouter key |
-| `OPEN_ROUTER_KEY` | — | Legacy alias |
-| `USE_OPENROUTER` | auto | `true` when key present; set `false` to disable |
+| `OPENROUTER_API_KEY` | — | Enables OpenRouter (always registered when set) |
+| `OPEN_ROUTER_KEY` | — | Legacy alias for `OPENROUTER_API_KEY` |
+| `USE_OPENROUTER` | `true` | Prefer OpenRouter over direct keys when OR key is set; set `false` to use direct providers when keys exist (OpenRouter remains fallback) |
 | `OPENROUTER_HTTP_REFERER` | — | Optional ranking header |
 | `OPENROUTER_X_TITLE` | — | Optional ranking header |
 | **Other providers** | | |
@@ -309,20 +336,44 @@ AI_PROVIDER_ROUTER_VERBOSE=true
 
 **Log levels:** `error` · `warn` · `info` · `debug` · `verbose` · `off`
 
-When neither `_LOGS_LEVEL` nor `_LOG_LEVEL` is set and no programmatic `logLevel` is passed, logxer defaults to `warn`. The router's `createRouter()` zero-config path resolves `AI_PROVIDER_ROUTER_LOG_LEVEL` with default `info`.
+When neither `_LOGS_LEVEL` nor `_LOG_LEVEL` is set, no `logLevel` / `logging` is passed, and the logxer registry has no entry, the router defaults to **`info`** (not logxer's package-only default of `warn`). `createRouter()` loads `LOGXER_PACKAGE_LEVELS` / `LOGXER_PACKAGE_LOGS_DEFAULT` via `applyPackageLogLevelsFromEnv()` after `.env`.
 
-**Programmatic:**
+**Host apps (logxer ≥ 4.5)** — provider packages (`@x12i/ai-provider-openai`, etc.) are **not** on the logxer 4.5 stack. Stack/registry options apply **only** to this router's logs (`AI_PROVIDER_ROUTER`). Configure your other libraries from `@x12i/logxer` in the host; pass the same `StackLoggingOptions` into `createRouter` when you want one object for the whole app:
 
 ```ts
-import { createRouter, createLogger, getLogger } from '@x12i/ai-providers-router';
+import { configurePackageLogLevels, type StackLoggingOptions } from '@x12i/logxer';
+import { createRouter, ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
+
+configurePackageLogLevels({
+  default: 'warn',
+  levels: {
+    MY_GATEWAY: 'info',
+    [ROUTER_LOG_ENV_PREFIX]: 'debug',
+  },
+});
 
-const router = await createRouter({ logLevel: 'debug', verbose: true });
+const logging: StackLoggingOptions = {
+  packageLevels: { [ROUTER_LOG_ENV_PREFIX]: 'debug' },
+};
+
+const router = await createRouter({ logging, verbose: true });
+```
 
-// Or inject a custom logger instance
+Bulk env for this package (loaded by `createRouter()` after `.env`):
+
+```bash
+LOGXER_PACKAGE_LEVELS=AI_PROVIDER_ROUTER:info
+AI_PROVIDER_ROUTER_LOGS_LEVEL=error   # wins over bulk for this prefix only
+```
+
+**Programmatic (router only):**
+
+```ts
+const router = await createRouter({ logLevel: 'debug', verbose: true });
 const router2 = await createRouter({ logger: createLogger({ level: 'info', verbose: false }) });
 ```
 
-Verbose mode logs sanitized AI request/response payloads (passwords, secrets, and API keys are redacted). Cross-cutting log sinks (console, file, format) are configured at the host/app level via logxer — not per-package.
+Verbose mode logs sanitized AI request/response payloads. Cross-cutting sinks (console, file, format) are configured in the **host** via `@x12i/logxer` — not via provider packages.
 
 ---
 
@@ -495,7 +546,7 @@ router.addResponseInterceptor(async (res, provider) => {
 });
 ```
 
-OpenRouter mode registers a request interceptor automatically to route vendor calls through OpenRouter while preserving the original provider name for model mapping.
+OpenRouter registers a request interceptor when `USE_OPENROUTER=true` (default) to route vendor calls through OpenRouter while preserving the original provider name for model mapping. When `USE_OPENROUTER=false`, the interceptor is skipped; `resolveProviderName` uses direct providers when registered and falls back to OpenRouter otherwise.
 
 ### Health checks
 
@@ -586,7 +637,7 @@ const registry = router.getProviderRegistry();
 const adapters = router.getAdapterRegistry();
 ```
 
-Providers are also **auto-registered on first invoke** when matching API keys are in the environment (unless OpenRouter mode is active).
+Providers are **auto-registered on first invoke** when matching API keys are in the environment. When `USE_OPENROUTER=true` (default) and `OPENROUTER_API_KEY` is set, direct providers are skipped in favor of OpenRouter. With `USE_OPENROUTER=false`, both direct providers and OpenRouter can be registered simultaneously.
 
 Legacy config file support:
 

package/dist/factory.js

@@ -1,6 +1,7 @@
+import { applyPackageLogLevelsFromEnv } from '@x12i/logxer';
 import { LLMProviderRouter } from './router/RouterWrapper.js';
 import dns from 'node:dns';
-import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC } from './utils/openrouterEnv.js';
+import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, resolveUseOpenRouter } 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
@@ -28,6 +29,7 @@ dns.setDefaultResultOrder('ipv4first');
 // This ensures nx-config2 can resolve ENV. placeholders
 // dotenv.config() is idempotent and won't overwrite existing process.env values
 dotenv.config();
+applyPackageLogLevelsFromEnv();
 /**
  * Resolve ENV. placeholders to actual environment variable values
  * Replaces nx-config2 functionality to avoid ESM/CommonJS compatibility issues
@@ -89,6 +91,7 @@ export async function createRouter(config) {
     const ercConfig = {
         // Router-specific configuration
         router: {
+            logsLevel: 'ENV.AI_PROVIDER_ROUTER_LOGS_LEVEL',
             logLevel: 'ENV.AI_PROVIDER_ROUTER_LOG_LEVEL||info',
             verbose: 'ENV.AI_PROVIDER_ROUTER_VERBOSE||false',
             timeoutMs: 'ENV.AI_PROVIDER_ROUTER_TIMEOUT_MS||60000',
@@ -131,41 +134,23 @@ export async function createRouter(config) {
         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,
+    const useOpenRouter = resolveUseOpenRouter({
+        userValue: config?.useOpenRouter,
+    });
+    const finalConfig = Object.keys(config || {}).length > 0 ? {
+        ...config,
+        useOpenRouter: config?.useOpenRouter ?? useOpenRouter,
+    } : {
+        logLevel: (ercResult.config.router.logsLevel ||
+            ercResult.config.router.logLevel),
         verbose: ercResult.config.router.verbose === 'true' || ercResult.config.router.verbose === true,
         timeoutMs: ercResult.config.router.timeoutMs ? parseInt(String(ercResult.config.router.timeoutMs), 10) : undefined,
         defaultTimeoutMs: ercResult.config.router.timeoutMs ? parseInt(String(ercResult.config.router.timeoutMs), 10) : undefined,
+        useOpenRouter,
     };
     const router = new LLMProviderRouter(finalConfig);
     // 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 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 ?? 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
-    // Default to true if key is present, unless explicitly disabled
-    let useOpenRouter = false;
-    if (hasValidKey) {
-        if (useOpenRouterEnv === undefined || useOpenRouterEnv === '' || useOpenRouterEnv === 'true' || useOpenRouterEnv === true) {
-            useOpenRouter = true;
-        }
-        else if (useOpenRouterEnv === 'false' || useOpenRouterEnv === false) {
-            useOpenRouter = false;
-        }
-        else {
-            // Default to true if key is present
-            useOpenRouter = true;
-        }
-    }
     // NOTE: We don't need to manually register providers here anymore if they are 
     // in environment variables, as LLMProviderRouter will auto-register them 
     // on first invoke/stream/createBatch call.

package/dist/index.d.ts

@@ -7,8 +7,8 @@ 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';
-export type { LogLevel, LoggerConfig } from './logger.js';
+export { Logger, getLogger, createLogger, createRouterLogxer, ROUTER_LOG_ENV_PREFIX, DebugLogAbstract, runWithLogContext, getLogContext, patchLogContext, applyPackageLogLevelsFromEnv, } from './logger.js';
+export type { LogLevel, LoggerConfig, LogMeta, LogRuntimeContext, StackLoggingOptions } from './logger.js';
 export { AIGateway } from './gateway.js';
 export type { EnhancedLLMResponse } from './gateway.js';
 export { applyResponseNormalization } from './normalization/applyResponseNormalization.js';

package/dist/index.js

@@ -38,8 +38,8 @@ export {
 export { createRouter, createRouterFromConfig } from './factory.js';
 // Error classes
 export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError, ProviderTimeoutError } from './errors.js';
-// Logger
-export { Logger, getLogger, createLogger } from './logger.js';
+// Logger (logxer correlation; host `StackLoggingOptions` via createRouter / LoggerConfig)
+export { Logger, getLogger, createLogger, createRouterLogxer, ROUTER_LOG_ENV_PREFIX, DebugLogAbstract, runWithLogContext, getLogContext, patchLogContext, applyPackageLogLevelsFromEnv, } from './logger.js';
 // Gateway (thin invoke wrapper)
 export { AIGateway } from './gateway.js';
 // Response normalization (Run Analysis G6/G8)

package/dist/logger.d.ts

@@ -1,13 +1,29 @@
 /**
  * Logging utility for AI Provider Router
- * Provides structured logging with proper log levels and verbose mode support
+ * Wraps @x12i/logxer with package config, verbose AI payload logging, and correlation context.
  */
-import { type LogLevel } from '@x12i/logxer';
-export type { LogLevel };
+import { applyPackageLogLevelsFromEnv, DebugLogAbstract, runWithLogContext, getLogContext, patchLogContext, type Logxer, type LogLevel, type LogMeta, type LogRuntimeContext, type StackLoggingOptions, type ScopeCriteria, type ScopeLogsOptions, type ScopeLogsResult, type GetJobLogsInput, type GetJobLogsResult } from '@x12i/logxer';
+export type { LogLevel, LogMeta, LogRuntimeContext, StackLoggingOptions };
+export { DebugLogAbstract, runWithLogContext, getLogContext, patchLogContext, applyPackageLogLevelsFromEnv, };
+/** Stable logxer `envPrefix` for this package (`AI_PROVIDER_ROUTER_LOGS_LEVEL`). */
+export declare const ROUTER_LOG_ENV_PREFIX = "AI_PROVIDER_ROUTER";
 export interface LoggerConfig {
     verbose?: boolean;
+    /** Explicit instance level (wins over `logging` stack and registry). */
     level?: LogLevel;
+    /**
+     * From the **host application** (logxer ≥ 4.5). Resolved only for `AI_PROVIDER_ROUTER`.
+     * Does not configure provider dependencies (they are not on the logxer 4.5 stack).
+     */
+    logging?: StackLoggingOptions;
 }
+/**
+ * Create a logxer instance for this package (prefer over ad-hoc `createLogxer` in consumers).
+ */
+export declare function createRouterLogxer(options?: {
+    logging?: StackLoggingOptions;
+    level?: LogLevel;
+}): Logxer;
 /**
  * Logger class that wraps logxer with proper log levels
  */
@@ -15,53 +31,33 @@ export declare class Logger {
     verbose: boolean;
     level: LogLevel;
     private gateway;
+    private logging?;
     constructor(config?: LoggerConfig);
     /**
      * Update logger configuration
      */
     setConfig(config: LoggerConfig): void;
-    /**
-     * Log error messages
-     */
-    error(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Log warning messages
-     */
-    warn(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Log informational messages
-     */
-    info(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Log debug messages
-     */
-    debug(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Log verbose messages (only when verbose mode is enabled)
-     */
-    logVerbose(message: string, data?: Record<string, unknown>): void;
-    /**
-     * Log AI request (unfiltered, only in verbose mode)
-     */
-    logAIRequest(provider: string, request: unknown, metadata?: Record<string, unknown>): void;
-    /**
-     * Log AI response (unfiltered, only in verbose mode)
-     */
-    logAIResponse(provider: string, response: unknown, metadata?: Record<string, unknown>): void;
-    /**
-     * Log AI request/response pair (unfiltered, only in verbose mode)
-     */
-    logAIIteraction(provider: string, request: unknown, response: unknown, duration?: number, metadata?: Record<string, unknown>): void;
-    /**
-     * Sanitize data for logging (remove sensitive info, handle circular refs)
+    getConfig(): Readonly<ReturnType<Logxer['getConfig']>>;
+    isLevelEnabled(level: LogLevel): boolean;
+    infoCode(code: string, data?: LogMeta): void;
+    warnCode(code: string, data?: LogMeta): void;
+    errorCode(code: string, data?: LogMeta): void;
+    diagnostic(level: LogLevel, message: string, data?: LogMeta): void;
+    success(message: string, data?: LogMeta): void;
+    scopeLogs(criteria: ScopeCriteria, options?: ScopeLogsOptions): Promise<ScopeLogsResult>;
+    getJobLogs(input: GetJobLogsInput): Promise<GetJobLogsResult>;
+    error(message: string, data?: LogMeta): void;
+    warn(message: string, data?: LogMeta): void;
+    info(message: string, data?: LogMeta): void;
+    debug(message: string, data?: LogMeta): void;
+    logVerbose(message: string, data?: LogMeta): void;
+    logAIRequest(provider: string, request: unknown, metadata?: LogMeta): void;
+    logAIResponse(provider: string, response: unknown, metadata?: LogMeta): void;
+    logAIIteraction(provider: string, request: unknown, response: unknown, duration?: number, metadata?: LogMeta): void;
+    /**
+     * @deprecated Logxer sanitizes payloads on emit when `sanitization.enabled` is set (default for this logger).
      */
     sanitizeForLogging(data: unknown): unknown;
 }
-/**
- * Get or create the default logger instance
- */
 export declare function getLogger(config?: LoggerConfig): Logger;
-/**
- * Create a new logger instance
- */
 export declare function createLogger(config?: LoggerConfig): Logger;

package/dist/logger.js

@@ -1,15 +1,55 @@
 /**
  * Logging utility for AI Provider Router
- * Provides structured logging with proper log levels and verbose mode support
+ * Wraps @x12i/logxer with package config, verbose AI payload logging, and correlation context.
  */
-import { createLogxer } from '@x12i/logxer';
+import { applyPackageLogLevelsFromEnv, createLogxer, DebugLogAbstract, runWithLogContext, getLogContext, patchLogContext, } from '@x12i/logxer';
+export { DebugLogAbstract, runWithLogContext, getLogContext, patchLogContext, applyPackageLogLevelsFromEnv, };
+/** Stable logxer `envPrefix` for this package (`AI_PROVIDER_ROUTER_LOGS_LEVEL`). */
+export const ROUTER_LOG_ENV_PREFIX = 'AI_PROVIDER_ROUTER';
 const LOGXER_PACKAGE = {
     packageName: 'AI Provider Router',
-    envPrefix: 'AI_PROVIDER_ROUTER',
+    envPrefix: ROUTER_LOG_ENV_PREFIX,
     debugNamespace: 'ai-providers-router',
 };
-function createGateway(level) {
-    return createLogxer(LOGXER_PACKAGE, level !== undefined ? { logLevel: level } : undefined);
+const DEFAULT_LOGXER_OPTIONS = {
+    sanitization: {
+        enabled: true,
+        detectAPIKeys: true,
+        detectPasswords: true,
+        detectJWTs: true,
+        detectEmails: true,
+    },
+    diagnostics: {
+        enabled: true,
+        consoleMode: 'summary',
+    },
+};
+let packageLevelsEnvApplied = false;
+function ensurePackageLogLevelsFromEnv() {
+    if (packageLevelsEnvApplied)
+        return;
+    applyPackageLogLevelsFromEnv();
+    packageLevelsEnvApplied = true;
+}
+function buildUserConfig(options) {
+    ensurePackageLogLevelsFromEnv();
+    const config = {
+        ...DEFAULT_LOGXER_OPTIONS,
+        ...(options.logging !== undefined ? { stack: options.logging } : {}),
+    };
+    if (options.level !== undefined) {
+        config.logLevel = options.level;
+    }
+    return config;
+}
+function createGateway(options = {}) {
+    return createLogxer(LOGXER_PACKAGE, buildUserConfig(options));
+}
+/**
+ * Create a logxer instance for this package (prefer over ad-hoc `createLogxer` in consumers).
+ */
+export function createRouterLogxer(options) {
+    return createGateway(options);
 }
 /**
  * Logger class that wraps logxer with proper log levels
@@ -17,7 +57,8 @@ function createGateway(level) {
 export class Logger {
     constructor(config = {}) {
         this.verbose = config.verbose ?? false;
-        this.gateway = createGateway(config.level);
+        this.logging = config.logging;
+        this.gateway = createGateway({ level: config.level, logging: config.logging });
         this.level = config.level ?? this.gateway.getConfig().logLevel;
     }
     /**
@@ -27,138 +68,109 @@ export class Logger {
         if (config.verbose !== undefined) {
             this.verbose = config.verbose;
         }
-        if (config.level !== undefined) {
-            this.level = config.level;
-            this.gateway = createGateway(config.level);
+        if (config.logging !== undefined) {
+            this.logging = config.logging;
+        }
+        if (config.level !== undefined || config.logging !== undefined) {
+            if (config.level !== undefined) {
+                this.level = config.level;
+            }
+            this.gateway = createGateway({
+                level: config.level ?? this.level,
+                logging: config.logging ?? this.logging,
+            });
+            if (config.level === undefined) {
+                this.level = this.gateway.getConfig().logLevel;
+            }
         }
     }
-    /**
-     * Log error messages
-     */
+    getConfig() {
+        return this.gateway.getConfig();
+    }
+    isLevelEnabled(level) {
+        return this.gateway.isLevelEnabled(level);
+    }
+    infoCode(code, data) {
+        this.gateway.infoCode(code, data);
+    }
+    warnCode(code, data) {
+        this.gateway.warnCode(code, data);
+    }
+    errorCode(code, data) {
+        this.gateway.errorCode(code, data);
+    }
+    diagnostic(level, message, data) {
+        this.gateway.diagnostic(level, message, data);
+    }
+    success(message, data) {
+        this.gateway.success(message, data);
+    }
+    scopeLogs(criteria, options) {
+        return this.gateway.scopeLogs(criteria, options);
+    }
+    getJobLogs(input) {
+        return this.gateway.getJobLogs(input);
+    }
     error(message, data) {
         this.gateway.error(message, data ?? {});
     }
-    /**
-     * Log warning messages
-     */
     warn(message, data) {
         this.gateway.warn(message, data ?? {});
     }
-    /**
-     * Log informational messages
-     */
     info(message, data) {
         this.gateway.info(message, data ?? {});
     }
-    /**
-     * Log debug messages
-     */
     debug(message, data) {
         this.gateway.debug(message, data ?? {});
     }
-    /**
-     * Log verbose messages (only when verbose mode is enabled)
-     */
     logVerbose(message, data) {
         if (!this.verbose)
             return;
         this.gateway.verbose(message, data ?? {});
     }
-    /**
-     * Log AI request (unfiltered, only in verbose mode)
-     */
     logAIRequest(provider, request, metadata) {
         if (!this.verbose)
             return;
         this.logVerbose('AI Request Sent', {
             provider,
-            request: this.sanitizeForLogging(request),
+            request,
             metadata: metadata ?? {},
             timestamp: new Date().toISOString(),
+            debugKind: DebugLogAbstract.STATE,
         });
     }
-    /**
-     * Log AI response (unfiltered, only in verbose mode)
-     */
     logAIResponse(provider, response, metadata) {
         if (!this.verbose)
             return;
         this.logVerbose('AI Response Received', {
             provider,
-            response: this.sanitizeForLogging(response),
+            response,
             metadata: metadata ?? {},
             timestamp: new Date().toISOString(),
+            debugKind: DebugLogAbstract.STATE,
         });
     }
-    /**
-     * Log AI request/response pair (unfiltered, only in verbose mode)
-     */
     logAIIteraction(provider, request, response, duration, metadata) {
         if (!this.verbose)
             return;
         this.logVerbose('AI Interaction Complete', {
             provider,
-            request: this.sanitizeForLogging(request),
-            response: this.sanitizeForLogging(response),
+            request,
+            response,
             duration: duration ? `${duration}ms` : undefined,
             metadata: metadata ?? {},
             timestamp: new Date().toISOString(),
+            debugKind: DebugLogAbstract.EVENT,
         });
     }
     /**
-     * Sanitize data for logging (remove sensitive info, handle circular refs)
+     * @deprecated Logxer sanitizes payloads on emit when `sanitization.enabled` is set (default for this logger).
      */
     sanitizeForLogging(data) {
-        if (data === null || data === undefined) {
-            return data;
-        }
-        const seen = new WeakSet();
-        const sanitize = (obj, depth = 0) => {
-            if (depth > 10) {
-                return '[Max Depth Reached]';
-            }
-            if (obj === null || obj === undefined) {
-                return obj;
-            }
-            if (typeof obj === 'string' || typeof obj === 'number' || typeof obj === 'boolean') {
-                return obj;
-            }
-            if (typeof obj === 'object') {
-                if (seen.has(obj)) {
-                    return '[Circular Reference]';
-                }
-                seen.add(obj);
-                if (Array.isArray(obj)) {
-                    return obj.map((item) => sanitize(item, depth + 1));
-                }
-                if (Buffer.isBuffer(obj)) {
-                    return `[Buffer: ${obj.length} bytes]`;
-                }
-                const result = {};
-                for (const key in obj) {
-                    if (Object.prototype.hasOwnProperty.call(obj, key)) {
-                        if (key.toLowerCase().includes('password') ||
-                            key.toLowerCase().includes('secret') ||
-                            key.toLowerCase().includes('apikey') ||
-                            (key.toLowerCase().includes('token') && key !== 'token')) {
-                            result[key] = '[REDACTED]';
-                        }
-                        else {
-                            result[key] = sanitize(obj[key], depth + 1);
-                        }
-                    }
-                }
-                return result;
-            }
-            return String(obj);
-        };
-        return sanitize(data);
+        return data;
     }
 }
 let defaultLogger = null;
-/**
- * Get or create the default logger instance
- */
 export function getLogger(config) {
     if (!defaultLogger) {
         defaultLogger = new Logger(config);
@@ -168,9 +180,6 @@ export function getLogger(config) {
     }
     return defaultLogger;
 }
-/**
- * Create a new logger instance
- */
 export function createLogger(config = {}) {
     return new Logger(config);
 }

package/dist/router/Router.d.ts

@@ -15,7 +15,9 @@ export declare class AIRouter {
      */
     private resolveProviderNameForCandidate;
     /**
-     * Resolve provider name from request, checking OpenRouter mode first
+     * Resolve provider name from request.
+     * Prefers OpenRouter when USE_OPENROUTER is true (default); falls back to OpenRouter when
+     * the requested vendor has no direct provider registered but an OpenRouter key exists.
      */
     private resolveProviderName;
     /**

package/dist/router/Router.js

@@ -3,7 +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 { hasOpenRouterApiKey, shouldPreferOpenRouter } from '../utils/openrouterEnv.js';
 import { attachPartialRouterPayload, buildPartialRouterPayload } from './partialErrorPayload.js';
 /**
  * Main router class
@@ -32,64 +32,62 @@ export class AIRouter {
         return this.resolveProviderName(candidateInput);
     }
     /**
-     * Resolve provider name from request, checking OpenRouter mode first
+     * Resolve provider name from request.
+     * Prefers OpenRouter when USE_OPENROUTER is true (default); falls back to OpenRouter when
+     * the requested vendor has no direct provider registered but an OpenRouter key exists.
      */
     resolveProviderName(input) {
         const hasOpenRouterAdapter = this.adapters.has('openrouter');
         const hasOpenRouterProvider = this.providers.has('openrouter');
-        // 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 preferOpenRouter = shouldPreferOpenRouter(this.routerConfig);
+        const canUseOpenRouter = hasOpenRouterProvider || (hasOpenRouterAdapter && hasOpenRouterKey);
         const cfgProviderRaw = input.request?.config?.provider;
         const cfgProvider = typeof cfgProviderRaw === 'string' ? cfgProviderRaw.trim() : undefined;
         const hasProviderInConfig = !!cfgProvider && cfgProvider !== '';
-        const hasProviderAtTopLevel = input.provider === 'openrouter';
+        const topLevelProvider = typeof input.provider === 'string' && input.provider.trim() !== ''
+            ? input.provider.trim()
+            : undefined;
         const hasRegisteredProviders = this.providers.list().length > 0;
-        // OpenRouter mode detection (COMPLETELY AUTOMATIC):
-        // 1. Explicit: top-level provider is 'openrouter'
-        // 2. OpenRouter provider is registered (when OPEN_ROUTER_KEY is set via factory)
-        // 3. AUTOMATIC: OpenRouter adapter exists + OPEN_ROUTER_KEY env var is set + config.provider is specified
-        //    This works even when router is created manually without calling createRouter()
-        // 4. Fallback: adapter exists + config.provider + no providers registered (auto-detect)
-        // 
-        // IMPORTANT: When OpenRouter provider is registered OR OPEN_ROUTER_KEY is set, OpenRouter mode is active.
-        // All provider names (openai, grok, anthropic, etc.) route through OpenRouter.
-        // The interceptor sets input.provider = 'openrouter' when OpenRouter mode is enabled.
-        const isOpenRouterMode = hasProviderAtTopLevel ||
-            hasOpenRouterProvider || // OpenRouter provider registered = OpenRouter mode is DEFAULT
-            (hasOpenRouterAdapter && hasOpenRouterKey && hasProviderInConfig) || // AUTOMATIC: env var + adapter + config.provider
-            (hasOpenRouterAdapter && hasProviderInConfig && !hasRegisteredProviders); // Fallback: adapter + config.provider + no providers
-        if (isOpenRouterMode) {
+        if (topLevelProvider === 'openrouter' || cfgProvider === 'openrouter') {
+            return 'openrouter';
+        }
+        if (preferOpenRouter && canUseOpenRouter) {
             return 'openrouter';
         }
-        // Honor request.config.provider in normal flow
         if (hasProviderInConfig) {
-            // Validate provider is registered
-            if (!this.providers.has(cfgProvider)) {
-                const available = this.providers.list().join(', ');
-                // 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 OPENROUTER_API_KEY environment variable to enable automatic OpenRouter mode. ` +
-                        `Available providers: ${available || '(none)'}`);
+            if (this.providers.has(cfgProvider)) {
+                if (!this.adapters.has(cfgProvider)) {
+                    const available = this.adapters.list().join(', ');
+                    throw new Error(`Adapter '${cfgProvider}' specified in request.config.provider but not registered. Available adapters: ${available || '(none)'}`);
                 }
-                throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. Available providers: ${available || '(none)'}`);
+                return cfgProvider;
+            }
+            if (canUseOpenRouter) {
+                return 'openrouter';
+            }
+            const available = this.providers.list().join(', ');
+            if (hasOpenRouterAdapter && !hasOpenRouterKey) {
+                throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. ` +
+                    `OpenRouter adapter is available - set OPENROUTER_API_KEY environment variable to enable OpenRouter fallback. ` +
+                    `Available providers: ${available || '(none)'}`);
+            }
+            throw new Error(`Provider '${cfgProvider}' specified in request.config.provider but not registered. Available providers: ${available || '(none)'}`);
+        }
+        if (topLevelProvider) {
+            if (this.providers.has(topLevelProvider)) {
+                return topLevelProvider;
             }
-            // Validate adapter is registered
-            if (!this.adapters.has(cfgProvider)) {
-                const available = this.adapters.list().join(', ');
-                throw new Error(`Adapter '${cfgProvider}' specified in request.config.provider but not registered. Available adapters: ${available || '(none)'}`);
+            if (canUseOpenRouter) {
+                return 'openrouter';
             }
-            return cfgProvider;
         }
-        // Existing fallback: top-level provider or first registered provider
         const providerName = input.provider ?? this.providers.list()[0];
         if (!providerName) {
-            // Improved error messages with OpenRouter mode guidance
             if (hasProviderInConfig && hasOpenRouterAdapter && !hasRegisteredProviders) {
                 if (!hasOpenRouterKey) {
                     throw new Error('OpenRouter adapter available and config.provider specified, but OpenRouter provider module not registered. ' +
-                        'Set OPENROUTER_API_KEY environment variable to enable automatic OpenRouter mode (works with both createRouter() and manual initialization).');
+                        'Set OPENROUTER_API_KEY environment variable to enable OpenRouter fallback (works with both createRouter() and manual initialization).');
                 }
                 throw new Error('OpenRouter adapter available and config.provider specified, but OpenRouter provider module not registered. ' +
                     'OPENROUTER_API_KEY is set but provider module initialization failed. Check that @x12i/ai-provider-openai is installed.');
@@ -97,10 +95,9 @@ export class AIRouter {
             if (hasProviderInConfig && !hasOpenRouterAdapter) {
                 throw new Error(`Provider '${input.request?.config?.provider}' specified in config but no providers registered and OpenRouter adapter not available.`);
             }
-            // Final fallback error with OpenRouter suggestion
             if (hasOpenRouterAdapter && !hasOpenRouterKey) {
                 throw new Error('No provider specified and no providers registered. ' +
-                    'OpenRouter adapter is available - set OPENROUTER_API_KEY environment variable to enable automatic OpenRouter mode.');
+                    'OpenRouter adapter is available - set OPENROUTER_API_KEY environment variable to enable OpenRouter fallback.');
             }
             throw new Error('No provider specified and no providers registered');
         }

package/dist/router/RouterTypes.d.ts

@@ -72,6 +72,8 @@ export type DiagnosticsMetadata = {
     /** Allow additional vendor/provider specific keys. */
     [key: string]: unknown;
 };
+import type { Logger } from '../logger.js';
+import type { LogLevel, StackLoggingOptions } from '@x12i/logxer';
 /**
  * Router configuration
  */
@@ -91,10 +93,21 @@ export interface RouterConfig {
         }): void;
     };
     verbose?: boolean;
-    logLevel?: 'error' | 'warn' | 'info' | 'debug' | 'verbose';
-    logger?: any;
+    logLevel?: LogLevel;
+    /**
+     * Host-app pass-through (logxer ≥ 4.5). Affects **only** this package's logger
+     * (`AI_PROVIDER_ROUTER` via `stack`). Provider packages under the router do not use logxer 4.5.
+     */
+    logging?: StackLoggingOptions;
+    logger?: Logger;
     timeoutMs?: number;
     defaultTimeoutMs?: number;
+    /**
+     * Prefer OpenRouter for vendor calls when OPENROUTER_API_KEY is set (default: true).
+     * Maps to USE_OPENROUTER env. When false, direct providers are used when keys exist;
+     * OpenRouter is still used as fallback for providers without a direct key.
+     */
+    useOpenRouter?: boolean;
     /** OpenRouter provider config (e.g. from gateway); used when env OPEN_ROUTER_KEY is not visible */
     openrouter?: {
         apiKey?: string;

package/dist/router/RouterWrapper.d.ts

@@ -39,6 +39,7 @@ export declare class LLMProviderRouter {
      * Invoke router (sync mode)
      */
     invoke(request: AIRouterRequest): Promise<AIResponse>;
+    private invokeWithLogContext;
     /**
      * Stream request
      */

package/dist/router/RouterWrapper.js

@@ -4,8 +4,8 @@ import { AdapterRegistry } from '../registry/AdapterRegistry.js';
 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 { getLogger, runWithLogContext, DebugLogAbstract } from '../logger.js';
+import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, shouldPreferOpenRouter } from '../utils/openrouterEnv.js';
 import { resolveModelVendorSlug } from '../utils/openrouterModelVendor.js';
 /**
  * Resolve ENV. placeholders to actual environment variable values
@@ -52,7 +52,12 @@ export class LLMProviderRouter {
         // Initialize logger
         this.logger = config?.logger || getLogger({
             verbose: config?.verbose || false,
-            level: config?.logLevel || 'info',
+            logging: config?.logging,
+            ...(config?.logLevel !== undefined
+                ? { level: config.logLevel }
+                : config?.logging
+                    ? {}
+                    : { level: 'info' }),
         });
         // Initialize registries
         this.providerRegistry = new ProviderRegistry();
@@ -66,6 +71,7 @@ export class LLMProviderRouter {
         this.logger.info('Router initialized with ProviderModule architecture', {
             verbose: this.logger.verbose,
             logLevel: this.logger.level,
+            debugKind: DebugLogAbstract.EVENT,
         });
     }
     /**
@@ -172,6 +178,9 @@ export class LLMProviderRouter {
      * Invoke router (sync mode)
      */
     async invoke(request) {
+        return runWithLogContext({ correlationId: request.requestId }, () => this.invokeWithLogContext(request));
+    }
+    async invokeWithLogContext(request) {
         const startTime = Date.now();
         // Auto-register providers if needed
         await this.ensureProvidersRegistered();
@@ -190,6 +199,7 @@ export class LLMProviderRouter {
         // Log request
         this.logger.logAIRequest(request.provider || 'unknown', processedRequest, {
             requestId: processedRequest.requestId,
+            correlationId: request.requestId,
         });
         // Execute
         const invokeStartTime = Date.now();
@@ -216,6 +226,8 @@ export class LLMProviderRouter {
                 provider: request.provider,
                 error: err.message,
                 stack: err.stack,
+                requestId: processedRequest.requestId,
+                debugKind: DebugLogAbstract.ANOMALY,
             });
             throw err;
         }
@@ -272,6 +284,7 @@ export class LLMProviderRouter {
         // Log request
         this.logger.logAIRequest(request.provider || 'unknown', processedRequest, {
             requestId: processedRequest.requestId,
+            correlationId: request.requestId,
         });
         // Stream
         for await (const event of this.router.runStream(processedRequest)) {
@@ -407,6 +420,9 @@ export class LLMProviderRouter {
             if (providerModule) {
                 this.providerRegistry.register(providerModule);
                 this.addRequestInterceptor(async (req, originalProvider) => {
+                    if (!shouldPreferOpenRouter(this.config)) {
+                        return req;
+                    }
                     const newRequest = { ...req };
                     if (!newRequest.request)
                         newRequest.request = {};
@@ -445,7 +461,9 @@ export class LLMProviderRouter {
                     newRequest.provider = 'openrouter';
                     return newRequest;
                 });
-                this.logger.info('Auto-registered OpenRouter provider and enabled OpenRouter mode');
+                this.logger.info('Auto-registered OpenRouter provider', {
+                    preferOpenRouter: shouldPreferOpenRouter(this.config),
+                });
             }
         }
         catch (e) {
@@ -494,10 +512,9 @@ export class LLMProviderRouter {
             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).
-        if (this.providerRegistry.has('openrouter')) {
-            this.logger.info('OpenRouter mode active - skipping individual providers to avoid state conflicts');
+        // When OpenRouter is preferred (default), skip direct providers to avoid singleton conflicts.
+        if (this.providerRegistry.has('openrouter') && shouldPreferOpenRouter(this.config)) {
+            this.logger.info('OpenRouter preferred - skipping individual provider auto-registration');
             return;
         }
         // 2. OpenAI

package/dist/utils/openrouterEnv.d.ts

@@ -6,3 +6,21 @@ 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";
+export interface ResolveUseOpenRouterOptions {
+    /** Programmatic override from RouterConfig.useOpenRouter — wins over environment. */
+    userValue?: boolean;
+    /** For tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Whether to prefer OpenRouter for vendor calls when an OpenRouter key is available.
+ *
+ * Default: `true` (route through OpenRouter even when direct provider keys exist).
+ * Set `USE_OPENROUTER=false` to use direct providers when keys exist; OpenRouter remains
+ * available as fallback for providers without a direct key.
+ */
+export declare function resolveUseOpenRouter(options?: ResolveUseOpenRouterOptions): boolean;
+/** True when OpenRouter should be the primary transport (not merely fallback). */
+export declare function shouldPreferOpenRouter(config: {
+    useOpenRouter?: boolean;
+} | undefined, env?: NodeJS.ProcessEnv): boolean;

package/dist/utils/openrouterEnv.js

@@ -16,3 +16,31 @@ export function hasOpenRouterApiKey() {
 }
 /** ERC placeholder resolution: prefer canonical name, fall back to legacy. */
 export const OPENROUTER_API_KEY_ERC = 'ENV.OPENROUTER_API_KEY||ENV.OPEN_ROUTER_KEY';
+/**
+ * Whether to prefer OpenRouter for vendor calls when an OpenRouter key is available.
+ *
+ * Default: `true` (route through OpenRouter even when direct provider keys exist).
+ * Set `USE_OPENROUTER=false` to use direct providers when keys exist; OpenRouter remains
+ * available as fallback for providers without a direct key.
+ */
+export function resolveUseOpenRouter(options = {}) {
+    const { userValue, env = process.env } = options;
+    if (userValue === false)
+        return false;
+    if (userValue === true)
+        return true;
+    const raw = env.USE_OPENROUTER;
+    if (raw === undefined || raw === '')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (raw === 'true')
+        return true;
+    return true;
+}
+/** True when OpenRouter should be the primary transport (not merely fallback). */
+export function shouldPreferOpenRouter(config, env) {
+    if (!hasOpenRouterApiKey())
+        return false;
+    return resolveUseOpenRouter({ userValue: config?.useOpenRouter, env });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.8.6",
+  "version": "4.8.8",
   "description": "Unified router for all LLM provider implementations",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "@x12i/ai-provider-grok": "^3.2.0",
     "@x12i/ai-provider-interface": "^3.2.1",
     "@x12i/ai-provider-openai": "^3.2.1",
-    "@x12i/logxer": "^4.4.0",
+    "@x12i/logxer": "^4.5.0",
     "ai-io-normalizer": "^6.0.3"
   },
   "devDependencies": {