@x12i/ai-gateway 7.9.2 → 9.0.0

package/dist/gateway.js

@@ -5,12 +5,13 @@
  */
 import { validateChatRequest, validateAIRequest } from './gateway-validation.js';
 import { ensureGatewayRequestIdentity } from './activity-manager.js';
-import { initializeGatewayComponents, loadConfig } from './gateway-config.js';
+import { initializeGatewayComponents } from './gateway-config.js';
 import { buildMessages } from './message-builder.js';
 import { extractJsonFromFlexMd } from './flex-md-loader.js';
 import { mergeConfig } from './gateway-utils.js';
 import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.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';
 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).';
@@ -27,9 +28,7 @@ export class AIGateway {
     constructor(config = {}, activityManager) {
         this.config = config;
         this.activityManager = activityManager;
-        // Load configuration and initialize components
-        const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig();
-        const components = initializeGatewayComponents(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering);
+        const components = initializeGatewayComponents(config);
         this.logger = components.logger;
         this.router = components.router;
         this.activityManager = components.activityManager;
@@ -50,9 +49,7 @@ export class AIGateway {
         const startTime = Date.now();
         // Basic validation
         validateChatRequest(request);
-        if (!this.activityManager) {
-            ensureGatewayRequestIdentity(request);
-        }
+        ensureGatewayRequestIdentity(request, undefined, this.logger);
         setGatewayLastJobId(resolveRuntimeJobId(request));
         // Generate simple task type ID
         const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
@@ -135,9 +132,7 @@ export class AIGateway {
         const startTime = Date.now();
         // Basic validation
         validateAIRequest(request);
-        if (!this.activityManager) {
-            ensureGatewayRequestIdentity(request);
-        }
+        ensureGatewayRequestIdentity(request, undefined, this.logger);
         setGatewayLastJobId(resolveRuntimeJobId(request));
         // Generate simple task type ID
         const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
@@ -252,48 +247,48 @@ export 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', withActivityIdentity(request.identity, {
                     contentLength: content.length,
-                    hasInstructions: !!resolvedRequest.instructions
-                });
+                    hasInstructions: !!resolvedRequest.instructions,
+                    debugKind: gatewayLogDebug.intent
+                }));
                 // Let flex-md extract structured data from the response content
-                const extractionResult = await extractJsonFromFlexMd(content);
-                this.logger.debug('Flex-md extraction result', {
-                    aiRequestId: request.aiRequestId,
+                const extractionResult = await extractJsonFromFlexMd(content, this.logger);
+                this.logger.debug('Flex-md extraction result', 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: 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', withActivityIdentity(request.identity, {
                         method: extractionResult.method,
-                        extractedKeys: Object.keys(extractionResult.json)
-                    });
+                        extractedKeys: Object.keys(extractionResult.json),
+                        debugKind: 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', withActivityIdentity(request.identity, {
                         hasResult: !!extractionResult,
-                        method: extractionResult?.method || 'none'
-                    });
+                        method: extractionResult?.method || 'none',
+                        debugKind: 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', 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: gatewayLogDebug.anomaly
+                }));
                 parsedContent = { rawText: content };
             }
             contentType = 'structured';
@@ -358,7 +353,11 @@ export class AIGateway {
                     });
                 }
             }
