@x12i/ai-gateway 9.6.7 → 9.6.8

package/dist-cjs/gateway.cjs

@@ -16,6 +16,7 @@ import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { applyOpenRouterInvokePolicy } from './ai-tools-client.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity, withGatewayLogContext } from './gateway-log-meta.js';
+import { exceptionEvidence, fieldEvidence, GatewayLogCode, gatewayErrorCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 import { invokeWithRetry } from './gateway-retry.js';
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
@@ -28,16 +29,24 @@ function warnIfSuccessfulInvokeReportsZeroUsageOrCost(logger, identity, meta, in
     const zeroCost = typeof cost === 'number' && cost === 0;
     if (!zeroTokens && !zeroCostUsd && !zeroCost)
         return;
-    logger.warn('Successful provider response reported zero token usage and/or zero cost; verify router adapter usage and billing metadata', withActivityIdentity(identity, {
+    gatewayWarnCode(logger, GatewayLogCode.ZERO_USAGE_OR_COST, identity, {
         invokeKind,
         zeroTokens,
         zeroCostUsd,
         zeroCostField: zeroCost,
-        tokens,
-        costUsd,
-        cost,
-        debugKind: gatewayLogDebug.anomaly
-    }));
+        debugKind: gatewayLogDebug.anomaly,
+        evidence: [
+            fieldEvidence('tokens.prompt', tokens.prompt),
+            fieldEvidence('tokens.completion', tokens.completion),
+            fieldEvidence('tokens.total', tokens.total),
+            fieldEvidence('costUsd', costUsd),
+            fieldEvidence('cost', cost)
+        ],
+        diagnostics: {
+            expected: 'Successful invoke should include non-zero token usage or cost when billing metadata is available.',
+            actual: `zeroTokens=${zeroTokens}, zeroCostUsd=${zeroCostUsd}, zeroCost=${zeroCost}`
+        }
+    });
 }
 /**
  * Simplified AI Gateway - Clean proxy implementation
@@ -494,12 +503,20 @@ export class AIGateway {
                     if (!response) {
                         const fallbackAttempts = buildGatewayFallbackAttemptsFromTrace(traceAttempts, deduped, lastError);
                         const providersTried = [...new Set(deduped.map((c) => c.provider))];
-                        this.logger.error('Trace fallback chain exhausted', withActivityIdentity(request.identity, {
+                        gatewayErrorCode(this.logger, GatewayLogCode.FALLBACK_CHAIN_EXHAUSTED, request.identity, {
                             providersTried,
-                            candidates: deduped,
-                            fallbackAttempts,
-                            debugKind: gatewayLogDebug.anomaly
-                        }));
+                            debugKind: gatewayLogDebug.anomaly,
+                            evidence: [
+                                fieldEvidence('providersTried', providersTried),
+                                fieldEvidence('candidateCount', deduped.length),
+                                fieldEvidence('fallbackAttempts', fallbackAttempts),
+                                ...(lastError ? [fieldEvidence('lastError.message', lastError.message)] : [])
+                            ],
+                            diagnostics: {
+                                expected: 'At least one provider/model candidate in the fallback chain should succeed.',
+                                actual: 'All candidates failed or returned no response.'
+                            }
+                        });
                         const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
                         exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
                         if (lastError) {
@@ -570,23 +587,32 @@ export class AIGateway {
                     }
                     else {
                         // Extraction failed, fall back to raw text wrapper
-                        this.logger.warn('Flex-md extraction failed - no structured data extracted', withActivityIdentity(request.identity, {
+                        gatewayWarnCode(this.logger, GatewayLogCode.FLEX_MD_EXTRACTION_FAILED, request.identity, {
                             hasResult: !!extractionResult,
                             method: extractionResult?.method || 'none',
-                            debugKind: gatewayLogDebug.anomaly
-                        }));
+                            debugKind: gatewayLogDebug.anomaly,
+                            evidence: [
+                                fieldEvidence('content.length', content.length),
+                                fieldEvidence('extraction.method', extractionResult?.method || 'none')
+                            ]
+                        });
                         parsedContent = { rawText: content };
                     }
                 }
                 catch (extractionError) {
                     // Extraction failed, fall back to raw text wrapper
                     const errorMessage = extractionError instanceof Error ? extractionError.message : String(extractionError);
-                    this.logger.warn('Flex-md extraction failed - flex-md library compatibility issue', withActivityIdentity(request.identity, {
+                    gatewayWarnCode(this.logger, GatewayLogCode.FLEX_MD_EXTRACTION_ERROR, request.identity, {
                         error: errorMessage,
-                        issue: 'flex-md uses require() in ES module context - needs fixing in flex-md-loader.ts',
                         fallback: 'using rawText wrapper',
-                        debugKind: gatewayLogDebug.anomaly
-                    }));
+                        debugKind: gatewayLogDebug.anomaly,
+                        evidence: [
+                            fieldEvidence('content.length', content.length),
+                            ...(extractionError instanceof Error
+                                ? [exceptionEvidence(extractionError)]
+                                : [fieldEvidence('error.message', errorMessage)])
+                        ]
+                    });
                     parsedContent = { rawText: content };
                 }
                 contentType = 'structured';

package/dist-cjs/index.cjs

@@ -30,9 +30,12 @@ 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, GATEWAY_LOG_ENV_PREFIX } from './logger-factory.js';
+export { createGatewayLogger } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, 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 } from '@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';
+export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
 // Runtime observability surface (leaf package: no downstream runtime objects)
 export { runtimeObjects } from './runtime-objects.js';
 // Export rate limiter

package/dist-cjs/index.d.ts

@@ -35,9 +35,13 @@ 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, GATEWAY_LOG_ENV_PREFIX } from './logger-factory.js';
-export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity } from '@x12i/logxer';
-export type { Logxer, LogMeta, RuntimeIdentity, LogRuntimeContext, GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
+export { createGatewayLogger } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, 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';
+export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
+export type { Logxer, LogMeta, RuntimeIdentity, LogRuntimeContext, GetJobLogsInput, GetJobLogsResult, QueryableLogLine, LogDiagnostics, DiagnosticEvidence, ScopeCriteria, ScopeLogsResult, StackLoggingOptions, PackageLogLevelsConfig, PackageLogLevelSetting } from '@x12i/logxer';
 export { runtimeObjects } from './runtime-objects.js';
 export type { ActivixQueryableClient, LogxerQueryableClient, PackageRuntimeObjects, RuntimeObjects } from './runtime-objects.js';
 export { GatewayRateLimiter } from './gateway-rate-limiter.js';

package/dist-cjs/logger-factory.cjs

@@ -4,8 +4,14 @@
  * Creates and configures logxer instances for the gateway
  */
 import { createLogxer, getStationRuntimeIdentity, mergeRuntimeIdentity } from '@x12i/logxer';
-/** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
-export const GATEWAY_LOG_ENV_PREFIX = 'AI_GATEWAY';
+import { resolveLogDiagnosticsCatalogPath } from './gateway-log-diagnostics.js';
+import { GATEWAY_LOG_ENV_PREFIX, initializeGatewayPackageLogLevels } from './gateway-log-levels.js';
+export { GATEWAY_LOG_ENV_PREFIX };
+const NOOP_GATEWAY_LOGGER = Symbol('noop-gateway-logger');
+/** True for the internal no-op logger when `enableLogging` is false. */
+export function isNoOpGatewayLogger(logger) {
+    return logger[NOOP_GATEWAY_LOGGER] === true;
+}
 function resolveGatewayRuntimeIdentity(packageName) {
     return mergeRuntimeIdentity(getStationRuntimeIdentity(), {
         service: process.env.AI_GATEWAY_LOG_SERVICE ?? packageName ?? GATEWAY_LOG_ENV_PREFIX,
@@ -25,26 +31,46 @@ export function createGatewayLogger(config) {
     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'
     }, {
-        // Level/format/sinks: ERC 2.0 env discovery (`AI_GATEWAY_LOGS_LEVEL`, host-level format, …).
-        runtimeIdentity: resolveGatewayRuntimeIdentity(config.packageName)
+        runtimeIdentity: resolveGatewayRuntimeIdentity(config.packageName),
+        stack: config.logging,
+        ...(config.logLevel !== undefined ? { logLevel: config.logLevel } : {}),
+        ...(catalogPath
+            ? {
+                diagnostics: {
+                    catalogPath,
+                    consoleMode: 'summary'
+                }
+            }
+            : {})
     });
 }
 function createNoOpLogger() {
     const noop = () => { };
-    return {
+    const noopAsync = async () => ({ lines: [], total: 0 });
+    const logger = {
         verbose: noop,
         debug: noop,
         info: noop,
         warn: noop,
         error: noop,
         success: noop,
+        infoCode: noop,
+        warnCode: noop,
+        errorCode: noop,
+        diagnostic: noop,
+        getJobLogs: noopAsync,
+        scopeLogs: noopAsync,
         isLevelEnabled: () => false,
         getConfig: () => ({}),
-        shadow: {}
+        shadow: {},
+        [NOOP_GATEWAY_LOGGER]: true
     };
+    return logger;
 }

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

@@ -3,9 +3,11 @@
  *
  * Creates and configures logxer instances for the gateway
  */
-import { type Logxer } from '@x12i/logxer';
-/** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
-export declare const GATEWAY_LOG_ENV_PREFIX = "AI_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 };
+/** 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
  *
@@ -16,4 +18,10 @@ export declare function createGatewayLogger(config: {
     enableLogging: boolean;
     packageName?: string;
     customLogger?: Logxer;
+    /** Parent/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;

package/dist-cjs/optimixer-manager.cjs

@@ -1,4 +1,5 @@
 import { Optimixer } from '@x12i/optimixer';
+import { exceptionEvidence, fieldEvidence, GatewayLogCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
 import { estimateMessagesTokenSizes } from './token-estimate.js';
 /** Optimixer bucket key: prefer taskTypeId (template), then identity actionType, else gateway default. */
@@ -47,8 +48,9 @@ export class OptimixerManager {
     async initialize() {
         const activix = await this.getActivix();
         if (!activix) {
-            this.logger.warn('Optimixer enabled but Activix is unavailable; adaptive max_tokens disabled', {
-                activixCollection: this.activixCollection
+            gatewayWarnCode(this.logger, GatewayLogCode.OPTIMIXER_ACTIVIX_UNAVAILABLE, undefined, {
+                activixCollection: this.activixCollection,
+                evidence: [fieldEvidence('activixCollection', this.activixCollection)]
             });
             return;
         }
@@ -65,8 +67,12 @@ export class OptimixerManager {
             });
         }
         catch (error) {
-            this.logger.warn('Optimixer initialization failed; adaptive max_tokens disabled', {
-                error: error instanceof Error ? error.message : String(error)
+            gatewayWarnCode(this.logger, GatewayLogCode.OPTIMIXER_INIT_FAILED, undefined, {
+                error: error instanceof Error ? error.message : String(error),
+                evidence: [
+                    fieldEvidence('activixCollection', this.activixCollection),
+                    ...(error instanceof Error ? [exceptionEvidence(error)] : [])
+                ]
             });
             this.optimixer = undefined;
         }
@@ -93,9 +99,13 @@ export class OptimixerManager {
             });
         }
         catch (error) {
-            this.logger.warn('Optimixer predictAiMaxTokens failed; caller should use fallback max_tokens', {
+            gatewayWarnCode(this.logger, GatewayLogCode.OPTIMIXER_PREDICT_FAILED, request.identity, {
                 error: error instanceof Error ? error.message : String(error),
-                aiRequestId: request.aiRequestId
+                aiRequestId: request.aiRequestId,
+                evidence: [
+                    fieldEvidence('aiRequestId', request.aiRequestId),
+                    ...(error instanceof Error ? [exceptionEvidence(error)] : [])
+                ]
             });
             return undefined;
         }

package/dist-cjs/runtime-objects.cjs

@@ -1,3 +1,4 @@
+import { isNoOpGatewayLogger } from './logger-factory.js';
 export let runtimeObjects = createRuntimeObjectsForMode();
 export function setGatewayLastJobId(jobId) {
     const objects = ensureRuntimeObjectsForCurrentMode();
@@ -41,6 +42,14 @@ function asActivixQueryableClient(activix) {
     return typeof candidate.getJobActivities === 'function' ? candidate : undefined;
 }
 function asLogxerQueryableClient(logger) {
+    if (isNoOpGatewayLogger(logger)) {
+        return undefined;
+    }
     const candidate = logger;
-    return typeof candidate.getJobLogs === 'function' ? candidate : undefined;
+    if (typeof candidate.getJobLogs !== 'function') {
+        return undefined;
+    }
+    return typeof candidate.scopeLogs === 'function'
+        ? { getJobLogs: candidate.getJobLogs.bind(candidate), scopeLogs: candidate.scopeLogs.bind(candidate) }
+        : { getJobLogs: candidate.getJobLogs.bind(candidate) };
 }

package/dist-cjs/runtime-objects.d.ts

@@ -2,7 +2,7 @@ import type { Logxer } from '@x12i/logxer';
 import type { Activix, ActivixQueryableClient } from '@x12i/activix';
 export type { ActivixQueryableClient } from '@x12i/activix';
 export type { GetJobLogsInput, GetJobLogsResult } from '@x12i/logxer';
-export type LogxerQueryableClient = Pick<Logxer, 'getJobLogs'>;
+export type LogxerQueryableClient = Pick<Logxer, 'getJobLogs'> & Partial<Pick<Logxer, 'scopeLogs'>>;
 export type PackageRuntimeObjects = {
     name: string;
     activixClient?: ActivixQueryableClient;

package/dist-cjs/types.d.ts

@@ -9,7 +9,7 @@ type AIModel = string;
 export type UsageTier = string;
 import type { Activix } from '@x12i/activix';
 import type { SmartInputConfig, SmartInputRenderOptions, TemplateRenderOptions } from '@x12i/rendrix';
-import type { Logxer } from '@x12i/logxer';
+import type { Logxer, PackageLogLevelsConfig } from '@x12i/logxer';
 /**
  * Diagnostics options for opt-in authoritative tracing.
  * Default behavior must remain minimal when diagnostics are not enabled.
@@ -349,6 +349,13 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
      * @default true
      */
     enableLogging?: boolean;
+    /**
+     * Process-wide package log level registry (logxer ≥ 4.5).
+     * Merged after `applyPackageLogLevelsFromEnv()` on first gateway init.
+     * `logging` (from {@link RouterConfig}) is forwarded to the gateway logger and router.
+     * @example `{ default: 'warn', levels: { AI_GATEWAY: 'info', AI_PROVIDER_ROUTER: 'debug' } }`
+     */
+    packageLogLevels?: PackageLogLevelsConfig;
     /**
      * Custom logger instance (optional)
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.6.7",
+  "version": "9.6.8",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -42,11 +42,11 @@
   "license": "mit",
   "dependencies": {
     "@x12i/activix": "^8.3.1",
-    "@x12i/ai-providers-router": "^4.8.6",
+    "@x12i/ai-providers-router": "^4.8.8",
     "@x12i/ai-tools": "^2.1.2",
     "@x12i/flex-md": "^4.8.0",
-    "@x12i/logxer": "^4.4.0",
-    "@x12i/optimixer": "^2.4.1",
+    "@x12i/logxer": "^4.5.0",
+    "@x12i/optimixer": "^2.4.2",
     "@x12i/rendrix": "^4.3.0"
   },
   "devDependencies": {