@x12i/ai-gateway 9.6.9 → 9.7.2

package/README.md

@@ -131,13 +131,27 @@ Defaults load from `defaults/model-config.json`, `instructions-blocks.json`, and
 | `MONGO_URI`, `MONGO_LOGS_DB` / `MONGO_DB` | Activix when no custom tracker |
 | `AI_GATEWAY_DEFAULT_MODEL` | Default model slug (`provider/model` or OpenRouter id) |
 | `mode` / `MODE` | Operational mode (`dev`, `debug`, `prod`) |
-| `AI_GATEWAY_LOGS_LEVEL` | Log level when using default logger (`AI_GATEWAY` prefix) |
+| `AI_GATEWAY_LOGS_LEVEL` | Log threshold for gateway diagnostics (`AI_GATEWAY` prefix): `error` … `verbose` |
+| `AI_GATEWAY_VERBOSE` | Full payload lines (still requires `AI_GATEWAY_LOGS_LEVEL=verbose`) |
+| `LOGXER_PACKAGE_LEVELS` | Bulk stack levels, e.g. `AI_GATEWAY:info,AI_PROVIDER_ROUTER:debug` |
 | `FLEX_MD_MIN_COMPLIANCE_LEVEL` | `L0`–`L3` output-format validation (default `L0`) |
 | `OPENROUTER_API_KEY` | OpenRouter key; always wired when set (required for profile/OpenRouter routes) |
 | `USE_OPENROUTER` | Optional; default **prefer** OpenRouter when key is set. `false` = use direct provider keys when present; OpenRouter still used as fallback when a provider has no key |
 | Other provider keys | `OPENAI_API_KEY`, `GROK_API_KEY`, etc. |
 
-Logging details: [Logger initialization](./docs/LOGGER_INITIALIZATION.md).
+Logging details: [Logger initialization](./docs/LOGGER_INITIALIZATION.md). Package identity and audit checklist: [LOGXER_INTEGRATION_CHECKLIST.md](./docs/LOGXER_INTEGRATION_CHECKLIST.md).
+
+### Logxer identity
+
+| Field | Value | Env / filter |
+|-------|-------|----------------|
+| `packageName` (log `package` column) | `AIGateway` | — |
+| `envPrefix` | `AI_GATEWAY` | `AI_GATEWAY_LOGS_LEVEL`, `LOGXER_PACKAGE_LEVELS` |
+| `debugNamespace` | `ai-gateway` | `DEBUG=ai-gateway` |
+
+Console lines show **`app:`** (host app from cwd `package.json`) separately from **`package:`** (`AIGateway` for gateway code, host package for host code).
+
+Exports: `GATEWAY_LOGXER_PACKAGE`, `GATEWAY_LOG_ENV_PREFIX`, `createGatewayLogger`, `resolveGatewayVerboseEnabled`.
 
 ---
 