-            console.debug('gateway: enhancedResponse:', enhancedResponse);
+            this.logger.debug('gateway: enhancedResponse', withActivityIdentity(request.identity, {
+                latencyMs: enhancedResponse.metadata?.latencyMs,
+                contentType: enhancedResponse.metadata?.contentType,
+                debugKind: gatewayLogDebug.state
+            }));
             return enhancedResponse;
         }
         catch (error) {
@@ -426,5 +425,5 @@ export class 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/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/index.js

@@ -23,8 +23,9 @@ export { mergeTemplateRenderOptions } from './template-render-merge.js';
 // Re-export activity tracking primitives (Activix)
 export { Activix } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
+export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';
 // Re-export logging (@x12i/logxer)
-export { createLogxer } from '@x12i/logxer';
+export { createLogxer, DebugLogAbstract } from '@x12i/logxer';
 // Runtime observability surface (leaf package: no downstream runtime objects)
 export { runtimeObjects } from './runtime-objects.js';
 // Export rate limiter

package/dist/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/instruction-optimizer.js

@@ -105,7 +105,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
  */
-export async function optimizeInstructions(gateway, originalInstructions, options = {}) {
+export 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';
@@ -128,13 +128,20 @@ export async function optimizeInstructions(gateway, originalInstructions, option
     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/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/instructions-parser.js

@@ -8,7 +8,7 @@ import { parseTemplate } from './template-parser.js';
 /**
  * Renders instruction templates with variables using Rendrix (@x12i/rendrix)
  */
-export async function renderInstructionTemplate(template, variables = {}, templateRenderOptions) {
+export async function renderInstructionTemplate(template, variables = {}, templateRenderOptions, logger) {
     const startTime = Date.now();
     // Extract memory contexts for Rendrix
     // parseTemplate expects: (template, workingMemory, shortTermMemory?, experienceMemory?, knowledgeMemory?)
@@ -19,7 +19,7 @@ export async function renderInstructionTemplate(template, variables = {}, templa
     // Render template using Rendrix
     // Pass memory contexts as separate parameters, not as a combined object
     const renderedText = await 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/logger-factory.js

@@ -4,6 +4,16 @@
  * Creates and configures logxer instances for the gateway
  */
 import { createLogxer } from '@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
  *
@@ -23,7 +33,8 @@ export function createGatewayLogger(config) {
         debugNamespace: 'ai-gateway'
     }, {
         logLevel: 'info',
-        logFormat: 'json'
+        logFormat: 'json',
+        runtimeIdentity: resolveDefaultRuntimeIdentity(config.packageName)
     });
 }
 function createNoOpLogger() {

package/dist/message-builder.js

@@ -152,7 +152,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,
@@ -174,7 +174,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'
         });
@@ -184,7 +184,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),
@@ -196,13 +196,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 parseTemplate(request.prompt, request.workingMemory, undefined, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+                const parsedPrompt = await 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.`);
@@ -214,7 +214,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,
@@ -223,7 +223,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,
@@ -252,7 +252,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,
@@ -271,7 +271,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
             });
@@ -293,7 +293,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',
@@ -383,7 +383,7 @@ export 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)
@@ -401,7 +401,7 @@ export async function buildMessages(request, config, options = {}) {
     // Rendrix handles token resolution, so we just parse directly
     if (instructionsText) {
         instructionsText = await 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);
@@ -418,7 +418,7 @@ export 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,
@@ -437,7 +437,7 @@ export 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'),
@@ -450,7 +450,7 @@ export async function buildMessages(request, config, options = {}) {
     if (request.context) {
         const contextText = typeof request.context === 'string' ? request.context : JSON.stringify(request.context);
         const parsedContext = await 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',
@@ -471,7 +471,7 @@ export 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),
@@ -488,7 +488,7 @@ export 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'
@@ -497,14 +497,14 @@ export 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/request-report-generator.js

@@ -148,7 +148,7 @@ function schemasMatch(schema1, schema2) {
 export 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/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
  */

package/dist/template-parser.js

@@ -35,10 +35,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)
  */
-export async function parseTemplate(template, workingMemory, taskConfig, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions) {
+export 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 || '';
@@ -79,7 +80,7 @@ export async function parseTemplate(template, workingMemory, taskConfig, shortTe
             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/troubleshooting-helper.d.ts

@@ -120,4 +120,4 @@ export declare function formatDiagnostic(diagnostic: DiagnosticInfo): string;
 /**
  * Quick validation helper - throws if invalid
  */
-export declare function assertValidAIRequest(request: Partial<AIRequest>): void;
+export declare function assertValidAIRequest(request: Partial<AIRequest>, logger?: import('@x12i/logxer').Logxer): void;

package/dist/troubleshooting-helper.js

@@ -585,12 +585,12 @@ export function formatDiagnostic(diagnostic) {
 /**
  * Quick validation helper - throws if invalid
  */
-export function assertValidAIRequest(request) {
+export function assertValidAIRequest(request, logger) {
     const validation = validateAIRequest(request);
     if (!validation.valid) {
         throw new Error(`AIRequest validation failed:\n${validation.errors.join('\n')}`);
     }
     if (validation.warnings.length > 0) {
-        console.warn('AIRequest validation warnings:', validation.warnings);
+        logger?.warn('AIRequest validation warnings', { warnings: validation.warnings });
     }
 }

package/dist/types.d.ts

@@ -32,11 +32,18 @@ export type ActivityIdentity = {
     };
     /** Gateway-level request correlation ID. */
     aiRequestId: string;
-    /** @deprecated Use aiRequestId. Kept only for backward compatibility. */
-    jobId?: string;
+    /**
+     * Upstream job identifier — must be supplied on `request.identity` only.
+     * The gateway copies this value as-is; it never generates or mutates it.
+     */
+    jobId: string;
     jobTypeId?: string;
     agentId: string;
-    taskId?: string;
+    /**
+     * Upstream task identifier — must be supplied on `request.identity` only.
+     * The gateway copies this value as-is; it never generates or mutates it.
+     */
+    taskId: string;
     taskTypeId?: string;
     /** Graph/node linkage (optional, used by activity identity grouping). */
     graphId?: string;
@@ -413,7 +420,7 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
  * Extends LLMRequest but omits 'messages' and 'input' to allow custom message handling
  * and make input optional (router may require it, but gateway allows it to be optional)
  */
-interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input'> {
+interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'request' | 'mode'> {
     /**
      * AI request ID - Required for all invocations and activity tracking
      */
@@ -422,15 +429,14 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input'> {
     jobId?: string;
     /**
      * Optional top-level run/session id for Activix. Prefer `identity.sessionId`; if both are set they must match.
-     * When omitted, `ActivityManager` resolves session from `identity.sessionId`, then `jobId`, then `aiRequestId`.
+     * When omitted, `ActivityManager` resolves session from `identity.sessionId`, then `identity.jobId`, then `aiRequestId`.
      */
     sessionId?: string;
     /**
-     * Optional identity object used for upstream linkage (forwarded through the request).
-     * May be partial; may include product-specific keys beyond `ActivityIdentity`. When omitted,
-     * the gateway normalizes and attaches a full envelope (`ensureGatewayRequestIdentity` / activity tracking).
+     * Mandatory runtime identity from the upstream client (job/task correlation, Activix `runContext`).
+     * Must include at least `jobId` and `taskId` as non-empty strings; the gateway never invents these.
      */
-    identity?: ActivityIdentity & Record<string, unknown>;
+    identity: ActivityIdentity & Record<string, unknown>;
     /**
      * Job type ID (optional) - Short ID or hash to identify recurring job types
      * Best practice: Use MD5 hash of the job type string for consistent job identification
@@ -459,7 +465,7 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input'> {
      */
     instructions: string;
     /**
-     * Task ID (optional)
+     * @deprecated Prefer `identity.taskId`. The gateway does not copy this into `identity`.
      */
     taskId?: string;
     /**