@x12i/ai-providers-router 4.8.12 → 4.9.1

package/README.md

@@ -321,7 +321,15 @@ Full reference: [Environment variables](./docs/environment-variables.md) · [Con
 
 The router uses [`@x12i/logxer`](https://www.npmjs.com/package/@x12i/logxer) for structured, package-scoped logging.
 
-**Package prefix:** `AI_PROVIDER_ROUTER`
+**Logxer identity** (npm package `@x12i/ai-providers-router`):
+
+| Identifier | Value | Used for |
+|------------|-------|----------|
+| `package` (log field) | `AIProviderRouter` | Structured logs, shadow capture, Mongo `package` column |
+| `envPrefix` | `AI_PROVIDER_ROUTER` | Env vars, `LOGXER_PACKAGE_LEVELS`, stack `packageLevels` keys |
+| `debugNamespace` | `ai-providers-router` | `DEBUG=ai-providers-router` |
+
+Exported constants: `ROUTER_LOG_ENV_PREFIX`, `ROUTER_LOGXER_PACKAGE`.
 
 ```bash
 # Canonical (preferred)
@@ -330,10 +338,19 @@ AI_PROVIDER_ROUTER_LOGS_LEVEL=info
 # Legacy (still supported when _LOGS_LEVEL is unset)
 AI_PROVIDER_ROUTER_LOG_LEVEL=info
 
-# Log full AI request/response payloads (router-specific, separate from log level)
+# Log full AI request/response payloads (requires _LOGS_LEVEL=verbose to print)
 AI_PROVIDER_ROUTER_VERBOSE=true
 ```
 
+**Tiered AI interaction logging**
+
+| Level | Env threshold | Router `verbose` flag | What you get |
+|-------|---------------|----------------------|--------------|
+| `info` | `_LOGS_LEVEL=info` | — | One **AI call completed** line per `invoke` / `stream` / `batch` (provider, model, duration, tokens, requestId) |
+| `debug` | `_LOGS_LEVEL=debug` | — | Routing resolution, fallback attempts, retries, batch poll progress |
+| `verbose` | `_LOGS_LEVEL=verbose` | `VERBOSE=true` | Full sanitized request/response via **AI interaction complete** |
+| `error` | always (if enabled) | — | Failed invoke/stream/batch with stack |
+
 **Log levels:** `error` · `warn` · `info` · `debug` · `verbose` · `off`
 
 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`.
@@ -369,10 +386,22 @@ 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 }) });
+import { createRouter, createLogger, ROUTER_LOGXER_PACKAGE } from '@x12i/ai-providers-router';
+
+// info summaries always; payloads when verbose + log level verbose
+const router = await createRouter({ logLevel: 'info', verbose: true });
+
+// inject custom logger
+const router2 = await createRouter({
+  logger: createLogger({ level: 'debug', verbose: false }),
+});
+
+// stack identity for host config
+console.log(ROUTER_LOGXER_PACKAGE.envPrefix); // AI_PROVIDER_ROUTER
 ```
 
+See also: [Logxer integration checklist](./docs/logxer-package-integration-checklist.md) (generic, shareable).
+
 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.
 
 ---

package/dist/factory.js

@@ -1,7 +1,7 @@
 import { applyPackageLogLevelsFromEnv } from '@x12i/logxer';
 import { LLMProviderRouter } from './router/RouterWrapper.js';
 import dns from 'node:dns';
-import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, resolveUseOpenRouter } from './utils/openrouterEnv.js';
+import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, resolvePreferOpenRouterPolicy } 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
@@ -121,7 +121,7 @@ export async function createRouter(config) {
                 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',
+                preferOpenRouter: 'ENV.PREFER_OPENROUTER||ENV.USE_OPENROUTER',
             },
         },
     };
