@x12i/ai-gateway 9.6.5 → 9.6.8

package/dist/logger-factory.js

@@ -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/optimixer-manager.js

@@ -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/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/runtime-objects.js

@@ -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/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/dist-cjs/defaults/log-diagnostics.json

@@ -0,0 +1,176 @@
+{
+  "GATEWAY_ZERO_USAGE_OR_COST": {
+    "defaultLevel": "warn",
+    "title": "Successful invoke reported zero token usage and/or zero cost",
+    "impact": "Billing and usage metadata may be missing from the provider adapter.",
+    "possibleCauses": [
+      "Router adapter did not populate usage fields.",
+      "Provider response omitted token counts.",
+      "Cost calculation was skipped or returned zero."
+    ],
+    "remediation": [
+      "Verify router adapter usage extraction.",
+      "Confirm ai-tools cost resolution is enabled when pricing is expected."
+    ],
+    "retryable": false,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_FALLBACK_CHAIN_EXHAUSTED": {
+    "defaultLevel": "error",
+    "title": "Provider fallback chain exhausted without a successful response",
+    "impact": "The AI request failed after all configured provider/model candidates were tried.",
+    "possibleCauses": [
+      "All providers in the chain returned errors.",
+      "Rate limits or auth failures across candidates.",
+      "Model or profile misconfiguration."
+    ],
+    "remediation": [
+      "Inspect fallbackAttempts in the log evidence.",
+      "Verify API keys and provider registration.",
+      "Review trace-mode metadata.attempts when enabled."
+    ],
+    "retryable": true,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "GATEWAY_FLEX_MD_EXTRACTION_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Flex-md extraction did not produce structured output",
+    "impact": "Parsed content falls back to a rawText wrapper; downstream contract validation may fail.",
+    "possibleCauses": [
+      "Model response was plain text without expected markdown structure.",
+      "flex-md headers or fenced blocks were missing.",
+      "Response was truncated before structured content completed."
+    ],
+    "remediation": [
+      "Inspect raw response sample.",
+      "Tighten instructions for markdown/JSON output format.",
+      "Check max token allocation."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_FLEX_MD_EXTRACTION_ERROR": {
+    "defaultLevel": "warn",
+    "title": "Flex-md extraction threw during parsing",
+    "impact": "Structured parsing failed; gateway uses rawText fallback.",
+    "possibleCauses": [
+      "flex-md library compatibility or loader issue.",
+      "Malformed markdown in the model response.",
+      "Unexpected response shape from the provider."
+    ],
+    "remediation": [
+      "Review the exception evidence.",
+      "Confirm flex-md version alignment with the gateway.",
+      "Inspect raw provider content."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_DEFAULT_MODEL_SUBSTITUTED": {
+    "defaultLevel": "warn",
+    "title": "Gateway substituted the configured default model",
+    "impact": "The request may run on a different provider/model than the caller specified.",
+    "possibleCauses": [
+      "Request omitted model while gateway defaults apply.",
+      "Operational mode requires a packaged default engine.",
+      "Profile resolution fell back to gateway defaults."
+    ],
+    "remediation": [
+      "Pass an explicit model on the request when substitution is undesired.",
+      "Review default model configuration and AI_TOOLS routing."
+    ],
+    "retryable": false,
+    "userActionRequired": false,
+    "confidence": "high"
+  },
+  "GATEWAY_RETRY_MAX_EXCEEDED": {
+    "defaultLevel": "warn",
+    "title": "Provider invoke retries exhausted",
+    "impact": "The router call failed after the configured retry budget.",
+    "possibleCauses": [
+      "Transient network or server errors persisted.",
+      "Throttling (429) without sufficient backoff.",
+      "Non-recoverable provider outage."
+    ],
+    "remediation": [
+      "Inspect error and status code evidence.",
+      "Increase retry limits or backoff if appropriate.",
+      "Check provider status and rate limits."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "high"
+  },
+  "GATEWAY_RETRY_ATTEMPT": {
+    "defaultLevel": "warn",
+    "title": "Retrying provider invoke after error",
+    "impact": "Request latency increases while the gateway retries.",
+    "possibleCauses": [
+      "Transient HTTP or network failure.",
+      "Rate limiting with backoff.",
+      "Timeout from the provider."
+    ],
+    "remediation": [
+      "Monitor retry counts per job.",
+      "Tune retry policy if retries are frequent."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_OPTIMIXER_ACTIVIX_UNAVAILABLE": {
+    "defaultLevel": "warn",
+    "title": "Optimixer enabled but Activix is unavailable",
+    "impact": "Adaptive max_tokens prediction is disabled for this gateway instance.",
+    "possibleCauses": [
+      "Activity tracking is disabled or Activix failed to initialize.",
+      "Mongo connection or collection configuration is missing."
+    ],
+    "remediation": [
+      "Enable activity tracking with a working Activix connection.",
+      "Verify activixCollection configuration."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "GATEWAY_OPTIMIXER_INIT_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Optimixer initialization failed",
+    "impact": "Adaptive max_tokens prediction is disabled.",
+    "possibleCauses": [
+      "Activix schema or collection mismatch.",
+      "Optimixer configuration error.",
+      "Dependency or network failure during create()."
+    ],
+    "remediation": [
+      "Check Activix connectivity and collection names.",
+      "Review optimixer gateway config."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "GATEWAY_OPTIMIXER_PREDICT_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Optimixer predictAiMaxTokens failed",
+    "impact": "Caller should use fallback max_tokens for the invoke.",
+    "possibleCauses": [
+      "Insufficient historical samples for the template.",
+      "Token estimation or profile resolution failed.",
+      "Optimixer internal error."
+    ],
+    "remediation": [
+      "Set explicit max_tokens on the request.",
+      "Verify templateId and model profile fields.",
+      "Check prediction history in Activix."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  }
+}

package/dist-cjs/gateway-config.cjs

@@ -162,7 +162,10 @@ export function initializeGatewayComponents(config) {
     const logger = createGatewayLogger({
         enableLogging: config.enableLogging ?? true,
         packageName: config.packageName,
-        customLogger: config.logger
+        customLogger: config.logger,
+        logging: config.logging,
+        packageLogLevels: config.packageLogLevels,
+        logLevel: config.logLevel
     });
     const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig(logger);
     logger.verbose('Gateway initializing', {
@@ -194,6 +197,12 @@ export function initializeGatewayComponents(config) {
         routerConfig.autoDiscover = config.autoDiscover;
     if (config.usageTracker !== undefined)
         routerConfig.usageTracker = config.usageTracker;
+    if (config.verbose !== undefined)
+        routerConfig.verbose = config.verbose;
+    if (config.logLevel !== undefined)
+        routerConfig.logLevel = config.logLevel;
+    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.
     const openRouterKey = resolveOpenRouterApiKey(config);

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

@@ -0,0 +1,72 @@
+/**
+ * Logxer 4.4+ diagnostic catalog codes and helpers for structured anomaly logging.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { exceptionEvidence, fieldEvidence } from '@x12i/logxer';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+export { exceptionEvidence, fieldEvidence };
+/** Stable diagnostic codes backed by `src/defaults/log-diagnostics.json`. */
+export const GatewayLogCode = {
+    ZERO_USAGE_OR_COST: 'GATEWAY_ZERO_USAGE_OR_COST',
+    FALLBACK_CHAIN_EXHAUSTED: 'GATEWAY_FALLBACK_CHAIN_EXHAUSTED',
+    FLEX_MD_EXTRACTION_FAILED: 'GATEWAY_FLEX_MD_EXTRACTION_FAILED',
+    FLEX_MD_EXTRACTION_ERROR: 'GATEWAY_FLEX_MD_EXTRACTION_ERROR',
+    DEFAULT_MODEL_SUBSTITUTED: 'GATEWAY_DEFAULT_MODEL_SUBSTITUTED',
+    RETRY_MAX_EXCEEDED: 'GATEWAY_RETRY_MAX_EXCEEDED',
+    RETRY_ATTEMPT: 'GATEWAY_RETRY_ATTEMPT',
+    OPTIMIXER_ACTIVIX_UNAVAILABLE: 'GATEWAY_OPTIMIXER_ACTIVIX_UNAVAILABLE',
+    OPTIMIXER_INIT_FAILED: 'GATEWAY_OPTIMIXER_INIT_FAILED',
+    OPTIMIXER_PREDICT_FAILED: 'GATEWAY_OPTIMIXER_PREDICT_FAILED'
+};
+function getModuleDir() {
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    try {
+        const getMetaUrl = new Function('return import.meta.url');
+        const metaUrl = getMetaUrl();
+        if (metaUrl && metaUrl.startsWith('file:')) {
+            return path.dirname(fileURLToPath(metaUrl));
+        }
+    }
+    catch {
+        // fall through
+    }
+    return process.cwd();
+}
+/** Resolve packaged `defaults/log-diagnostics.json` for createLogxer diagnostics.catalogPath. */
+export function resolveLogDiagnosticsCatalogPath() {
+    const moduleDir = getModuleDir();
+    const cwd = process.cwd();
+    const candidates = [
+        moduleDir,
+        path.resolve(moduleDir, '..'),
+        path.resolve(moduleDir, '../dist'),
+        path.resolve(moduleDir, '../dist-cjs'),
+        path.resolve(moduleDir, '../src'),
+        path.join(cwd, 'dist'),
+        path.join(cwd, 'dist-cjs'),
+        path.join(cwd, 'src')
+    ];
+    for (const dir of candidates) {
+        const catalogPath = path.join(dir, 'defaults', 'log-diagnostics.json');
+        if (fs.existsSync(catalogPath)) {
+            return catalogPath;
+        }
+    }
+    return undefined;
+}
+export function gatewayWarnCode(logger, code, identity, data) {
+    logger.warnCode(code, withActivityIdentity(identity, data));
+}
+export function gatewayErrorCode(logger, code, identity, data) {
+    logger.errorCode(code, withActivityIdentity(identity, data));
+}
+export function gatewayInfoCode(logger, code, identity, data) {
+    logger.infoCode(code, withActivityIdentity(identity, data));
+}
+export function gatewayAnomalyMeta(identity, data) {
+    return withActivityIdentity(identity, data, gatewayLogDebug.anomaly);
+}

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

@@ -0,0 +1,23 @@
+import { exceptionEvidence, fieldEvidence, type LogMeta, type Logxer } from '@x12i/logxer';
+import type { ActivityIdentity } from './types.js';
+export { exceptionEvidence, fieldEvidence };
+/** Stable diagnostic codes backed by `src/defaults/log-diagnostics.json`. */
+export declare const GatewayLogCode: {
+    readonly ZERO_USAGE_OR_COST: "GATEWAY_ZERO_USAGE_OR_COST";
+    readonly FALLBACK_CHAIN_EXHAUSTED: "GATEWAY_FALLBACK_CHAIN_EXHAUSTED";
+    readonly FLEX_MD_EXTRACTION_FAILED: "GATEWAY_FLEX_MD_EXTRACTION_FAILED";
+    readonly FLEX_MD_EXTRACTION_ERROR: "GATEWAY_FLEX_MD_EXTRACTION_ERROR";
+    readonly DEFAULT_MODEL_SUBSTITUTED: "GATEWAY_DEFAULT_MODEL_SUBSTITUTED";
+    readonly RETRY_MAX_EXCEEDED: "GATEWAY_RETRY_MAX_EXCEEDED";
+    readonly RETRY_ATTEMPT: "GATEWAY_RETRY_ATTEMPT";
+    readonly OPTIMIXER_ACTIVIX_UNAVAILABLE: "GATEWAY_OPTIMIXER_ACTIVIX_UNAVAILABLE";
+    readonly OPTIMIXER_INIT_FAILED: "GATEWAY_OPTIMIXER_INIT_FAILED";
+    readonly OPTIMIXER_PREDICT_FAILED: "GATEWAY_OPTIMIXER_PREDICT_FAILED";
+};
+export type GatewayLogCode = (typeof GatewayLogCode)[keyof typeof GatewayLogCode];
+/** Resolve packaged `defaults/log-diagnostics.json` for createLogxer diagnostics.catalogPath. */
+export declare function resolveLogDiagnosticsCatalogPath(): string | undefined;
+export declare function gatewayWarnCode(logger: Logxer, code: GatewayLogCode | string, identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): void;
+export declare function gatewayErrorCode(logger: Logxer, code: GatewayLogCode | string, identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): void;
+export declare function gatewayInfoCode(logger: Logxer, code: GatewayLogCode | string, identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): void;
+export declare function gatewayAnomalyMeta(identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): LogMeta;

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

@@ -0,0 +1,33 @@
+/**
+ * Logxer ≥ 4.5 — process-wide package log levels for the gateway dependency stack.
+ * @see node_modules/@x12i/logxer/docs/package-log-levels-stack.md
+ */
+import { applyPackageLogLevelsFromEnv, mergePackageLogLevelsConfig } from '@x12i/logxer';
+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';
+/** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
+export const GATEWAY_STACK_LOG_PREFIXES = {
+    gateway: GATEWAY_LOG_ENV_PREFIX,
+    router: ROUTER_LOG_ENV_PREFIX,
+    flexMd: 'FLEX_MD',
+    optimixer: 'OPTIMIXER'
+};
+let packageLogLevelsInitialized = false;
+/**
+ * Load bulk env (`LOGXER_PACKAGE_LEVELS`, `LOGXER_PACKAGE_LOGS_DEFAULT`) and merge optional host config.
+ * Idempotent — safe to call from `createGatewayLogger` / `initializeGatewayComponents`.
+ */
+export function initializeGatewayPackageLogLevels(options) {
+    if (!packageLogLevelsInitialized) {
+        applyPackageLogLevelsFromEnv();
+        packageLogLevelsInitialized = true;
+    }
+    if (options?.packageLogLevels) {
+        mergePackageLogLevelsConfig(options.packageLogLevels);
+    }
+}
+/** Reset init flag (tests). */
+export function resetGatewayPackageLogLevelsInit() {
+    packageLogLevelsInitialized = false;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Logxer ≥ 4.5 — process-wide package log levels for the gateway dependency stack.
+ * @see node_modules/@x12i/logxer/docs/package-log-levels-stack.md
+ */
+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";
+/** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
+export declare const GATEWAY_STACK_LOG_PREFIXES: {
+    readonly gateway: "AI_GATEWAY";
+    readonly router: "AI_PROVIDER_ROUTER";
+    readonly flexMd: "FLEX_MD";
+    readonly optimixer: "OPTIMIXER";
+};
+/**
+ * Load bulk env (`LOGXER_PACKAGE_LEVELS`, `LOGXER_PACKAGE_LOGS_DEFAULT`) and merge optional host config.
+ * Idempotent — safe to call from `createGatewayLogger` / `initializeGatewayComponents`.
+ */
+export declare function initializeGatewayPackageLogLevels(options?: {
+    packageLogLevels?: PackageLogLevelsConfig;
+}): void;
+/** Reset init flag (tests). */
+export declare function resetGatewayPackageLogLevelsInit(): void;

package/dist-cjs/gateway-mode.cjs

@@ -1,7 +1,8 @@
 /**
  * Gateway operational mode (prod vs dev/debug) and default model resolution.
  */
-import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+import { gatewayLogDebug } from './gateway-log-meta.js';
+import { fieldEvidence, GatewayLogCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 /** Profile name resolved via ai-tools + {@link @x12i/ai-profiles} when catalog is enabled. */
 export const CODE_DEFAULT_MODEL = 'cheap';
 /**
@@ -69,8 +70,16 @@ export function resolveGatewayDefaultModel(defaultModelConfig, gatewayDefaultEng
     };
 }
 export function warnDefaultModelSubstitution(logger, identity, details) {
-    logger.warn('Gateway substituted default model for request', withActivityIdentity(identity, {
+    gatewayWarnCode(logger, GatewayLogCode.DEFAULT_MODEL_SUBSTITUTED, identity, {
         ...details,
-        debugKind: gatewayLogDebug.anomaly
-    }));
+        debugKind: gatewayLogDebug.anomaly,
+        evidence: [
+            fieldEvidence('defaultModel', details.defaultModel),
+            fieldEvidence('defaultSource', details.defaultSource),
+            fieldEvidence('reason', details.reason),
+            fieldEvidence('mode', details.mode),
+            ...(details.originalModel ? [fieldEvidence('originalModel', details.originalModel)] : []),
+            ...(details.originalProvider ? [fieldEvidence('originalProvider', details.originalProvider)] : [])
+        ]
+    });
 }

package/dist-cjs/gateway-retry.cjs

@@ -5,6 +5,7 @@
  * NOTE: Retry delays use SIMPLE SLEEP (not smart rate limiting).
  * Between-calls rate limiting is handled separately in gateway-rate-limiter.ts (smart).
  */
+import { exceptionEvidence, fieldEvidence, GatewayLogCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 /**
  * Determines if an error is a network error (fetch failed, DNS, connectivity)
  */
@@ -146,12 +147,18 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
             }
             // If this was the last attempt, throw the error
             if (attempt >= maxRetries) {
-                logger.warn('Max retries exceeded', {
+                gatewayWarnCode(logger, GatewayLogCode.RETRY_MAX_EXCEEDED, undefined, {
                     jobId,
                     error: lastError.message,
                     errorName: lastError.name,
                     totalAttempts: attempt + 1,
-                    maxRetries
+                    maxRetries,
+                    evidence: [
+                        fieldEvidence('jobId', jobId),
+                        fieldEvidence('totalAttempts', attempt + 1),
+                        fieldEvidence('maxRetries', maxRetries),
+                        exceptionEvidence(lastError)
+                    ]
                 });
                 throw lastError;
             }
@@ -187,7 +194,7 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
                 errorType,
                 delayMs: Math.round(delay)
             });
-            logger.warn('Retrying request after error', {
+            gatewayWarnCode(logger, GatewayLogCode.RETRY_ATTEMPT, undefined, {
                 jobId,
                 error: lastError.message,
                 errorName: lastError.name,
@@ -195,7 +202,15 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
                 attempt: attempt + 1,
                 maxRetries: maxRetries + 1,
                 delayMs: Math.round(delay),
-                statusCode
+                statusCode,
+                evidence: [
+                    fieldEvidence('jobId', jobId),
+                    fieldEvidence('attempt', attempt + 1),
+                    fieldEvidence('errorType', errorType),
+                    fieldEvidence('delayMs', Math.round(delay)),
+                    ...(statusCode !== undefined ? [fieldEvidence('statusCode', statusCode)] : []),
+                    exceptionEvidence(lastError)
+                ]
             });
             await sleep(delay);
         }