@@ -251,11 +265,14 @@ Live tests use `LIVE_TEST_PROVIDER` / `LIVE_TEST_MODEL` (default `openrouter` +
 import { validateAIRequest, diagnoseRequest, formatDiagnostic } from '@x12i/ai-gateway';
 ```
 
-Enable request logging:
+Enable gateway/router diagnostics:
 
 ```bash
-export AI_GATEWAY_DEBUG=true
-export AI_GATEWAY_DEBUG_REQUEST=true
+export AI_GATEWAY_LOGS_LEVEL=debug
+export AI_PROVIDER_ROUTER_LOGS_LEVEL=debug
+# Optional full I/O payloads (requires _LOGS_LEVEL=verbose on the relevant package):
+export AI_GATEWAY_VERBOSE=true
+export AI_PROVIDER_ROUTER_VERBOSE=true
 export FLEX_MD_MIN_COMPLIANCE_LEVEL=L0
 ```
 

package/dist/gateway-config.js

@@ -161,11 +161,11 @@ export function initializeGatewayComponents(config) {
     // Initialize logger FIRST (before other components that might need it)
     const logger = createGatewayLogger({
         enableLogging: config.enableLogging ?? true,
-        packageName: config.packageName,
         customLogger: config.logger,
         logging: config.logging,
         packageLogLevels: config.packageLogLevels,
-        logLevel: config.logLevel
+        logLevel: config.logLevel,
+        verbose: config.verbose
     });
     const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig(logger);
     logger.verbose('Gateway initializing', {
@@ -204,7 +204,7 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     // OpenRouter: always pass apiKey when set (fallback for providers without direct keys).
-    // USE_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
+    // PREFER_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
     const openRouterKey = resolveOpenRouterApiKey(config);
     const preferOpenRouter = resolvePreferOpenRouter(config);
     if (openRouterKey) {

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

@@ -5,6 +5,15 @@
 import { type PackageLogLevelsConfig } from '@x12i/logxer';
 /** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
 export declare const GATEWAY_LOG_ENV_PREFIX = "AI_GATEWAY";
+/**
+ * Stable logxer package identity for `@x12i/ai-gateway`.
+ * @see docs/LOGXER_INTEGRATION_CHECKLIST.md
+ */
+export declare const GATEWAY_LOGXER_PACKAGE: {
+    readonly packageName: "AIGateway";
+    readonly envPrefix: "AI_GATEWAY";
+    readonly debugNamespace: "ai-gateway";
+};
 /** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
 export declare const GATEWAY_STACK_LOG_PREFIXES: {
     readonly gateway: "AI_GATEWAY";

package/dist/gateway-log-levels.js

@@ -6,6 +6,15 @@ import { applyPackageLogLevelsFromEnv, mergePackageLogLevelsConfig } from '@x12i
 import { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
 /** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
 export const GATEWAY_LOG_ENV_PREFIX = 'AI_GATEWAY';
+/**
+ * Stable logxer package identity for `@x12i/ai-gateway`.
+ * @see docs/LOGXER_INTEGRATION_CHECKLIST.md
+ */
+export const GATEWAY_LOGXER_PACKAGE = {
+    packageName: 'AIGateway',
+    envPrefix: GATEWAY_LOG_ENV_PREFIX,
+    debugNamespace: 'ai-gateway'
+};
 /** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
 export const GATEWAY_STACK_LOG_PREFIXES = {
     gateway: GATEWAY_LOG_ENV_PREFIX,

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

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

package/dist/index.d.ts

@@ -35,8 +35,9 @@ export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manage
 export { OptimixerManager } from './optimixer-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityIdentity, withGatewayLogContext, gatewayLogDebug } from './gateway-log-meta.js';
-export { createGatewayLogger } from './logger-factory.js';
-export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
+export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
+export type { GatewayLoggerConfig } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';

package/dist/index.js

@@ -30,8 +30,8 @@ export { normalizeToActivixCostShape } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export { OptimixerManager } from './optimixer-manager.js';
 export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityIdentity, withGatewayLogContext, gatewayLogDebug } from './gateway-log-meta.js';
-export { createGatewayLogger } from './logger-factory.js';
-export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
+export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';

package/dist/logger-factory.d.ts

@@ -4,24 +4,29 @@
  * Creates and configures logxer instances for the gateway
  */
 import { type LogLevel, type Logxer, type PackageLogLevelsConfig, type StackLoggingOptions } from '@x12i/logxer';
-import { GATEWAY_LOG_ENV_PREFIX } from './gateway-log-levels.js';
-export { GATEWAY_LOG_ENV_PREFIX };
+import { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE } from './gateway-log-levels.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE };
 /** True for the internal no-op logger when `enableLogging` is false. */
 export declare function isNoOpGatewayLogger(logger: Logxer): boolean;
-/**
- * Creates a logger instance based on configuration
- *
- * @param config - Logger configuration
- * @returns Configured logger or no-op logger if logging is disabled
- */
-export declare function createGatewayLogger(config: {
+/** Payload verbose flag (`AI_GATEWAY_VERBOSE`) — separate from `{PREFIX}_LOGS_LEVEL` threshold. */
+export declare function resolveGatewayVerboseEnabled(config?: {
+    verbose?: boolean;
+}): boolean;
+export interface GatewayLoggerConfig {
     enableLogging: boolean;
-    packageName?: string;
+    /** Host Logxer — transports inherited; emit surface stays {@link GATEWAY_LOGXER_PACKAGE}. */
     customLogger?: Logxer;
-    /** Parent/host pass-through (logxer ≥ 4.5). Forwarded as `createLogxer(..., { stack })`. */
+    /** Host pass-through (logxer ≥ 4.5). Forwarded as `createLogxer(..., { stack })`. */
     logging?: StackLoggingOptions;
     /** Merged into the process registry after `applyPackageLogLevelsFromEnv()`. */
     packageLogLevels?: PackageLogLevelsConfig;
     /** Explicit level for this gateway logger instance (wins over stack/registry/env). */
     logLevel?: LogLevel;
-}): Logxer;
+    /** Full payload logging (`AI_GATEWAY_VERBOSE`); still requires log threshold `verbose`. */
+    verbose?: boolean;
+}
+/**
+ * Creates a logger instance based on configuration.
+ * Prefer this over ad-hoc `createLogxer` in consumers.
+ */
+export declare function createGatewayLogger(config: GatewayLoggerConfig): Logxer;

package/dist/logger-factory.js

@@ -5,42 +5,100 @@
  */
 import { createLogxer, getStationRuntimeIdentity, mergeRuntimeIdentity } from '@x12i/logxer';
 import { resolveLogDiagnosticsCatalogPath } from './gateway-log-diagnostics.js';
-import { GATEWAY_LOG_ENV_PREFIX, initializeGatewayPackageLogLevels } from './gateway-log-levels.js';
-export { GATEWAY_LOG_ENV_PREFIX };
+import { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, initializeGatewayPackageLogLevels } from './gateway-log-levels.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE };
 const NOOP_GATEWAY_LOGGER = Symbol('noop-gateway-logger');
+const DEFAULT_GATEWAY_LOGXER_OPTIONS = {
+    sanitization: {
+        enabled: true,
+        detectAPIKeys: true,
+        detectPasswords: true,
+        detectJWTs: true,
+        detectEmails: true
+    }
+};
 /** True for the internal no-op logger when `enableLogging` is false. */
 export function isNoOpGatewayLogger(logger) {
     return logger[NOOP_GATEWAY_LOGGER] === true;
 }
-function resolveGatewayRuntimeIdentity(packageName) {
+/** Payload verbose flag (`AI_GATEWAY_VERBOSE`) — separate from `{PREFIX}_LOGS_LEVEL` threshold. */
+export function resolveGatewayVerboseEnabled(config) {
+    if (config?.verbose !== undefined) {
+        return config.verbose;
+    }
+    const env = process.env.AI_GATEWAY_VERBOSE ?? process.env[`${GATEWAY_LOG_ENV_PREFIX}_VERBOSE`];
+    if (env === undefined) {
+        return false;
+    }
+    return env === 'true' || env === '1';
+}
+function resolveGatewayRuntimeIdentity() {
     return mergeRuntimeIdentity(getStationRuntimeIdentity(), {
-        service: process.env.AI_GATEWAY_LOG_SERVICE ?? packageName ?? GATEWAY_LOG_ENV_PREFIX,
+        service: process.env.AI_GATEWAY_LOG_SERVICE ?? 'ai-gateway',
         version: process.env.npm_package_version
     });
 }
+/** Share host transport settings; gateway keeps its own `package` label (`AIGateway`). */
+function inheritLoggingConfigFromHost(hostLogger) {
+    if (!hostLogger || typeof hostLogger.getConfig !== 'function') {
+        return {};
+    }
+    const hostConfig = hostLogger.getConfig();
+    if (!hostConfig || typeof hostConfig !== 'object') {
+        return {};
+    }
+    const inherited = {};
+    const pick = (key) => {
+        const value = hostConfig[key];
+        if (value !== undefined) {
+            inherited[key] = value;
+        }
+    };
+    pick('logToConsole');
+    pick('logToFile');
+    pick('logFilePath');
+    pick('logFormat');
+    pick('showFullTimestamp');
+    pick('enableUnifiedLogger');
+    pick('unifiedLogger');
+    pick('consolePackagesShow');
+    pick('consolePackagesHide');
+    pick('transports');
+    pick('tracing');
+    pick('trails');
+    pick('shadow');
+    pick('queryStore');
+    pick('queryCache');
+    pick('causalLogging');
+    // Gateway always sanitizes; merge host toggles when present.
+    if (hostConfig.sanitization) {
+        inherited.sanitization = {
+            ...DEFAULT_GATEWAY_LOGXER_OPTIONS.sanitization,
+            ...hostConfig.sanitization
+        };
+    }
+    if (hostConfig.runtimeIdentity) {
+        inherited.runtimeIdentity = mergeRuntimeIdentity(hostConfig.runtimeIdentity, resolveGatewayRuntimeIdentity());
+    }
+    return inherited;
+}
 /**
- * Creates a logger instance based on configuration
- *
- * @param config - Logger configuration
- * @returns Configured logger or no-op logger if logging is disabled
+ * Creates a logger instance based on configuration.
+ * Prefer this over ad-hoc `createLogxer` in consumers.
  */
 export function createGatewayLogger(config) {
-    if (config.customLogger) {
-        return config.customLogger;
-    }
     if (!config.enableLogging) {
         return createNoOpLogger();
     }
     initializeGatewayPackageLogLevels({ packageLogLevels: config.packageLogLevels });
     const catalogPath = resolveLogDiagnosticsCatalogPath();
-    return createLogxer({
-        packageName: config.packageName || GATEWAY_LOG_ENV_PREFIX,
-        envPrefix: GATEWAY_LOG_ENV_PREFIX,
-        debugNamespace: 'ai-gateway'
-    }, {
-        runtimeIdentity: resolveGatewayRuntimeIdentity(config.packageName),
+    const hostLogging = inheritLoggingConfigFromHost(config.customLogger);
+    return createLogxer(GATEWAY_LOGXER_PACKAGE, {
+        ...DEFAULT_GATEWAY_LOGXER_OPTIONS,
+        runtimeIdentity: resolveGatewayRuntimeIdentity(),
         stack: config.logging,
         ...(config.logLevel !== undefined ? { logLevel: config.logLevel } : {}),
+        ...hostLogging,
         ...(catalogPath
             ? {
                 diagnostics: {

package/dist/openrouter-routing.d.ts

@@ -5,8 +5,13 @@
 import type { GatewayConfig } from './types.js';
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export declare function readPreferOpenRouterFromEnv(): boolean | undefined;
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;

package/dist/openrouter-routing.js

@@ -11,17 +11,38 @@ export function resolveOpenRouterApiKey(config = {}) {
     return env || undefined;
 }
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export function readPreferOpenRouterFromEnv() {
+    const prefer = process.env.PREFER_OPENROUTER?.trim();
+    if (prefer === 'false' || prefer === '0')
+        return false;
+    if (prefer === 'true' || prefer === '1')
+        return true;
+    const legacy = process.env.USE_OPENROUTER?.trim();
+    if (legacy === 'false' || legacy === '0')
+        return false;
+    if (legacy === 'true' || legacy === '1')
+        return true;
+    return undefined;
+}
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export function resolvePreferOpenRouter(config = {}) {
+    if (config.openRouter?.prefer === true)
+        return true;
+    if (config.openRouter?.prefer === false)
+        return false;
     if (config.openRouter?.enabled === true)
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    const env = process.env.USE_OPENROUTER;
-    if (env === 'false' || env === '0')
-        return false;
-    return !!resolveOpenRouterApiKey(config);
+    const fromEnv = readPreferOpenRouterFromEnv();
+    if (fromEnv !== undefined)
+        return fromEnv;
+    return true;
 }

package/dist/types.d.ts

@@ -357,18 +357,25 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
      */
     packageLogLevels?: PackageLogLevelsConfig;
     /**
-     * Custom logger instance (optional)
+     * Host Logxer for shared transports and correlation context.
+     * The gateway always creates its own logger with log envelope `package: AIGateway`;
+     * the host logger is not used as the emit surface (so ai-skills logs stay ai-skills, gateway logs stay AIGateway).
      */
     logger?: Logxer;
     /**
-     * Custom activity tracker instance (optional)
+     * @deprecated Ignored — gateway logs always use {@link GATEWAY_LOGXER_PACKAGE} (`package: AIGateway`).
+     * Use `logging` / `packageLogLevels` for stack verbosity; pass `logger` to share transports.
      */
-    activityTracker?: Activix;
+    packageName?: string;
     /**
-     * Package name for logging
-     * @default 'AI_GATEWAY'
+     * Full payload logging for gateway-owned verbose lines (`AI_GATEWAY_VERBOSE=true`).
+     * Separate from log threshold (`AI_GATEWAY_LOGS_LEVEL=verbose`). Router I/O payloads use the same flag via `RouterConfig.verbose`.
      */
-    packageName?: string;
+    verbose?: boolean;
+    /**
+     * Custom activity tracker instance (optional)
+     */
+    activityTracker?: Activix;
     /**
      * Default engine (e.g., 'openai', 'anthropic')
      * Used only for provider routing when request doesn't specify provider
@@ -383,8 +390,8 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     };
     /**
      * OpenRouter preference (not a hard off-switch when {@link openrouter}.apiKey or OPENROUTER_API_KEY is set).
-     * - `enabled: true` or omitted with OPENROUTER_API_KEY: prefer OpenRouter even when direct provider keys exist.
-     * - `enabled: false` or USE_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
+     * - `prefer: true` / `enabled: true` or omitted env (default true): prefer OpenRouter when OPENROUTER_API_KEY is present.
+     * - `prefer: false` / `enabled: false` or PREFER_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
      */
     openRouter?: {
         enabled?: boolean;

package/dist-cjs/gateway-config.cjs

@@ -161,11 +161,11 @@ export function initializeGatewayComponents(config) {
     // Initialize logger FIRST (before other components that might need it)
     const logger = createGatewayLogger({
         enableLogging: config.enableLogging ?? true,
-        packageName: config.packageName,
         customLogger: config.logger,
         logging: config.logging,
         packageLogLevels: config.packageLogLevels,
-        logLevel: config.logLevel
+        logLevel: config.logLevel,
+        verbose: config.verbose
     });
     const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig(logger);
     logger.verbose('Gateway initializing', {
@@ -204,7 +204,7 @@ export function initializeGatewayComponents(config) {
     if (config.logging !== undefined)
         routerConfig.logging = config.logging;
     // OpenRouter: always pass apiKey when set (fallback for providers without direct keys).
-    // USE_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
+    // PREFER_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
     const openRouterKey = resolveOpenRouterApiKey(config);
     const preferOpenRouter = resolvePreferOpenRouter(config);
     if (openRouterKey) {

package/dist-cjs/gateway-log-levels.cjs

@@ -6,6 +6,15 @@ import { applyPackageLogLevelsFromEnv, mergePackageLogLevelsConfig } from '@x12i
 import { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
 /** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
 export const GATEWAY_LOG_ENV_PREFIX = 'AI_GATEWAY';
+/**
+ * Stable logxer package identity for `@x12i/ai-gateway`.
+ * @see docs/LOGXER_INTEGRATION_CHECKLIST.md
+ */
+export const GATEWAY_LOGXER_PACKAGE = {
+    packageName: 'AIGateway',
+    envPrefix: GATEWAY_LOG_ENV_PREFIX,
+    debugNamespace: 'ai-gateway'
+};
 /** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
 export const GATEWAY_STACK_LOG_PREFIXES = {
     gateway: GATEWAY_LOG_ENV_PREFIX,

package/dist-cjs/gateway-log-levels.d.ts

@@ -5,6 +5,15 @@
 import { type PackageLogLevelsConfig } from '@x12i/logxer';
 /** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
 export declare const GATEWAY_LOG_ENV_PREFIX = "AI_GATEWAY";
+/**
+ * Stable logxer package identity for `@x12i/ai-gateway`.
+ * @see docs/LOGXER_INTEGRATION_CHECKLIST.md
+ */
+export declare const GATEWAY_LOGXER_PACKAGE: {
+    readonly packageName: "AIGateway";
+    readonly envPrefix: "AI_GATEWAY";
+    readonly debugNamespace: "ai-gateway";
+};
 /** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
 export declare const GATEWAY_STACK_LOG_PREFIXES: {
     readonly gateway: "AI_GATEWAY";

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

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

package/dist-cjs/index.cjs

@@ -30,8 +30,8 @@ export { normalizeToActivixCostShape } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export { OptimixerManager } from './optimixer-manager.js';
 export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityIdentity, withGatewayLogContext, gatewayLogDebug } from './gateway-log-meta.js';
-export { createGatewayLogger } from './logger-factory.js';
-export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
+export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 // Re-export logging (@x12i/logxer)
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';

package/dist-cjs/index.d.ts

@@ -35,8 +35,9 @@ export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manage
 export { OptimixerManager } from './optimixer-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityIdentity, withGatewayLogContext, gatewayLogDebug } from './gateway-log-meta.js';
-export { createGatewayLogger } from './logger-factory.js';
-export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
+export { createGatewayLogger, resolveGatewayVerboseEnabled } from './logger-factory.js';
+export type { GatewayLoggerConfig } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
 export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
 export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';

package/dist-cjs/logger-factory.cjs

@@ -5,42 +5,100 @@
  */
 import { createLogxer, getStationRuntimeIdentity, mergeRuntimeIdentity } from '@x12i/logxer';
 import { resolveLogDiagnosticsCatalogPath } from './gateway-log-diagnostics.js';
-import { GATEWAY_LOG_ENV_PREFIX, initializeGatewayPackageLogLevels } from './gateway-log-levels.js';
-export { GATEWAY_LOG_ENV_PREFIX };
+import { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE, initializeGatewayPackageLogLevels } from './gateway-log-levels.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE };
 const NOOP_GATEWAY_LOGGER = Symbol('noop-gateway-logger');
+const DEFAULT_GATEWAY_LOGXER_OPTIONS = {
+    sanitization: {
+        enabled: true,
+        detectAPIKeys: true,
+        detectPasswords: true,
+        detectJWTs: true,
+        detectEmails: true
+    }
+};
 /** True for the internal no-op logger when `enableLogging` is false. */
 export function isNoOpGatewayLogger(logger) {
     return logger[NOOP_GATEWAY_LOGGER] === true;
 }
-function resolveGatewayRuntimeIdentity(packageName) {
+/** Payload verbose flag (`AI_GATEWAY_VERBOSE`) — separate from `{PREFIX}_LOGS_LEVEL` threshold. */
+export function resolveGatewayVerboseEnabled(config) {
+    if (config?.verbose !== undefined) {
+        return config.verbose;
+    }
+    const env = process.env.AI_GATEWAY_VERBOSE ?? process.env[`${GATEWAY_LOG_ENV_PREFIX}_VERBOSE`];
+    if (env === undefined) {
+        return false;
+    }
+    return env === 'true' || env === '1';
+}
+function resolveGatewayRuntimeIdentity() {
     return mergeRuntimeIdentity(getStationRuntimeIdentity(), {
-        service: process.env.AI_GATEWAY_LOG_SERVICE ?? packageName ?? GATEWAY_LOG_ENV_PREFIX,
+        service: process.env.AI_GATEWAY_LOG_SERVICE ?? 'ai-gateway',
         version: process.env.npm_package_version
     });
 }
+/** Share host transport settings; gateway keeps its own `package` label (`AIGateway`). */
+function inheritLoggingConfigFromHost(hostLogger) {
+    if (!hostLogger || typeof hostLogger.getConfig !== 'function') {
+        return {};
+    }
+    const hostConfig = hostLogger.getConfig();
+    if (!hostConfig || typeof hostConfig !== 'object') {
+        return {};
+    }
+    const inherited = {};
+    const pick = (key) => {
+        const value = hostConfig[key];
+        if (value !== undefined) {
+            inherited[key] = value;
+        }
+    };
+    pick('logToConsole');
+    pick('logToFile');
+    pick('logFilePath');
+    pick('logFormat');
+    pick('showFullTimestamp');
+    pick('enableUnifiedLogger');
+    pick('unifiedLogger');
+    pick('consolePackagesShow');
+    pick('consolePackagesHide');
+    pick('transports');
+    pick('tracing');
+    pick('trails');
+    pick('shadow');
+    pick('queryStore');
+    pick('queryCache');
+    pick('causalLogging');
+    // Gateway always sanitizes; merge host toggles when present.
+    if (hostConfig.sanitization) {
+        inherited.sanitization = {
+            ...DEFAULT_GATEWAY_LOGXER_OPTIONS.sanitization,
+            ...hostConfig.sanitization
+        };
+    }
+    if (hostConfig.runtimeIdentity) {
+        inherited.runtimeIdentity = mergeRuntimeIdentity(hostConfig.runtimeIdentity, resolveGatewayRuntimeIdentity());
+    }
+    return inherited;
+}
 /**
- * Creates a logger instance based on configuration
- *
- * @param config - Logger configuration
- * @returns Configured logger or no-op logger if logging is disabled
+ * Creates a logger instance based on configuration.
+ * Prefer this over ad-hoc `createLogxer` in consumers.
  */
 export function createGatewayLogger(config) {
-    if (config.customLogger) {
-        return config.customLogger;
-    }
     if (!config.enableLogging) {
         return createNoOpLogger();
     }
     initializeGatewayPackageLogLevels({ packageLogLevels: config.packageLogLevels });
     const catalogPath = resolveLogDiagnosticsCatalogPath();
-    return createLogxer({
-        packageName: config.packageName || GATEWAY_LOG_ENV_PREFIX,
-        envPrefix: GATEWAY_LOG_ENV_PREFIX,
-        debugNamespace: 'ai-gateway'
-    }, {
-        runtimeIdentity: resolveGatewayRuntimeIdentity(config.packageName),
+    const hostLogging = inheritLoggingConfigFromHost(config.customLogger);
+    return createLogxer(GATEWAY_LOGXER_PACKAGE, {
+        ...DEFAULT_GATEWAY_LOGXER_OPTIONS,
+        runtimeIdentity: resolveGatewayRuntimeIdentity(),
         stack: config.logging,
         ...(config.logLevel !== undefined ? { logLevel: config.logLevel } : {}),
+        ...hostLogging,
         ...(catalogPath
             ? {
                 diagnostics: {

package/dist-cjs/logger-factory.d.ts

@@ -4,24 +4,29 @@
  * Creates and configures logxer instances for the gateway
  */
 import { type LogLevel, type Logxer, type PackageLogLevelsConfig, type StackLoggingOptions } from '@x12i/logxer';
-import { GATEWAY_LOG_ENV_PREFIX } from './gateway-log-levels.js';
-export { GATEWAY_LOG_ENV_PREFIX };
+import { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE } from './gateway-log-levels.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_LOGXER_PACKAGE };
 /** True for the internal no-op logger when `enableLogging` is false. */
 export declare function isNoOpGatewayLogger(logger: Logxer): boolean;
-/**
- * Creates a logger instance based on configuration
- *
- * @param config - Logger configuration
- * @returns Configured logger or no-op logger if logging is disabled
- */
-export declare function createGatewayLogger(config: {
+/** Payload verbose flag (`AI_GATEWAY_VERBOSE`) — separate from `{PREFIX}_LOGS_LEVEL` threshold. */
+export declare function resolveGatewayVerboseEnabled(config?: {
+    verbose?: boolean;
+}): boolean;
+export interface GatewayLoggerConfig {
     enableLogging: boolean;
-    packageName?: string;
+    /** Host Logxer — transports inherited; emit surface stays {@link GATEWAY_LOGXER_PACKAGE}. */
     customLogger?: Logxer;
-    /** Parent/host pass-through (logxer ≥ 4.5). Forwarded as `createLogxer(..., { stack })`. */
+    /** Host pass-through (logxer ≥ 4.5). Forwarded as `createLogxer(..., { stack })`. */
     logging?: StackLoggingOptions;
     /** Merged into the process registry after `applyPackageLogLevelsFromEnv()`. */
     packageLogLevels?: PackageLogLevelsConfig;
     /** Explicit level for this gateway logger instance (wins over stack/registry/env). */
     logLevel?: LogLevel;
-}): Logxer;
+    /** Full payload logging (`AI_GATEWAY_VERBOSE`); still requires log threshold `verbose`. */
+    verbose?: boolean;
+}
+/**
+ * Creates a logger instance based on configuration.
+ * Prefer this over ad-hoc `createLogxer` in consumers.
+ */
+export declare function createGatewayLogger(config: GatewayLoggerConfig): Logxer;

package/dist-cjs/openrouter-routing.cjs

@@ -11,17 +11,38 @@ export function resolveOpenRouterApiKey(config = {}) {
     return env || undefined;
 }
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export function readPreferOpenRouterFromEnv() {
+    const prefer = process.env.PREFER_OPENROUTER?.trim();
+    if (prefer === 'false' || prefer === '0')
+        return false;
+    if (prefer === 'true' || prefer === '1')
+        return true;
+    const legacy = process.env.USE_OPENROUTER?.trim();
+    if (legacy === 'false' || legacy === '0')
+        return false;
+    if (legacy === 'true' || legacy === '1')
+        return true;
+    return undefined;
+}
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export function resolvePreferOpenRouter(config = {}) {
+    if (config.openRouter?.prefer === true)
+        return true;
+    if (config.openRouter?.prefer === false)
+        return false;
     if (config.openRouter?.enabled === true)
         return true;
     if (config.openRouter?.enabled === false)
         return false;
-    const env = process.env.USE_OPENROUTER;
-    if (env === 'false' || env === '0')
-        return false;
-    return !!resolveOpenRouterApiKey(config);
+    const fromEnv = readPreferOpenRouterFromEnv();
+    if (fromEnv !== undefined)
+        return fromEnv;
+    return true;
 }

package/dist-cjs/openrouter-routing.d.ts

@@ -5,8 +5,13 @@
 import type { GatewayConfig } from './types.js';
 export declare function resolveOpenRouterApiKey(config?: GatewayConfig): string | undefined;
 /**
- * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter even with direct keys).
- * Default: true when OPENROUTER_API_KEY is set. `USE_OPENROUTER=false` turns this off; ai-tools still falls back
- * when a vendor API key is missing.
+ * Read operator preference from env: `PREFER_OPENROUTER` (current), then deprecated `USE_OPENROUTER`.
+ * Returns undefined when neither is set.
+ */
+export declare function readPreferOpenRouterFromEnv(): boolean | undefined;
+/**
+ * When true, pass `routeViaOpenRouter: true` into ai-tools resolveModel (prefer OpenRouter when a key exists).
+ * Default: true. `PREFER_OPENROUTER=false` (or deprecated `USE_OPENROUTER=false`) forces vendor-direct when keys exist;
+ * ai-tools still falls back to OpenRouter when the requested provider has no direct key.
  */
 export declare function resolvePreferOpenRouter(config?: GatewayConfig): boolean;

package/dist-cjs/types.d.ts

@@ -357,18 +357,25 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
      */
     packageLogLevels?: PackageLogLevelsConfig;
     /**
-     * Custom logger instance (optional)
+     * Host Logxer for shared transports and correlation context.
+     * The gateway always creates its own logger with log envelope `package: AIGateway`;
+     * the host logger is not used as the emit surface (so ai-skills logs stay ai-skills, gateway logs stay AIGateway).
      */
     logger?: Logxer;
     /**
-     * Custom activity tracker instance (optional)
+     * @deprecated Ignored — gateway logs always use {@link GATEWAY_LOGXER_PACKAGE} (`package: AIGateway`).
+     * Use `logging` / `packageLogLevels` for stack verbosity; pass `logger` to share transports.
      */
-    activityTracker?: Activix;
+    packageName?: string;
     /**
-     * Package name for logging
-     * @default 'AI_GATEWAY'
+     * Full payload logging for gateway-owned verbose lines (`AI_GATEWAY_VERBOSE=true`).
+     * Separate from log threshold (`AI_GATEWAY_LOGS_LEVEL=verbose`). Router I/O payloads use the same flag via `RouterConfig.verbose`.
      */
-    packageName?: string;
+    verbose?: boolean;
+    /**
+     * Custom activity tracker instance (optional)
+     */
+    activityTracker?: Activix;
     /**
      * Default engine (e.g., 'openai', 'anthropic')
      * Used only for provider routing when request doesn't specify provider
@@ -383,8 +390,8 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     };
     /**
      * OpenRouter preference (not a hard off-switch when {@link openrouter}.apiKey or OPENROUTER_API_KEY is set).
-     * - `enabled: true` or omitted with OPENROUTER_API_KEY: prefer OpenRouter even when direct provider keys exist.
-     * - `enabled: false` or USE_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
+     * - `prefer: true` / `enabled: true` or omitted env (default true): prefer OpenRouter when OPENROUTER_API_KEY is present.
+     * - `prefer: false` / `enabled: false` or PREFER_OPENROUTER=false: use direct providers when their API keys exist; OpenRouter still used as fallback when a requested provider has no key.
      */
     openRouter?: {
         enabled?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.6.9",
+  "version": "9.7.2",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -42,10 +42,10 @@
   "license": "mit",
   "dependencies": {
     "@x12i/activix": "^8.3.1",
-    "@x12i/ai-providers-router": "^4.8.12",
-    "@x12i/ai-tools": "^2.1.2",
+    "@x12i/ai-providers-router": "^4.9.2",
+    "@x12i/ai-tools": "^2.1.3",
     "@x12i/flex-md": "^4.8.0",
-    "@x12i/logxer": "^4.5.1",
+    "@x12i/logxer": "^4.6.0",
     "@x12i/optimixer": "^2.4.4",
     "@x12i/rendrix": "^4.3.0"
   },