@@ -134,19 +134,19 @@ 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 useOpenRouter = resolveUseOpenRouter({
-        userValue: config?.useOpenRouter,
+    const preferOpenRouter = resolvePreferOpenRouterPolicy({
+        userValue: config?.preferOpenRouter ?? config?.useOpenRouter,
     });
     const finalConfig = Object.keys(config || {}).length > 0 ? {
         ...config,
-        useOpenRouter: config?.useOpenRouter ?? useOpenRouter,
+        preferOpenRouter: config?.preferOpenRouter ?? config?.useOpenRouter ?? preferOpenRouter,
     } : {
         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,
+        preferOpenRouter,
     };
     const router = new LLMProviderRouter(finalConfig);
     // Configure providers from ERC auto-detected config OR explicit config

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

package/dist/index.js

@@ -39,7 +39,7 @@ export { createRouter, createRouterFromConfig } from './factory.js';
 // Error classes
 export { ProviderNotFoundError, FallbackExhaustedError, ProviderNotInstalledError, ProviderTimeoutError } from './errors.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';
+export { Logger, getLogger, createLogger, createRouterLogxer, ROUTER_LOG_ENV_PREFIX, ROUTER_LOGXER_PACKAGE, extractAIModelHint, 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

@@ -7,6 +7,18 @@ 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";
+/**
+ * Logxer package identity for `@x12i/ai-providers-router`.
+ *
+ * - `packageName` → `package` field in structured logs / shadow / Mongo
+ * - `envPrefix` → `AI_PROVIDER_ROUTER_LOGS_LEVEL`, `LOGXER_PACKAGE_LEVELS`, stack `packageLevels`
+ * - `debugNamespace` → `DEBUG=ai-providers-router`
+ */
+export declare const ROUTER_LOGXER_PACKAGE: {
+    readonly packageName: "AIProviderRouter";
+    readonly envPrefix: "AI_PROVIDER_ROUTER";
+    readonly debugNamespace: "ai-providers-router";
+};
 export interface LoggerConfig {
     verbose?: boolean;
     /** Explicit instance level (wins over `logging` stack and registry). */
@@ -24,6 +36,24 @@ export declare function createRouterLogxer(options?: {
     logging?: StackLoggingOptions;
     level?: LogLevel;
 }): Logxer;
+export interface AICallCompletedMeta extends LogMeta {
+    mode: 'sync' | 'stream' | 'batch';
+    provider: string;
+    model?: string;
+    durationMs?: number;
+    requestId?: string;
+    correlationId?: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+    };
+    batchItemCount?: number;
+    attemptCount?: number;
+    fallbackUsed?: boolean;
+}
+/** Extract model id from a router request or response shape for logging summaries. */
+export declare function extractAIModelHint(source: unknown): string | undefined;
 /**
  * Logger class that wraps logxer with proper log levels
  */
@@ -53,6 +83,12 @@ export declare class Logger {
     logVerbose(message: string, data?: LogMeta): void;
     logAIRequest(provider: string, request: unknown, metadata?: LogMeta): void;
     logAIResponse(provider: string, response: unknown, metadata?: LogMeta): void;
+    /** Info-level summary for every completed AI call (no full payloads). */
+    logAICallCompleted(meta: AICallCompletedMeta): void;
+    logAIRoutingResolved(data: LogMeta): void;
+    logAIFallbackAttempt(data: LogMeta): void;
+    logAIRetryAttempt(data: LogMeta): void;
+    logAIBatchProgress(data: 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).

package/dist/logger.js

@@ -6,11 +6,19 @@ import { applyPackageLogLevelsFromEnv, createLogxer, DebugLogAbstract, runWithLo
 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',
+/**
+ * Logxer package identity for `@x12i/ai-providers-router`.
+ *
+ * - `packageName` → `package` field in structured logs / shadow / Mongo
+ * - `envPrefix` → `AI_PROVIDER_ROUTER_LOGS_LEVEL`, `LOGXER_PACKAGE_LEVELS`, stack `packageLevels`
+ * - `debugNamespace` → `DEBUG=ai-providers-router`
+ */
+export const ROUTER_LOGXER_PACKAGE = {
+    packageName: 'AIProviderRouter',
     envPrefix: ROUTER_LOG_ENV_PREFIX,
     debugNamespace: 'ai-providers-router',
 };
+const LOGXER_PACKAGE = ROUTER_LOGXER_PACKAGE;
 const DEFAULT_LOGXER_OPTIONS = {
     sanitization: {
         enabled: true,
@@ -51,6 +59,43 @@ function createGateway(options = {}) {
 export function createRouterLogxer(options) {
     return createGateway(options);
 }
+/** Extract model id from a router request or response shape for logging summaries. */
+export function extractAIModelHint(source) {
+    if (!source || typeof source !== 'object')
+        return undefined;
+    const obj = source;
+    const readModel = (value) => {
+        if (typeof value === 'string' && value.trim() !== '')
+            return value.trim();
+        if (value && typeof value === 'object') {
+            const obj = value;
+            for (const key of ['id', 'model', 'name']) {
+                const nested = obj[key];
+                if (typeof nested === 'string' && nested.trim() !== '')
+                    return nested.trim();
+            }
+        }
+        return undefined;
+    };
+    const request = obj.request;
+    if (request && typeof request === 'object') {
+        const req = request;
+        const fromConfig = req.config && typeof req.config === 'object'
+            ? readModel(req.config.model)
+            : undefined;
+        if (fromConfig)
+            return fromConfig;
+        const fromRequest = readModel(req.model);
+        if (fromRequest)
+            return fromRequest;
+    }
+    const metadata = obj.metadata;
+    if (metadata && typeof metadata === 'object') {
+        const meta = metadata;
+        return readModel(meta.modelUsed) ?? readModel(meta.model);
+    }
+    return readModel(obj.model);
+}
 /**
  * Logger class that wraps logxer with proper log levels
  */
@@ -131,35 +176,63 @@ export class Logger {
     logAIRequest(provider, request, metadata) {
         if (!this.verbose)
             return;
-        this.logVerbose('AI Request Sent', {
+        this.gateway.verbose('AI request sent', {
             provider,
             request,
-            metadata: metadata ?? {},
-            timestamp: new Date().toISOString(),
+            ...(metadata ?? {}),
             debugKind: DebugLogAbstract.STATE,
         });
     }
     logAIResponse(provider, response, metadata) {
         if (!this.verbose)
             return;
-        this.logVerbose('AI Response Received', {
+        this.gateway.verbose('AI response received', {
             provider,
             response,
-            metadata: metadata ?? {},
-            timestamp: new Date().toISOString(),
+            ...(metadata ?? {}),
             debugKind: DebugLogAbstract.STATE,
         });
     }
+    /** Info-level summary for every completed AI call (no full payloads). */
+    logAICallCompleted(meta) {
+        this.info('AI call completed', {
+            ...meta,
+            debugKind: DebugLogAbstract.EVENT,
+        });
+    }
+    logAIRoutingResolved(data) {
+        this.debug('AI routing resolved', {
+            ...data,
+            debugKind: DebugLogAbstract.INTENT,
+        });
+    }
+    logAIFallbackAttempt(data) {
+        this.debug('AI fallback attempt', {
+            ...data,
+            debugKind: DebugLogAbstract.EVENT,
+        });
+    }
+    logAIRetryAttempt(data) {
+        this.debug('AI retry attempt', {
+            ...data,
+            debugKind: DebugLogAbstract.EVENT,
+        });
+    }
+    logAIBatchProgress(data) {
+        this.debug('AI batch progress', {
+            ...data,
+            debugKind: DebugLogAbstract.EVENT,
+        });
+    }
     logAIIteraction(provider, request, response, duration, metadata) {
         if (!this.verbose)
             return;
-        this.logVerbose('AI Interaction Complete', {
+        this.gateway.verbose('AI interaction complete', {
             provider,
             request,
             response,
-            duration: duration ? `${duration}ms` : undefined,
-            metadata: metadata ?? {},
-            timestamp: new Date().toISOString(),
+            durationMs: duration,
+            ...(metadata ?? {}),
             debugKind: DebugLogAbstract.EVENT,
         });
     }

package/dist/router/Router.d.ts

@@ -10,13 +10,14 @@ export declare class AIRouter {
     private adapters;
     private routerConfig;
     constructor(providers: ProviderRegistry, adapters: AdapterRegistry, routerConfig?: RouterConfig);
+    private get logger();
     /**
      * Resolve provider module name for a specific fallback candidate.
      */
     private resolveProviderNameForCandidate;
     /**
      * Resolve provider name from request.
-     * Prefers OpenRouter when USE_OPENROUTER is true (default); falls back to OpenRouter when
+     * Prefers OpenRouter when PREFER_OPENROUTER is true (default) and a key is present; 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

@@ -15,6 +15,9 @@ export class AIRouter {
         this.adapters = adapters;
         this.routerConfig = routerConfig;
     }
+    get logger() {
+        return this.routerConfig.logger;
+    }
     /**
      * Resolve provider module name for a specific fallback candidate.
      */
@@ -33,7 +36,7 @@ export class AIRouter {
     }
     /**
      * Resolve provider name from request.
-     * Prefers OpenRouter when USE_OPENROUTER is true (default); falls back to OpenRouter when
+     * Prefers OpenRouter when PREFER_OPENROUTER is true (default) and a key is present; falls back to OpenRouter when
      * the requested vendor has no direct provider registered but an OpenRouter key exists.
      */
     resolveProviderName(input) {
@@ -118,6 +121,17 @@ export class AIRouter {
             requestConfig: requestConfig && typeof requestConfig === 'object' ? requestConfig : undefined,
             routerFallbackChain: this.routerConfig.fallbackChain,
         });
+        this.logger?.logAIRoutingResolved({
+            requestId,
+            mode: 'sync',
+            requestedProvider: input.provider ?? (typeof requestConfig?.provider === 'string' ? requestConfig.provider : undefined),
+            resolvedProvider: primaryProviderName,
+            model: primaryModel,
+            preferOpenRouter: shouldPreferOpenRouter(this.routerConfig),
+            openRouterKeyPresent: hasOpenRouterApiKey(),
+            fallbackCandidateCount: fallbackCandidates.length,
+            fallbackCandidates: fallbackCandidates.map((c) => ({ provider: c.provider, model: c.model })),
+        });
         const maxRetries = Math.max(0, Math.min(10, Number(input.exec?.retries ?? 0) || 0));
         const attempts = [];
         const normalizeUsage = (usage) => {
@@ -161,6 +175,14 @@ export class AIRouter {
             const candidate = fallbackCandidates[fallbackIndex];
             const candidateInput = buildCandidateRequest(input, candidate);
             const providerName = this.resolveProviderNameForCandidate(candidateInput, candidate.provider);
+            this.logger?.logAIFallbackAttempt({
+                requestId,
+                mode: 'sync',
+                fallbackIndex,
+                candidateProvider: candidate.provider,
+                resolvedModule: providerName,
+                model: candidate.model,
+            });
             if (!this.providers.has(providerName)) {
                 const err = new Error(`Provider not registered: ${providerName}. Available: ${this.providers.list().join(', ')}`);
                 lastError = err;
@@ -207,6 +229,16 @@ export class AIRouter {
                 candidateInput.request?.config?.model ??
                 candidateInput.request?.model;
             for (let retryIndex = 0; retryIndex <= maxRetries; retryIndex++) {
+                if (retryIndex > 0) {
+                    this.logger?.logAIRetryAttempt({
+                        requestId,
+                        mode: 'sync',
+                        provider: providerName,
+                        model: candidate.model,
+                        retryIndex,
+                        maxRetries,
+                    });
+                }
                 const startedAt = Date.now();
                 let execResult;
                 try {
@@ -338,6 +370,18 @@ export class AIRouter {
     async *runStream(input) {
         const requestId = input.requestId ?? newId();
         const providerName = this.resolveProviderName(input);
+        const requestConfig = input.request?.config;
+        const model = (typeof requestConfig?.model === 'string' ? requestConfig.model : undefined) ??
+            (typeof input.request?.model === 'string' ? input.request.model : undefined);
+        this.logger?.logAIRoutingResolved({
+            requestId,
+            mode: 'stream',
+            requestedProvider: input.provider ?? (typeof requestConfig?.provider === 'string' ? requestConfig.provider : undefined),
+            resolvedProvider: providerName,
+            model,
+            preferOpenRouter: shouldPreferOpenRouter(this.routerConfig),
+            openRouterKeyPresent: hasOpenRouterApiKey(),
+        });
         const provider = this.providers.get(providerName);
         const adapter = this.adapters.get(providerName);
         // Check capabilities
@@ -414,6 +458,12 @@ export class AIRouter {
     async runBatch(providerName, items, exec) {
         const provider = this.providers.get(providerName);
         const adapter = this.adapters.get(providerName);
+        this.logger?.logAIRoutingResolved({
+            mode: 'batch',
+            requestedProvider: providerName,
+            resolvedProvider: providerName,
+            batchItemCount: items.length,
+        });
         // Check capabilities
         if (!provider.capabilities.modes.batch) {
             throw new Error(`Provider '${providerName}' does not support batch mode`);
@@ -443,6 +493,12 @@ export class AIRouter {
         })));
         // Submit batch
         const handle = await provider.submitBatch(specs);
+        this.logger?.logAIBatchProgress({
+            provider: providerName,
+            batchItemCount: itemsWithIds.length,
+            phase: 'submitted',
+            batchId: handle.batchId,
+        });
         // Poll until complete
         while (true) {
             const status = await provider.getBatchStatus(handle);
@@ -452,6 +508,13 @@ export class AIRouter {
             if (status.state === 'failed' || status.state === 'canceled') {
                 throw new Error(`Batch ended with state: ${status.state}`);
             }
+            this.logger?.logAIBatchProgress({
+                provider: providerName,
+                batchItemCount: itemsWithIds.length,
+                phase: 'polling',
+                batchState: status.state,
+                batchId: handle.batchId,
+            });
             // Wait before polling again
             await new Promise((r) => setTimeout(r, 2000));
         }

package/dist/router/RouterTypes.d.ts

@@ -104,9 +104,11 @@ export interface RouterConfig {
     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;
+     * Maps to PREFER_OPENROUTER env. When false, direct providers are used when keys exist;
      * OpenRouter is still used as fallback for providers without a direct key.
      */
+    preferOpenRouter?: boolean;
+    /** @deprecated Use preferOpenRouter (maps to USE_OPENROUTER env as legacy fallback). */
     useOpenRouter?: boolean;
     /** OpenRouter provider config (e.g. from gateway); used when env OPEN_ROUTER_KEY is not visible */
     openrouter?: {

package/dist/router/RouterWrapper.js

@@ -4,7 +4,7 @@ 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, runWithLogContext, DebugLogAbstract } from '../logger.js';
+import { getLogger, runWithLogContext, DebugLogAbstract, extractAIModelHint } from '../logger.js';
 import { resolveOpenRouterApiKey, OPENROUTER_API_KEY_ERC, shouldPreferOpenRouter } from '../utils/openrouterEnv.js';
 import { resolveModelVendorSlug } from '../utils/openrouterModelVendor.js';
 /**
@@ -66,8 +66,11 @@ export class LLMProviderRouter {
         this.adapterRegistry.register(new OpenAIAdapter());
         this.adapterRegistry.register(new GrokAdapter());
         this.adapterRegistry.register(new OpenRouterAdapter());
-        // Create router
-        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry, this.config);
+        // Create router (inject logger for core routing/fallback debug logs)
+        this.router = new AIRouter(this.providerRegistry, this.adapterRegistry, {
+            ...this.config,
+            logger: this.logger,
+        });
         this.logger.info('Router initialized with ProviderModule architecture', {
             verbose: this.logger.verbose,
             logLevel: this.logger.level,
@@ -232,10 +235,21 @@ export class LLMProviderRouter {
             throw err;
         }
         const invokeDuration = Date.now() - invokeStartTime;
-        // Log response
-        this.logger.logAIResponse(result.provider, result, {
+        const attempts = result.metadata?.attempts;
+        this.logger.logAICallCompleted({
+            mode: 'sync',
+            provider: result.provider,
+            model: extractAIModelHint(result) ?? extractAIModelHint(processedRequest),
+            durationMs: invokeDuration,
+            requestId: result.requestId,
+            correlationId: request.requestId,
+            usage: result.usage,
+            attemptCount: attempts?.length,
+            fallbackUsed: attempts?.some((a) => (a.routing?.fallbackIndex ?? 0) > 0),
+        });
+        this.logger.logAIIteraction(result.provider, processedRequest, result, invokeDuration, {
             requestId: result.requestId,
-            duration: invokeDuration,
+            correlationId: request.requestId,
             usage: result.usage,
         });
         // Apply response interceptors
@@ -265,6 +279,7 @@ export class LLMProviderRouter {
      * Stream request
      */
     async *stream(request) {
+        const startTime = Date.now();
         // Auto-register providers if needed
         await this.ensureProvidersRegistered();
         // Apply request interceptors
@@ -281,34 +296,64 @@ export class LLMProviderRouter {
             processedRequest.exec.timeoutMs = this.config.timeoutMs ?? this.config.defaultTimeoutMs ?? 60000;
         }
         // idempotencyKey and signal are passed through as-is if provided
-        // Log request
         this.logger.logAIRequest(request.provider || 'unknown', processedRequest, {
             requestId: processedRequest.requestId,
             correlationId: request.requestId,
+            mode: 'stream',
         });
-        // Stream
-        for await (const event of this.router.runStream(processedRequest)) {
-            // Apply response interceptors to completed events
-            if (event.type === 'completed') {
-                let processedResponse = event.response;
-                for (const interceptor of this.responseInterceptors) {
-                    processedResponse = await interceptor(processedResponse, event.response.provider);
+        try {
+            for await (const event of this.router.runStream(processedRequest)) {
+                if (event.type === 'completed') {
+                    let processedResponse = event.response;
+                    for (const interceptor of this.responseInterceptors) {
+                        processedResponse = await interceptor(processedResponse, event.response.provider);
+                    }
+                    const durationMs = Date.now() - startTime;
+                    this.logger.logAICallCompleted({
+                        mode: 'stream',
+                        provider: processedResponse.provider,
+                        model: extractAIModelHint(processedResponse) ?? extractAIModelHint(processedRequest),
+                        durationMs,
+                        requestId: event.requestId,
+                        correlationId: request.requestId,
+                        usage: processedResponse.usage,
+                    });
+                    this.logger.logAIIteraction(processedResponse.provider, processedRequest, processedResponse, durationMs, {
+                        requestId: event.requestId,
+                        correlationId: request.requestId,
+                        usage: processedResponse.usage,
+                        mode: 'stream',
+                    });
+                    yield {
+                        type: 'completed',
+                        requestId: event.requestId,
+                        response: processedResponse,
+                    };
+                }
+                else {
+                    yield event;
                 }
-                yield {
-                    type: 'completed',
-                    requestId: event.requestId,
-                    response: processedResponse,
-                };
-            }
-            else {
-                yield event;
             }
         }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('Router stream execution failed', {
+                provider: request.provider,
+                error: err.message,
+                stack: err.stack,
+                requestId: processedRequest.requestId,
+                correlationId: request.requestId,
+                mode: 'stream',
+                debugKind: DebugLogAbstract.ANOMALY,
+            });
+            throw err;
+        }
     }
     /**
      * Batch request
      */
     async createBatch(providerName, items, exec) {
+        const startTime = Date.now();
         // Auto-register providers if needed
         await this.ensureProvidersRegistered();
         // Ensure exec.timeoutMs is always set (router owns execution semantics)
@@ -319,7 +364,34 @@ export class LLMProviderRouter {
             idempotencyKey: exec?.idempotencyKey,
             signal: exec?.signal,
         };
-        return this.router.runBatch(providerName, items, execWithDefaults);
+        this.logger.logAIRequest(providerName, { provider: providerName, itemCount: items.length, items }, {
+            mode: 'batch',
+            batchItemCount: items.length,
+        });
+        try {
+            const result = await this.router.runBatch(providerName, items, execWithDefaults);
+            const durationMs = Date.now() - startTime;
+            this.logger.logAICallCompleted({
+                mode: 'batch',
+                provider: result.provider,
+                durationMs,
+                batchItemCount: result.items.length,
+            });
+            this.logger.logAIIteraction(result.provider, { provider: providerName, itemCount: items.length, items }, result, durationMs, { mode: 'batch', batchItemCount: result.items.length });
+            return result;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('Router batch execution failed', {
+                provider: providerName,
+                error: err.message,
+                stack: err.stack,
+                batchItemCount: items.length,
+                mode: 'batch',
+                debugKind: DebugLogAbstract.ANOMALY,
+            });
+            throw err;
+        }
     }
     /**
      * List registered providers

package/dist/utils/openrouterEnv.d.ts

@@ -6,21 +6,32 @@ 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. */
+export interface ResolvePreferOpenRouterOptions {
+    /** Programmatic override from RouterConfig.preferOpenRouter — wins over environment. */
     userValue?: boolean;
     /** For tests; defaults to `process.env`. */
     env?: NodeJS.ProcessEnv;
 }
+/** @deprecated Use ResolvePreferOpenRouterOptions */
+export type ResolveUseOpenRouterOptions = ResolvePreferOpenRouterOptions;
+export interface PreferOpenRouterConfig {
+    preferOpenRouter?: boolean;
+    /** @deprecated Use preferOpenRouter */
+    useOpenRouter?: boolean;
+}
 /**
- * Whether to prefer OpenRouter for vendor calls when an OpenRouter key is available.
+ * Read operator preference from env. Prefers PREFER_OPENROUTER; USE_OPENROUTER is legacy fallback.
+ * Default when both are unset: `true`.
+ */
+export declare function readPreferOpenRouterFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether the operator prefers OpenRouter for vendor calls (before key availability is applied).
  *
- * 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.
+ * Default: `true`. Set `PREFER_OPENROUTER=false` to force vendor-direct when keys exist;
+ * OpenRouter remains available as fallback for providers without a direct key.
  */
-export declare function resolveUseOpenRouter(options?: ResolveUseOpenRouterOptions): boolean;
+export declare function resolvePreferOpenRouterPolicy(options?: ResolvePreferOpenRouterOptions): boolean;
+/** @deprecated Use resolvePreferOpenRouterPolicy */
+export declare function resolveUseOpenRouter(options?: ResolvePreferOpenRouterOptions): boolean;
 /** True when OpenRouter should be the primary transport (not merely fallback). */
-export declare function shouldPreferOpenRouter(config: {
-    useOpenRouter?: boolean;
-} | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function shouldPreferOpenRouter(config: PreferOpenRouterConfig | undefined, env?: NodeJS.ProcessEnv): boolean;

package/dist/utils/openrouterEnv.js

@@ -16,31 +16,56 @@ 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';
+function parsePreferOpenRouterEnvValue(raw) {
+    if (raw === undefined || raw === '')
+        return undefined;
+    if (raw === 'false')
+        return false;
+    if (raw === 'true')
+        return true;
+    return true;
+}
 /**
- * Whether to prefer OpenRouter for vendor calls when an OpenRouter key is available.
+ * Read operator preference from env. Prefers PREFER_OPENROUTER; USE_OPENROUTER is legacy fallback.
+ * Default when both are unset: `true`.
+ */
+export function readPreferOpenRouterFromEnv(env = process.env) {
+    const prefer = parsePreferOpenRouterEnvValue(env.PREFER_OPENROUTER);
+    if (prefer !== undefined)
+        return prefer;
+    const legacy = parsePreferOpenRouterEnvValue(env.USE_OPENROUTER);
+    if (legacy !== undefined)
+        return legacy;
+    return true;
+}
+function resolveConfigPreferOpenRouter(config) {
+    if (config?.preferOpenRouter !== undefined)
+        return config.preferOpenRouter;
+    if (config?.useOpenRouter !== undefined)
+        return config.useOpenRouter;
+    return undefined;
+}
+/**
+ * Whether the operator prefers OpenRouter for vendor calls (before key availability is applied).
  *
- * 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.
+ * Default: `true`. Set `PREFER_OPENROUTER=false` to force vendor-direct when keys exist;
+ * OpenRouter remains available as fallback for providers without a direct key.
  */
-export function resolveUseOpenRouter(options = {}) {
+export function resolvePreferOpenRouterPolicy(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;
+    return readPreferOpenRouterFromEnv(env);
+}
+/** @deprecated Use resolvePreferOpenRouterPolicy */
+export function resolveUseOpenRouter(options = {}) {
+    return resolvePreferOpenRouterPolicy(options);
 }
 /** 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 });
+    return resolvePreferOpenRouterPolicy({ userValue: resolveConfigPreferOpenRouter(config), env });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-providers-router",
-  "version": "4.8.12",
+  "version": "4.9.1",
   "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.5.1",
+    "@x12i/logxer": "^4.6.0",
     "ai-io-normalizer": "^6.0.3"
   },
   "devDependencies": {