@x12i/ai-gateway 7.9.2 → 9.0.1

package/dist/content-normalizer/content-normalizer.d.ts

@@ -6,6 +6,7 @@
  * Preserves both rawText and parsedContent for downstream consumers.
  */
 import type { LLMResponse } from '../types.js';
+import type { Logxer } from '@x12i/logxer';
 import type { NormalizedContent } from './types.js';
 /**
  * Normalizes content from router response
@@ -20,7 +21,7 @@ import type { NormalizedContent } from './types.js';
  * @param response - Router response object
  * @returns Normalized content with metadata
  */
-export declare function normalizeContent(response: LLMResponse): NormalizedContent;
+export declare function normalizeContent(response: LLMResponse, logger?: Logxer): NormalizedContent;
 /**
  * Checks if content is empty
  *

package/dist/content-normalizer/content-normalizer.js

@@ -182,14 +182,14 @@ function determineContentType(value, parsedContent) {
  * @param response - Router response object
  * @returns Normalized content with metadata
  */
-export function normalizeContent(response) {
+export function normalizeContent(response, logger) {
     // Extract content value from response
     const contentValue = extractContentValue(response);
     // CRITICAL: Check if router already converted object to "[object Object]" string
     // This happens when router uses String() on objects before returning
     if (typeof contentValue === 'string' && contentValue === '[object Object]') {
         // Router already broke it - try to recover from other fields
-        console.error('[content-normalizer] Router returned "[object Object]" string - attempting recovery', {
+        logger?.error('[content-normalizer] Router returned "[object Object]" string - attempting recovery', {
             responseKeys: Object.keys(response),
             hasOutput: !!response.output,
             hasRawText: !!response.rawText,
@@ -230,7 +230,7 @@ export function normalizeContent(response) {
             };
         }
         // If we can't recover, log error and return empty
-        console.error('[content-normalizer] Cannot recover from "[object Object]" - no valid object found in response');
+        logger?.error('[content-normalizer] Cannot recover from "[object Object]" - no valid object found in response');
         return {
             content: '',
             rawText: undefined,
@@ -319,7 +319,7 @@ export function normalizeContent(response) {
                 // Last resort: use String() but this should never happen
                 normalizedString = String(contentValue);
                 // This will be "[object Object]" but we've exhausted all options
-                console.error('[content-normalizer] Failed to stringify object and no rawText available', {
+                logger?.error('[content-normalizer] Failed to stringify object and no rawText available', {
                     error,
                     contentValueType: typeof contentValue,
                     isArray: Array.isArray(contentValue)
@@ -342,7 +342,7 @@ export function normalizeContent(response) {
             }
             catch {
                 // If this also fails, we're stuck with "[object Object]"
-                console.error('[content-normalizer] Cannot recover from "[object Object]" - all recovery attempts failed');
+                logger?.error('[content-normalizer] Cannot recover from "[object Object]" - all recovery attempts failed');
             }
         }
     }

package/dist/flex-md-loader.d.ts

@@ -13,6 +13,7 @@
  * - Native output format support: Extracts and uses flex-md native output formats from instructions
  *   based on compliance level when no explicit format is provided
  */
+import { type Logxer } from '@x12i/logxer';
 /**
  * Load flex-md module (ES Module) asynchronously
  * Caches the result to avoid multiple imports
@@ -38,7 +39,7 @@ export declare function loadFlexMd(): Promise<any>;
  *   - Other flex-md options
  * @returns Parsed JSON object and method used, or null if parsing fails
  */
-export declare function extractJsonFromFlexMd(content: string): Promise<{
+export declare function extractJsonFromFlexMd(content: string, logger?: Logxer): Promise<{
     json: any;
     method: string;
 } | null>;

package/dist/flex-md-loader.js

@@ -15,6 +15,7 @@
  */
 import * as path from 'path';
 import { pathToFileURL } from 'url';
+import { DebugLogAbstract } from '@x12i/logxer';
 let flexMdModule = null;
 let flexMdLoadError = null;
 let flexMdLoading = null;
@@ -328,7 +329,7 @@ async function extractFlexMdOutputFormatFromInstructions(instructions, complianc
  *   - Other flex-md options
  * @returns Parsed JSON object and method used, or null if parsing fails
  */
-export async function extractJsonFromFlexMd(content) {
+export async function extractJsonFromFlexMd(content, logger) {
     // ARCHITECTURE: ai-gateway layer only handles unstructured parsing
     // Schema-driven parsing is handled at skills layer with nx-md-parser
     // No schema parameter - this layer doesn't know about schemas
@@ -346,8 +347,9 @@ export async function extractJsonFromFlexMd(content) {
                 }
             }
             catch (error) {
-                // markdownToJson failed, continue to other methods
-                console.warn('markdownToJson failed:', error instanceof Error ? error.message : String(error));
+                logger?.warn('markdownToJson failed', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
             }
         }
         // Secondary approach: Use extractFromMarkdown for low-level section extraction
@@ -357,15 +359,16 @@ export async function extractJsonFromFlexMd(content) {
                 if (result && typeof result === 'object' && result !== null) {
                     const json = result.json || result.data || result.result || result;
                     if (json && typeof json === 'object' && json !== null) {
-                        console.debug('extractJsonFromFlexMd: using extractFromMarkdown');
-                        console.debug('extractJsonFromFlexMd: json:', json);
+                        logger?.debug('extractJsonFromFlexMd: using extractFromMarkdown', { debugKind: DebugLogAbstract.TRACE });
+                        logger?.debug('extractJsonFromFlexMd: parsed json', { json, debugKind: DebugLogAbstract.STATE });
                         return { json, method: 'extractFromMarkdown' };
                     }
                 }
             }
             catch (error) {
-                // extractFromMarkdown failed, continue
-                console.warn('extractFromMarkdown failed:', error instanceof Error ? error.message : String(error));
+                logger?.warn('extractFromMarkdown failed', {
+                    error: error instanceof Error ? error.message : String(error)
+                });
             }
         }
     }
@@ -373,13 +376,14 @@ export async function extractJsonFromFlexMd(content) {
         // flex-md loading failed, log once and continue to fallback.
         if (!hasLoggedFlexMdLoadWarning) {
             hasLoggedFlexMdLoadWarning = true;
-            console.warn('extractJsonFromFlexMd: flex-md library failed to load, using markdown parser fallback:', error instanceof Error ? error.message : String(error));
+            logger?.warn('extractJsonFromFlexMd: flex-md library failed to load, using markdown parser fallback', {
+                error: error instanceof Error ? error.message : String(error)
+            });
         }
     }
-    console.debug('extractJsonFromFlexMd: using markdown parser fallback');
-    console.debug('extractJsonFromFlexMd: content:', content);
+    logger?.debug('extractJsonFromFlexMd: using markdown parser fallback', { contentLength: content.length });
     // Final fallback: Parse markdown sections
-    return fallbackMarkdownParser(content);
+    return fallbackMarkdownParser(content, logger);
 }
 /**
  * Helper function to detect and parse markdown lists into arrays
@@ -437,7 +441,7 @@ function parseMarkdownList(content) {
 /**
  * Simple markdown parser for unstructured content (fallback when flex-md unavailable)
  */
-function fallbackMarkdownParser(content) {
+function fallbackMarkdownParser(content, logger) {
     const result = {};
     const detectedHeaders = [];
     // Simple section extraction based on markdown headers
@@ -480,12 +484,11 @@ function fallbackMarkdownParser(content) {
         result[key] = parseMarkdownList(currentContent);
         detectedHeaders.push(key);
     }
-    // Debug logging for incomplete parsing
-    console.log('Fallback parser detected headers:', detectedHeaders);
+    logger?.debug('Fallback parser detected headers', { detectedHeaders, debugKind: DebugLogAbstract.STATE });
     const expectedHeaders = ['shortAnswer', 'fullAnswer', 'assumptions', 'unknowns', 'evidence'];
     const missingHeaders = expectedHeaders.filter(h => !detectedHeaders.includes(h));
     if (missingHeaders.length > 0) {
-        console.log('Fallback parser missing expected headers:', missingHeaders);
+        logger?.debug('Fallback parser missing expected headers', { missingHeaders, debugKind: DebugLogAbstract.STATE });
     }
     // If we extracted some structure, return it
     if (Object.keys(result).length > 0) {

package/dist/gateway-config.d.ts

@@ -20,10 +20,10 @@ export interface GatewayConfigContext {
     messageBuilderConfig: MessageBuilderConfig;
 }
 /**
- * Loads configuration from JSON files (model config and instructionsBlocks)
- * Note: Called before logger is initialized, so no logging here
+ * Loads configuration from JSON files (model config and instructionsBlocks).
+ * Pass a {@link Logxer} instance so load diagnostics go through logxer (not console).
  */
-export declare function loadConfig(): {
+export declare function loadConfig(logger: Logxer): {
     defaultModelConfig: Record<string, unknown>;
     defaultInstructionsBlocks: Record<string, any>;
     defaultTemplateRendering?: TemplateRenderOptions;
@@ -40,7 +40,7 @@ export declare function setupRequestInterceptor(router: LLMProviderRouter, logge
 /**
  * Initializes gateway components
  */
-export declare function initializeGatewayComponents(config: GatewayConfig, defaultModelConfig: Record<string, unknown>, defaultInstructionsBlocks: Record<string, any>, defaultTemplateRendering?: TemplateRenderOptions): {
+export declare function initializeGatewayComponents(config: GatewayConfig): {
     logger: Logxer;
     router: LLMProviderRouter;
     activityManager: ActivityManager;

package/dist/gateway-config.js

@@ -53,10 +53,10 @@ import { mergeTemplateRenderOptions } from './template-render-merge.js';
 import { GatewayRateLimiter } from './gateway-rate-limiter.js';
 import { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, DEFAULT_RATE_LIMIT_ENABLED } from './gateway-rate-limiter-constants.js';
 /**
- * Loads configuration from JSON files (model config and instructionsBlocks)
- * Note: Called before logger is initialized, so no logging here
+ * Loads configuration from JSON files (model config and instructionsBlocks).
+ * Pass a {@link Logxer} instance so load diagnostics go through logxer (not console).
  */
-export function loadConfig() {
+export function loadConfig(logger) {
     const defaultModelConfig = {};
     const defaultInstructionsBlocks = {};
     let defaultTemplateRendering;
@@ -81,26 +81,22 @@ export function loadConfig() {
             const parsed = JSON.parse(content);
             // Use Object.assign to merge, preserving nested structure
             Object.assign(defaultInstructionsBlocks, parsed);
-            // Debug: Log what was loaded (only in development)
-            if (process.env.NODE_ENV !== 'production') {
-                console.log('Loaded instructions blocks:', {
-                    topLevelKeys: Object.keys(defaultInstructionsBlocks),
-                    hasOutput: 'output' in defaultInstructionsBlocks,
-                    outputKeys: 'output' in defaultInstructionsBlocks ? Object.keys(defaultInstructionsBlocks.output) : []
-                });
-            }
+            logger.debug('Loaded instructions blocks from defaults', {
+                topLevelKeys: Object.keys(defaultInstructionsBlocks),
+                hasOutput: 'output' in defaultInstructionsBlocks,
+                outputKeys: 'output' in defaultInstructionsBlocks ? Object.keys(defaultInstructionsBlocks.output) : []
+            });
         }
         else {
-            // Optional file: fallback defaults below still keep the gateway functional.
-            if (process.env.NODE_ENV !== 'production') {
-                console.debug('Optional instructions blocks file not found at:', instructionsBlocksPath);
-            }
+            logger.verbose('Optional instructions blocks file not found; using packaged fallbacks', {
+                instructionsBlocksPath
+            });
         }
     }
     catch (error) {
-        // Can't log here as logger isn't initialized yet
-        // Error will be logged after logger initialization in constructor
-        console.warn('Failed to load defaults from JSON files:', error);
+        logger.warn('Failed to load defaults from JSON files', {
+            error: error instanceof Error ? error.message : String(error)
+        });
     }
     // Ensure critical blocks exist even if file loading failed
     if (!defaultInstructionsBlocks['outputObjectPrefix']) {
@@ -128,10 +124,10 @@ export function getFlexMdMinComplianceLevel() {
 export function setupRequestInterceptor(router, logger) {
     logger.debug('Setting up request interceptor for jobId propagation and config cleanup');
     router.addRequestInterceptor(async (request, provider) => {
-        // Propagate jobId to request metadata
-        if (request.jobId) {
-            logger.verbose('Propagating jobId to request metadata', {
-                jobId: request.jobId,
+        const identityJobId = request?.identity?.jobId;
+        if (typeof identityJobId === 'string' && identityJobId.trim().length > 0) {
+            logger.verbose('Propagating identity.jobId to request metadata', {
+                jobId: identityJobId,
                 provider: provider?.getProviderName?.() || 'unknown'
             });
             if (!request.config) {
@@ -140,7 +136,7 @@ export function setupRequestInterceptor(router, logger) {
             if (!request.config.metadata) {
                 request.config.metadata = {};
             }
-            request.config.metadata.jobId = request.jobId;
+            request.config.metadata.jobId = identityJobId;
         }
         // Remove 'provider' from config - router uses it for routing but providers don't accept it
         // Router reads config.provider to determine which provider to call, but then passes
@@ -159,14 +155,14 @@ export function setupRequestInterceptor(router, logger) {
 /**
  * Initializes gateway components
  */
-export function initializeGatewayComponents(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering) {
+export function initializeGatewayComponents(config) {
     // Initialize logger FIRST (before other components that might need it)
     const logger = createGatewayLogger({
         enableLogging: config.enableLogging ?? true,
         packageName: config.packageName,
         customLogger: config.logger
     });
-    // Now that logger is initialized, log the defaults loading
+    const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig(logger);
     logger.verbose('Gateway initializing', {
         defaultEngine: config.defaultEngine,
         hasDefaultInstructionsBlocks: Object.keys(defaultInstructionsBlocks).length > 0

package/dist/gateway-conversion.js

@@ -39,7 +39,7 @@ export async function invokeStructuredText(request, gateway) {
     // Create a new request with structured-text mode
     const structuredRequest = {
         ...request,
-        jobId: `${request.jobId}-step1`
+        identity: { ...request.identity }
     };
     // Make the call (this will recursively call invoke, but with structured-text mode)
     return await gateway.invoke(structuredRequest);
@@ -81,7 +81,7 @@ export async function convertStructuredToJson(structuredText, originalRequest, c
     });
     try {
         // Use flex-md 3.0.0 to extract and parse JSON
-        const flexMdResult = await extractJsonFromFlexMd(structuredText);
+        const flexMdResult = await extractJsonFromFlexMd(structuredText, logger);
         if (!flexMdResult || !flexMdResult.json) {
             throw new Error('flex-md SDK could not extract JSON from structured text');
         }

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

@@ -0,0 +1,15 @@
+/**
+ * Maps gateway {@link ActivityIdentity} into Logxer {@link LogMeta} fields for correlation and querying.
+ */
+import type { LogMeta } from '@x12i/logxer';
+import type { ActivityIdentity } from './types.js';
+/** Subset of identity forwarded on every structured log line (plus full envelope under `identity`). */
+export declare function activityIdentityToLogMeta(identity: Partial<ActivityIdentity> | undefined): LogMeta;
+export declare function withActivityIdentity(identity: Partial<ActivityIdentity> | undefined, data?: LogMeta, debugKind?: LogMeta['debugKind']): LogMeta;
+export declare const gatewayLogDebug: {
+    readonly anomaly: "ANOMALY";
+    readonly trace: "TRACE";
+    readonly intent: "INTENT";
+    readonly event: "EVENT";
+    readonly state: "STATE";
+};

package/dist/gateway-log-meta.js

@@ -0,0 +1,36 @@
+import { DebugLogAbstract } from '@x12i/logxer';
+/** Subset of identity forwarded on every structured log line (plus full envelope under `identity`). */
+export function activityIdentityToLogMeta(identity) {
+    if (!identity) {
+        return {};
+    }
+    const meta = {
+        identity: JSON.stringify({
+            sessionId: identity.sessionId,
+            aiRequestId: identity.aiRequestId,
+            jobId: identity.jobId,
+            taskId: identity.taskId,
+            agentId: identity.agentId
+        }),
+        jobId: identity.jobId,
+        sessionId: identity.sessionId,
+        correlationId: identity.aiRequestId,
+        taskId: identity.taskId,
+        activityIdentity: identity
+    };
+    return meta;
+}
+export function withActivityIdentity(identity, data, debugKind) {
+    return {
+        ...activityIdentityToLogMeta(identity),
+        ...(data || {}),
+        ...(debugKind !== undefined ? { debugKind } : {})
+    };
+}
+export const gatewayLogDebug = {
+    anomaly: DebugLogAbstract.ANOMALY,
+    trace: DebugLogAbstract.TRACE,
+    intent: DebugLogAbstract.INTENT,
+    event: DebugLogAbstract.EVENT,
+    state: DebugLogAbstract.STATE
+};

package/dist/gateway-memory.js

@@ -113,8 +113,8 @@ export function buildWorkingMemory(request, existingWorkingMemory, otherMemories
     if (!workingMemory.job.narrative && request.prompt) {
         workingMemory.job.narrative = request.prompt;
     }
-    if (!workingMemory.job.id && request.jobId) {
-        workingMemory.job.id = request.jobId;
+    if (!workingMemory.job.id && request.identity.jobId) {
+        workingMemory.job.id = request.identity.jobId;
     }
     // Populate task fields from request if not already present in existing memory
     if (!workingMemory.task.objective && request.instructions) {
@@ -124,8 +124,8 @@ export function buildWorkingMemory(request, existingWorkingMemory, otherMemories
         workingMemory.task.context = request.context;
     }
     // Input field has been removed - data should come from workingMemory.input
-    if (!workingMemory.task.id && request.taskId) {
-        workingMemory.task.id = request.taskId;
+    if (!workingMemory.task.id && request.identity.taskId) {
+        workingMemory.task.id = request.identity.taskId;
     }
     // Add entity information if not present
     if (!workingMemory.entity && request.agentId) {
@@ -182,7 +182,7 @@ export async function resolveTemplateParams(request, config, logger) {
             // If memory component fails, fall back to request-only mode
             logger?.warn('Memory component resolution failed, using request-only mode', {
                 error: error instanceof Error ? error.message : String(error),
-                jobId: request.jobId
+                jobId: request.identity.jobId
             });
         }
     }
@@ -194,7 +194,7 @@ export async function resolveTemplateParams(request, config, logger) {
     // Rendrix priority: shortTermMemory > workingMemory > experienceMemory > knowledgeMemory
     if (request.templateTokens && Object.keys(request.templateTokens).length > 0) {
         logger?.debug('Merged templateTokens into shortTermMemory (tier 1 - highest priority)', {
-            jobId: request.jobId,
+            jobId: request.identity.jobId,
             tokenKeys: Object.keys(request.templateTokens)
         });
     }

package/dist/gateway-messages.js

@@ -24,7 +24,7 @@ function isAIRequest(request) {
  */
 export async function constructMessages(request, config, logger, parsedSnapshot) {
     logger.verbose('Constructing messages from request', {
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         agentId: request.agentId,
         hasInstructions: !!request.instructions,
         hasContext: !!request.context,
@@ -32,11 +32,11 @@ export async function constructMessages(request, config, logger, parsedSnapshot)
         hasWorkingMemory: !!request.workingMemory
     });
     // LOGGING: Construct messages phase (instructions should already be resolved)
-    const traceId = request.jobId || `trace-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const traceId = request.identity.jobId || request.aiRequestId;
     const agentId = request.agentId;
     logger.info('instructions.constructMessages.entry', {
         traceId,
-        jobId: request.jobId,
+        jobId: request.identity.jobId,
         agentId,
         'instructionsType': typeof request.instructions,
         'instructionsLength': typeof request.instructions === 'string' ? request.instructions.length : 'N/A',
@@ -59,7 +59,7 @@ export async function constructMessages(request, config, logger, parsedSnapshot)
                 if (typeof finalInstructions === 'string') {
                     finalInstructions = `${finalInstructions}\n\nExamples:\n${fewShotExamples}`;
                     logger.debug('Added few-shot examples to instructions', {
-                        jobId: request.jobId,
+                        jobId: request.identity.jobId,
                         exampleCount: Math.min(examples.length, 3),
                         totalExamples: examples.length
                     });

package/dist/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/gateway-meta.js

@@ -17,12 +17,19 @@ export async function testInstructions(instructions, testInput, expectedSchema,
     if (!model) {
         throw new Error('Model must be provided in options.model or configured as default');
     }
+    const aiRequestId = `test-instructions-${Date.now()}`;
+    const runtimeIdentity = {
+        ...options.identity,
+        aiRequestId,
+        agentId
+    };
     // Create test request with internal system action config
     const testRequest = {
-        jobId: `test-instructions-${Date.now()}`,
+        aiRequestId,
         agentId,
         instructions,
-        input: testInput,
+        identity: runtimeIdentity,
+        workingMemory: { input: testInput },
         config: {
             model,
             provider,

package/dist/gateway-utils.js

@@ -22,7 +22,7 @@ export 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 ? '...' : '')
@@ -41,7 +41,7 @@ export 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,
@@ -96,7 +96,7 @@ export 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'
         });
     }
@@ -112,7 +112,7 @@ export 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,
@@ -123,7 +123,7 @@ export 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,
@@ -135,7 +135,7 @@ export 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,
@@ -149,7 +149,7 @@ export 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,
@@ -162,7 +162,7 @@ export 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,
@@ -170,7 +170,7 @@ export 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/gateway-validation.js

@@ -2,6 +2,13 @@
  * Gateway Validation Module
  * Basic validation for clean proxy implementation
  */
+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
  */
@@ -12,6 +19,7 @@ export 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.`);
@@ -34,6 +42,7 @@ export 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.`);