@x12i/ai-gateway 7.9.1 → 9.0.0

package/dist-cjs/gateway-meta.d.ts

@@ -2,13 +2,15 @@
  * Gateway Meta Operations Module
  * Handles meta operations like instruction optimization and testing
  */
-import type { EnhancedLLMResponse, GatewayConfig } from './types.js';
+import type { ActivityIdentity, EnhancedLLMResponse, GatewayConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import type { AIGateway } from './gateway.js';
 /**
  * Test instructions by running them and analyzing the response
  */
 export declare function testInstructions(instructions: string, testInput: string, expectedSchema: Record<string, unknown> | undefined, options: {
+    /** Mandatory runtime identity for the internal test invoke (upstream job/task correlation). */
+    identity: ActivityIdentity;
     agentId?: string;
     model?: string;
     provider?: string;

package/dist-cjs/gateway-utils.cjs

@@ -60,7 +60,7 @@ async function ensureTaskTypeId(request, logger) {
     // Generate MD5 hash
     const taskTypeId = generateMD5Hash(preParsedInstructions);
     logger.debug('Auto-generated taskTypeId from instructions MD5 hash', {
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         taskTypeId,
         instructionsLength: preParsedInstructions.length,
         instructionsPreview: preParsedInstructions.substring(0, 100) + (preParsedInstructions.length > 100 ? '...' : '')
@@ -79,7 +79,7 @@ async function mergeConfig(request, config, logger) {
             : config.internalSystemActions?.skillAudit)
         : undefined;
     logger.verbose('Merging request config with gateway defaults', {
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         hasRequestConfig: !!request.config,
         hasModelConfig: !!request.modelConfig,
         requestModel: request.config?.model,
@@ -134,7 +134,7 @@ async function mergeConfig(request, config, logger) {
     // Log if using default model
     if (!request.config?.model && !internalDefaults?.model) {
         logger.info('Using default model: gpt-5-nano (no model provided in request)', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             note: 'Default model ensures requests always work regardless of configuration'
         });
     }
@@ -150,7 +150,7 @@ async function mergeConfig(request, config, logger) {
             if (flexMdMaxTokens && flexMdMaxTokens > 0) {
                 merged.maxTokens = flexMdMaxTokens;
                 logger.debug('Using maxTokens from flex-md', {
-                    jobId: request.jobId,
+                    jobId: request.identity.jobId,
                     model: merged.model,
                     provider: merged.provider,
                     maxTokens: merged.maxTokens,
@@ -161,7 +161,7 @@ async function mergeConfig(request, config, logger) {
                 // flex-md doesn't have model info or returned invalid value - use fallback
                 merged.maxTokens = 2000;
                 logger.debug('Using fallback maxTokens (flex-md unavailable or no model info)', {
-                    jobId: request.jobId,
+                    jobId: request.identity.jobId,
                     model: merged.model,
                     provider: merged.provider,
                     maxTokens: merged.maxTokens,
@@ -173,7 +173,7 @@ async function mergeConfig(request, config, logger) {
             // Error loading flex-md or getting model info - use fallback
             merged.maxTokens = 2000;
             logger.debug('Using fallback maxTokens (flex-md error)', {
-                jobId: request.jobId,
+                jobId: request.identity.jobId,
                 model: merged.model,
                 provider: merged.provider,
                 maxTokens: merged.maxTokens,
@@ -187,7 +187,7 @@ async function mergeConfig(request, config, logger) {
         // This should rarely happen, but handle edge cases
         merged.maxTokens = 2000;
         logger.debug('Using fallback maxTokens (not auto-detected and not explicitly set)', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             model: merged.model,
             provider: merged.provider,
             maxTokens: merged.maxTokens,
@@ -200,7 +200,7 @@ async function mergeConfig(request, config, logger) {
             internalDefaults?.maxTokens !== undefined ? `internalSystemActions.${useInternalDefaults}` :
                 'gateway.config';
         logger.debug('Using explicitly set maxTokens', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             model: merged.model,
             provider: merged.provider,
             maxTokens: merged.maxTokens,
@@ -208,7 +208,7 @@ async function mergeConfig(request, config, logger) {
         });
     }
     logger.debug('Config merged', {
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         finalModel: merged.model,
         finalProvider: merged.provider,
         finalTemperature: merged.temperature,

package/dist-cjs/gateway-validation.cjs

@@ -6,6 +6,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateChatRequest = validateChatRequest;
 exports.validateAIRequest = validateAIRequest;
+function validateMandatoryRuntimeIdentity(request) {
+    const id = request.identity;
+    if (id === undefined || id === null || typeof id !== 'object') {
+        throw new Error('identity is required on every request (mandatory runtime identity from upstream)');
+    }
+    // identity.jobId / identity.taskId: TypeScript requires them; at runtime empty values are logged as WARN in ensureGatewayRequestIdentity.
+}
 /**
  * Validates ChatRequest has required fields
  */
@@ -16,6 +23,7 @@ function validateChatRequest(request) {
     if (!request.agentId) {
         throw new Error('agentId is required');
     }
+    validateMandatoryRuntimeIdentity(request);
     // Reject input field - it has been removed
     if ('input' in request && request.input !== undefined) {
         const err = new Error(`The 'input' field has been removed. Use workingMemory.input instead for template rendering. Prompt templates should contain {{input}} which will be resolved from workingMemory.input.`);
@@ -38,6 +46,7 @@ function validateAIRequest(request) {
     if (!request.agentId) {
         throw new Error('agentId is required for AI requests');
     }
+    validateMandatoryRuntimeIdentity(request);
     // Reject input field - it has been removed
     if ('input' in request && request.input !== undefined) {
         const err = new Error(`The 'input' field has been removed. Use workingMemory.input instead for template rendering. Prompt templates should contain {{input}} which will be resolved from workingMemory.input.`);

package/dist-cjs/gateway.cjs

@@ -14,6 +14,7 @@ const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
 const gateway_utils_js_1 = require("./gateway-utils.cjs");
 const gateway_provider_auto_register_js_1 = require("./gateway-provider-auto-register.cjs");
 const runtime_objects_js_1 = require("./runtime-objects.cjs");
+const gateway_log_meta_js_1 = require("./gateway-log-meta.cjs");
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
 const NO_PROVIDER_HINT = ' Set OPEN_ROUTER_KEY (or OPENROUTER_API_KEY) in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
@@ -30,9 +31,7 @@ class AIGateway {
     constructor(config = {}, activityManager) {
         this.config = config;
         this.activityManager = activityManager;
-        // Load configuration and initialize components
-        const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = (0, gateway_config_js_1.loadConfig)();
-        const components = (0, gateway_config_js_1.initializeGatewayComponents)(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering);
+        const components = (0, gateway_config_js_1.initializeGatewayComponents)(config);
         this.logger = components.logger;
         this.router = components.router;
         this.activityManager = components.activityManager;
@@ -53,9 +52,7 @@ class AIGateway {
         const startTime = Date.now();
         // Basic validation
         (0, gateway_validation_js_1.validateChatRequest)(request);
-        if (!this.activityManager) {
-            (0, activity_manager_js_1.ensureGatewayRequestIdentity)(request);
-        }
+        (0, activity_manager_js_1.ensureGatewayRequestIdentity)(request, undefined, this.logger);
         (0, runtime_objects_js_1.setGatewayLastJobId)(resolveRuntimeJobId(request));
         // Generate simple task type ID
         const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
@@ -138,9 +135,7 @@ class AIGateway {
         const startTime = Date.now();
         // Basic validation
         (0, gateway_validation_js_1.validateAIRequest)(request);
-        if (!this.activityManager) {
-            (0, activity_manager_js_1.ensureGatewayRequestIdentity)(request);
-        }
+        (0, activity_manager_js_1.ensureGatewayRequestIdentity)(request, undefined, this.logger);
         (0, runtime_objects_js_1.setGatewayLastJobId)(resolveRuntimeJobId(request));
         // Generate simple task type ID
         const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
@@ -255,48 +250,48 @@ class AIGateway {
             let parsingMethod = undefined;
             // Actually use flex-md parsing - extract structured data from markdown
             try {
-                this.logger.debug('Attempting flex-md extraction', {
-                    aiRequestId: request.aiRequestId,
+                this.logger.debug('Attempting flex-md extraction', (0, gateway_log_meta_js_1.withActivityIdentity)(request.identity, {
                     contentLength: content.length,
-                    hasInstructions: !!resolvedRequest.instructions
-                });
+                    hasInstructions: !!resolvedRequest.instructions,
+                    debugKind: gateway_log_meta_js_1.gatewayLogDebug.intent
+                }));
                 // Let flex-md extract structured data from the response content
-                const extractionResult = await (0, flex_md_loader_js_1.extractJsonFromFlexMd)(content);
-                this.logger.debug('Flex-md extraction result', {
-                    aiRequestId: request.aiRequestId,
+                const extractionResult = await (0, flex_md_loader_js_1.extractJsonFromFlexMd)(content, this.logger);
+                this.logger.debug('Flex-md extraction result', (0, gateway_log_meta_js_1.withActivityIdentity)(request.identity, {
                     hasResult: !!extractionResult,
                     hasJson: !!(extractionResult && extractionResult.json),
                     method: extractionResult?.method,
-                    jsonType: extractionResult?.json ? typeof extractionResult.json : 'none'
-                });
+                    jsonType: extractionResult?.json ? typeof extractionResult.json : 'none',
+                    debugKind: gateway_log_meta_js_1.gatewayLogDebug.state
+                }));
                 if (extractionResult && extractionResult.json) {
                     // Successfully extracted structured data
                     parsedContent = extractionResult.json;
-                    this.logger.info('Flex-md extraction successful - parsed into structured object', {
-                        aiRequestId: request.aiRequestId,
+                    this.logger.info('Flex-md extraction successful - parsed into structured object', (0, gateway_log_meta_js_1.withActivityIdentity)(request.identity, {
                         method: extractionResult.method,
-                        extractedKeys: Object.keys(extractionResult.json)
-                    });
+                        extractedKeys: Object.keys(extractionResult.json),
+                        debugKind: gateway_log_meta_js_1.gatewayLogDebug.event
+                    }));
                 }
                 else {
                     // Extraction failed, fall back to raw text wrapper
-                    this.logger.warn('Flex-md extraction failed - no structured data extracted', {
-                        aiRequestId: request.aiRequestId,
+                    this.logger.warn('Flex-md extraction failed - no structured data extracted', (0, gateway_log_meta_js_1.withActivityIdentity)(request.identity, {
                         hasResult: !!extractionResult,
-                        method: extractionResult?.method || 'none'
-                    });
+                        method: extractionResult?.method || 'none',
+                        debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+                    }));
                     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', {
-                    aiRequestId: request.aiRequestId,
+                this.logger.warn('Flex-md extraction failed - flex-md library compatibility issue', (0, gateway_log_meta_js_1.withActivityIdentity)(request.identity, {
                     error: errorMessage,
                     issue: 'flex-md uses require() in ES module context - needs fixing in flex-md-loader.ts',
-                    fallback: 'using rawText wrapper'
-                });
+                    fallback: 'using rawText wrapper',
+                    debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+                }));
                 parsedContent = { rawText: content };
             }
             contentType = 'structured';
@@ -361,7 +356,11 @@ class AIGateway {
                     });
                 }
             }
-            console.debug('gateway: enhancedResponse:', enhancedResponse);
+            this.logger.debug('gateway: enhancedResponse', (0, gateway_log_meta_js_1.withActivityIdentity)(request.identity, {
+                latencyMs: enhancedResponse.metadata?.latencyMs,
+                contentType: enhancedResponse.metadata?.contentType,
+                debugKind: gateway_log_meta_js_1.gatewayLogDebug.state
+            }));
             return enhancedResponse;
         }
         catch (error) {
@@ -430,5 +429,5 @@ class AIGateway {
 }
 exports.AIGateway = AIGateway;
 function resolveRuntimeJobId(request) {
-    return request.identity?.jobId ?? request.jobId ?? request.identity?.sessionId ?? request.aiRequestId;
+    return request.identity.jobId || request.identity.sessionId || request.aiRequestId;
 }

package/dist-cjs/index.cjs

@@ -21,7 +21,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = exports.getObjectTypesForAgent = exports.getObjectType = exports.OBJECT_TYPES_LIBRARY = exports.assertValidAIRequest = exports.formatDiagnostic = exports.runValidationTests = exports.createValidationTestCases = exports.createTestAIRequest = exports.supportsJSONMode = exports.diagnoseResponse = exports.diagnoseRequest = exports.validateResponse = exports.extractJSON = exports.validateJSON = exports.validateAIRequest = exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = exports.GatewayRateLimiter = exports.runtimeObjects = exports.createLogxer = exports.ensureGatewayRequestIdentity = exports.ActivityManager = exports.Activix = exports.mergeTemplateRenderOptions = exports.autoRegisterProviders = exports.InstructionBackendError = exports.InstructionNotFoundError = exports.AIGateway = exports.FallbackExhaustedError = exports.ProviderNotFoundError = exports.createRouterFromConfig = exports.createRouter = exports.LLMProviderRouter = void 0;
+exports.resetObjectTypesLibrary = exports.getObjectTypesLibrary = exports.initializeObjectTypesLibrary = exports.getObjectTypesForAgent = exports.getObjectType = exports.OBJECT_TYPES_LIBRARY = exports.assertValidAIRequest = exports.formatDiagnostic = exports.runValidationTests = exports.createValidationTestCases = exports.createTestAIRequest = exports.supportsJSONMode = exports.diagnoseResponse = exports.diagnoseRequest = exports.validateResponse = exports.extractJSON = exports.validateJSON = exports.validateAIRequest = exports.DEFAULT_RATE_LIMIT_ENABLED = exports.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS = exports.GatewayRateLimiter = exports.runtimeObjects = exports.DebugLogAbstract = exports.createLogxer = exports.gatewayLogDebug = exports.withActivityIdentity = exports.activityIdentityToLogMeta = exports.ensureGatewayRequestIdentity = exports.ActivityManager = exports.Activix = exports.mergeTemplateRenderOptions = exports.autoRegisterProviders = exports.InstructionBackendError = exports.InstructionNotFoundError = exports.AIGateway = exports.FallbackExhaustedError = exports.ProviderNotFoundError = exports.createRouterFromConfig = exports.createRouter = exports.LLMProviderRouter = void 0;
 // Re-export router class and types (base functionality)
 var ai_providers_router_1 = require("@x12i/ai-providers-router");
 Object.defineProperty(exports, "LLMProviderRouter", { enumerable: true, get: function () { return ai_providers_router_1.LLMProviderRouter; } });
@@ -53,9 +53,14 @@ Object.defineProperty(exports, "Activix", { enumerable: true, get: function () {
 var activity_manager_js_1 = require("./activity-manager.cjs");
 Object.defineProperty(exports, "ActivityManager", { enumerable: true, get: function () { return activity_manager_js_1.ActivityManager; } });
 Object.defineProperty(exports, "ensureGatewayRequestIdentity", { enumerable: true, get: function () { return activity_manager_js_1.ensureGatewayRequestIdentity; } });
+var gateway_log_meta_js_1 = require("./gateway-log-meta.cjs");
+Object.defineProperty(exports, "activityIdentityToLogMeta", { enumerable: true, get: function () { return gateway_log_meta_js_1.activityIdentityToLogMeta; } });
+Object.defineProperty(exports, "withActivityIdentity", { enumerable: true, get: function () { return gateway_log_meta_js_1.withActivityIdentity; } });
+Object.defineProperty(exports, "gatewayLogDebug", { enumerable: true, get: function () { return gateway_log_meta_js_1.gatewayLogDebug; } });
 // Re-export logging (@x12i/logxer)
 var logxer_1 = require("@x12i/logxer");
 Object.defineProperty(exports, "createLogxer", { enumerable: true, get: function () { return logxer_1.createLogxer; } });
+Object.defineProperty(exports, "DebugLogAbstract", { enumerable: true, get: function () { return logxer_1.DebugLogAbstract; } });
 // Runtime observability surface (leaf package: no downstream runtime objects)
 var runtime_objects_js_1 = require("./runtime-objects.cjs");
 Object.defineProperty(exports, "runtimeObjects", { enumerable: true, get: function () { return runtime_objects_js_1.runtimeObjects; } });

package/dist-cjs/index.d.ts

@@ -23,8 +23,9 @@ export { Activix } from '@x12i/activix';
 export type { ActivixRunContext, FindByRunContextCriteria } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export type { ActivityIdentity } from './types.js';
-export { createLogxer } from '@x12i/logxer';
-export type { Logxer } from '@x12i/logxer';
+export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';
+export { createLogxer, DebugLogAbstract } from '@x12i/logxer';
+export type { Logxer, LogMeta, RuntimeIdentity } 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/instruction-optimizer.cjs

@@ -111,7 +111,7 @@ If the instructions are already well-written, explain that in the analysis and m
  * @param options - Optimization options
  * @returns Optimization result with fixed instructions and analysis
  */
-async function optimizeInstructions(gateway, originalInstructions, options = {}) {
+async function optimizeInstructions(gateway, originalInstructions, options) {
     // Get internal system action config (instruction optimization)
     const internalConfig = gateway.config?.internalSystemActions?.instructionOptimization;
     const defaultEngine = gateway.config?.defaultEngine || 'openai';
@@ -134,13 +134,20 @@ async function optimizeInstructions(gateway, originalInstructions, options = {})
     if (enforceJsonOutput) {
         additionalContext += '\n\nIMPORTANT: The fixed instructions MUST include strict JSON-only output enforcement rules.';
     }
+    const aiRequestId = `optimize-instructions-${Date.now()}`;
+    const identity = {
+        ...options.identity,
+        aiRequestId,
+        agentId
+    };
     // Create the optimization request - uses gateway.invoke() which goes through router
     // Use internal system action config for temperature and maxTokens if available
     const optimizationRequest = {
-        jobId: `optimize-instructions-${Date.now()}`,
+        aiRequestId,
         agentId,
         instructions: INSTRUCTION_OPTIMIZER_INSTRUCTIONS + additionalContext,
-        input: originalInstructions,
+        identity,
+        workingMemory: { input: originalInstructions },
         config: {
             model,
             provider,

package/dist-cjs/instruction-optimizer.d.ts

@@ -5,6 +5,7 @@
  * This is a meta-feature that uses the AI Gateway (via router) to improve AI instructions.
  */
 import type { AIGateway } from './gateway.js';
+import type { ActivityIdentity } from './types.js';
 /**
  * Result from instruction optimization
  */
@@ -45,6 +46,10 @@ export interface InstructionOptimizationResult {
  * Options for instruction optimization
  */
 export interface OptimizeInstructionsOptions {
+    /**
+     * Runtime identity for this internal `invoke` (same jobId/taskId as the upstream work unit; gateway never invents them).
+     */
+    identity: ActivityIdentity;
     /**
      * Agent ID for the optimization request
      */
@@ -85,7 +90,7 @@ export interface OptimizeInstructionsOptions {
  * @param options - Optimization options
  * @returns Optimization result with fixed instructions and analysis
  */
-export declare function optimizeInstructions(gateway: AIGateway, originalInstructions: string, options?: OptimizeInstructionsOptions): Promise<InstructionOptimizationResult>;
+export declare function optimizeInstructions(gateway: AIGateway, originalInstructions: string, options: OptimizeInstructionsOptions): Promise<InstructionOptimizationResult>;
 /**
  * Utility: Extract only the fixed instructions text
  *

package/dist-cjs/instructions-parser.cjs

@@ -13,7 +13,7 @@ const template_parser_js_1 = require("./template-parser.cjs");
 /**
  * Renders instruction templates with variables using Rendrix (@x12i/rendrix)
  */
-async function renderInstructionTemplate(template, variables = {}, templateRenderOptions) {
+async function renderInstructionTemplate(template, variables = {}, templateRenderOptions, logger) {
     const startTime = Date.now();
     // Extract memory contexts for Rendrix
     // parseTemplate expects: (template, workingMemory, shortTermMemory?, experienceMemory?, knowledgeMemory?)
@@ -24,7 +24,7 @@ async function renderInstructionTemplate(template, variables = {}, templateRende
     // Render template using Rendrix
     // Pass memory contexts as separate parameters, not as a combined object
     const renderedText = await (0, template_parser_js_1.parseTemplate)(template, workingMemory, undefined, // taskConfig removed - no longer used
-    shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+    shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger);
     // Combine all memory contexts for return value (for metadata)
     const combinedVariables = {
         ...variables,

package/dist-cjs/instructions-parser.d.ts

@@ -5,6 +5,7 @@
  * Separated from instruction resolution to keep concerns clean.
  */
 import type { TemplateRenderOptions } from '@x12i/rendrix';
+import type { Logxer } from '@x12i/logxer';
 export interface TemplateVariables {
     workingMemory?: Record<string, any>;
     shortTermMemory?: Record<string, any>;
@@ -20,7 +21,7 @@ export interface RenderedInstruction {
 /**
  * Renders instruction templates with variables using Rendrix (@x12i/rendrix)
  */
-export declare function renderInstructionTemplate(template: string, variables?: TemplateVariables, templateRenderOptions?: TemplateRenderOptions): Promise<RenderedInstruction>;
+export declare function renderInstructionTemplate(template: string, variables?: TemplateVariables, templateRenderOptions?: TemplateRenderOptions, logger?: Logxer): Promise<RenderedInstruction>;
 /**
  * Checks if a template contains variables that need rendering
  */

package/dist-cjs/logger-factory.cjs

@@ -7,6 +7,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createGatewayLogger = createGatewayLogger;
 const logxer_1 = require("@x12i/logxer");
+function resolveDefaultRuntimeIdentity(packageName) {
+    const service = process.env.AI_GATEWAY_LOG_SERVICE ?? packageName ?? 'AI_GATEWAY';
+    if (!service)
+        return undefined;
+    return {
+        service,
+        env: process.env.NODE_ENV,
+        version: process.env.npm_package_version
+    };
+}
 /**
  * Creates a logger instance based on configuration
  *
@@ -26,7 +36,8 @@ function createGatewayLogger(config) {
         debugNamespace: 'ai-gateway'
     }, {
         logLevel: 'info',
-        logFormat: 'json'
+        logFormat: 'json',
+        runtimeIdentity: resolveDefaultRuntimeIdentity(config.packageName)
     });
 }
 function createNoOpLogger() {

package/dist-cjs/message-builder.cjs

@@ -188,7 +188,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
             message: 'Input data must be provided via workingMemory.input for template rendering'
         };
         logger.error('Input field provided but has been removed', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             agentId: request.agentId,
             errorCode: 'INPUT_FIELD_DEPRECATED',
             hasPrompt: !!request.prompt,
@@ -210,7 +210,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
             hasInputInWorkingMemory: !!request.workingMemory?.input
         };
         logger.error('Prompt is required for AI requests', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             agentId: request.agentId,
             errorCode: 'PROMPT_REQUIRED'
         });
@@ -220,7 +220,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
     if (request.prompt) {
         if (typeof request.prompt === 'string') {
             logger.info('Parsing prompt template text', {
-                jobId: request.jobId,
+                jobId: request.identity.jobId,
                 agentId: request.agentId,
                 promptLength: request.prompt.length,
                 promptPreview: request.prompt.substring(0, 200),
@@ -232,13 +232,13 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
                     err.code = 'WORKING_MEMORY_REQUIRED';
                     err.details = { requiresVariables: true };
                     logger.error('workingMemory required for prompt template rendering', {
-                        jobId: request.jobId,
+                        jobId: request.identity.jobId,
                         agentId: request.agentId,
                         errorCode: 'WORKING_MEMORY_REQUIRED'
                     });
                     throw err;
                 }
-                const parsedPrompt = await (0, template_parser_js_1.parseTemplate)(request.prompt, request.workingMemory, undefined, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+                const parsedPrompt = await (0, template_parser_js_1.parseTemplate)(request.prompt, request.workingMemory, undefined, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger);
                 if (!parsedPrompt || parsedPrompt.trim() === '') {
                     const workingMemoryObj = request.workingMemory;
                     const err = new Error(`Prompt template rendered to empty string. This may indicate missing template variables or empty template content.`);
@@ -250,7 +250,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
                         workingMemoryKeys: workingMemoryObj ? Object.keys(workingMemoryObj) : []
                     };
                     logger.error('Prompt template rendered to empty string', {
-                        jobId: request.jobId,
+                        jobId: request.identity.jobId,
                         agentId: request.agentId,
                         errorCode: 'PROMPT_RENDERED_EMPTY',
                         hasWorkingMemory: !!request.workingMemory,
@@ -259,7 +259,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
                     throw err;
                 }
                 logger.info('Prompt text parsed successfully', {
-                    jobId: request.jobId,
+                    jobId: request.identity.jobId,
                     agentId: request.agentId,
                     originalLength: request.prompt.length,
                     parsedLength: parsedPrompt.length,
@@ -288,7 +288,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
                     errorMessage = err.message;
                 }
                 logger.error('Failed to render prompt template', {
-                    jobId: request.jobId,
+                    jobId: request.identity.jobId,
                     agentId: request.agentId,
                     errorCode,
                     error: err.message,
@@ -307,7 +307,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
         else {
             const err = new Error(`Prompt must be a string template, but received: ${typeof request.prompt}`);
             logger.error('Prompt provided as non-string - not supported', {
-                jobId: request.jobId,
+                jobId: request.identity.jobId,
                 agentId: request.agentId,
                 promptType: typeof request.prompt
             });
@@ -329,7 +329,7 @@ async function buildUserMessage(request, config, shortTermMemory, experienceMemo
             partsLength: parts.length
         };
         logger.error('Prompt provided but resulted in empty user message', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             agentId: request.agentId,
             prompt: request.prompt,
             errorCode: 'PROMPT_NO_USER_MESSAGE',
@@ -419,7 +419,7 @@ async function buildMessages(request, config, options = {}) {
     if (request.instructions) {
         if (typeof request.instructions === 'string') {
             logger.info('Using instructions as template text', {
-                jobId: request.jobId,
+                jobId: request.identity.jobId,
                 agentId: request.agentId,
                 instructionsLength: request.instructions.length,
                 instructionsPreview: request.instructions.substring(0, 200)
@@ -437,7 +437,7 @@ async function buildMessages(request, config, options = {}) {
     // Rendrix handles token resolution, so we just parse directly
     if (instructionsText) {
         instructionsText = await (0, template_parser_js_1.parseTemplate)(instructionsText, request.workingMemory, undefined, // taskConfig removed - no longer used
-        shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+        shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger);
     }
     // Step 4: Add input recognition rules
     const inputRules = await buildInputRecognitionRules(request, config, options);
@@ -454,7 +454,7 @@ async function buildMessages(request, config, options = {}) {
     if (!instructionsText || instructionsText.trim() === '') {
         const errorMessage = 'No instructions available - cannot proceed without clear instructions. This is a bad request.';
         logger.error(errorMessage, {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             agentId: request.agentId,
             hasRequestInstructions: !!request.instructions,
             instructionType: typeof request.instructions,
@@ -473,7 +473,7 @@ async function buildMessages(request, config, options = {}) {
     }
     // Log the final system message for verification
     logger.info('Final system message constructed', {
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         agentId: request.agentId,
         messageLength: instructionsText.length,
         hasMarkdown: instructionsText.toLowerCase().includes('markdown'),
@@ -486,7 +486,7 @@ async function buildMessages(request, config, options = {}) {
     if (request.context) {
         const contextText = typeof request.context === 'string' ? request.context : JSON.stringify(request.context);
         const parsedContext = await (0, template_parser_js_1.parseTemplate)(contextText, request.workingMemory, undefined, // taskConfig removed - no longer used
-        shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+        shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger);
         if (parsedContext && parsedContext.trim() !== '') {
             messages.push({
                 role: 'assistant',
@@ -507,7 +507,7 @@ async function buildMessages(request, config, options = {}) {
         }
         // Log the user message for verification
         logger.info('Final user message constructed', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             agentId: request.agentId,
             messageLength: userMessage.length,
             messagePreview: userMessage.substring(0, 200),
@@ -524,7 +524,7 @@ async function buildMessages(request, config, options = {}) {
                 hasWorkingMemory: !!request.workingMemory
             };
             logger.error('Prompt provided but no user message created', {
-                jobId: request.jobId,
+                jobId: request.identity.jobId,
                 agentId: request.agentId,
                 prompt: request.prompt,
                 errorCode: 'PROMPT_NO_USER_MESSAGE'
@@ -533,14 +533,14 @@ async function buildMessages(request, config, options = {}) {
         }
         // If no prompt was provided, it's just a warning (input-only requests are valid)
         logger.warn('No user message to add', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             agentId: request.agentId,
             hasPrompt: !!request.prompt
         });
     }
     // Log complete message structure
     logger.info('Complete message structure', {
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         agentId: request.agentId,
         totalMessages: messages.length,
         systemMessages: messages.filter(m => m.role === 'system').length,

package/dist-cjs/request-report-generator.cjs

@@ -151,7 +151,7 @@ function schemasMatch(schema1, schema2) {
 async function generateRequestReport(request, library, // ObjectTypesLibrary removed
 logger) {
     const report = {
-        requestId: request.jobId || `req-${Date.now()}`,
+        requestId: request.identity.jobId || request.aiRequestId,
         timestamp: Date.now(),
         validation: {},
         examples: { count: 0 },

package/dist-cjs/template-parser.cjs

@@ -72,10 +72,11 @@ async function loadRendrix() {
  * @param experienceMemory - Experience memory for learned knowledge (optional)
  * @param knowledgeMemory - Knowledge memory for reference data (optional)
  * @param templateRenderOptions - Passed to Rendrix `render` (v4+): templateId, subPathSearch, silentMissingMustTokens
+ * @param logger - Optional Logxer for non-fatal parse failures (replaces console).
  * @returns Parsed template string
  * @throws {Error} When the parser throws TemplateResolutionError (v4 MUST path missing after merge)
  */
-async function parseTemplate(template, workingMemory, taskConfig, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions) {
+async function parseTemplate(template, workingMemory, taskConfig, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions, logger) {
     // If no template or empty, return as-is
     if (!template || typeof template !== 'string') {
         return template || '';
@@ -116,7 +117,7 @@ async function parseTemplate(template, workingMemory, taskConfig, shortTermMemor
             throw error;
         }
         const err = error instanceof Error ? error : new Error(String(error));
-        console.warn('Template parsing failed, using template as-is:', {
+        logger?.warn('Template parsing failed, using template as-is', {
             error: err.message,
             templateLength: template.length,
             hasWorkingMemory: !!workingMemory,

package/dist-cjs/template-parser.d.ts

@@ -5,6 +5,7 @@
  * TemplateResolutionError from the parser is rethrown; other errors fall back to the raw template.
  */
 import type { TemplateRenderOptions } from '@x12i/rendrix';
+import type { Logxer } from '@x12i/logxer';
 /**
  * Task configuration type for template rendering
  * @deprecated taskConfig is no longer used by Rendrix 3.0.0+
@@ -48,10 +49,11 @@ export interface KnowledgeMemory {
  * @param experienceMemory - Experience memory for learned knowledge (optional)
  * @param knowledgeMemory - Knowledge memory for reference data (optional)
  * @param templateRenderOptions - Passed to Rendrix `render` (v4+): templateId, subPathSearch, silentMissingMustTokens
+ * @param logger - Optional Logxer for non-fatal parse failures (replaces console).
  * @returns Parsed template string
  * @throws {Error} When the parser throws TemplateResolutionError (v4 MUST path missing after merge)
  */
-export declare function parseTemplate(template: string, workingMemory?: unknown, taskConfig?: TaskConfig, shortTermMemory?: ShortTermMemory, experienceMemory?: ExperienceMemory, knowledgeMemory?: KnowledgeMemory, templateRenderOptions?: TemplateRenderOptions): Promise<string>;
+export declare function parseTemplate(template: string, workingMemory?: unknown, taskConfig?: TaskConfig, shortTermMemory?: ShortTermMemory, experienceMemory?: ExperienceMemory, knowledgeMemory?: KnowledgeMemory, templateRenderOptions?: TemplateRenderOptions, logger?: Logxer): Promise<string>;
 /**
  * Checks if Rendrix (@x12i/rendrix) is available
  */