@x12i/ai-gateway 7.9.1 → 9.0.0

package/dist-cjs/activity-manager.cjs

@@ -10,6 +10,7 @@ exports.ActivityManager = void 0;
 exports.ensureGatewayRequestIdentity = ensureGatewayRequestIdentity;
 const activix_1 = require("@x12i/activix");
 const activity_tracking_config_js_1 = require("./config/activity-tracking-config.cjs");
+const gateway_log_meta_js_1 = require("./gateway-log-meta.cjs");
 function readAiRequestIdFromRequest(request) {
     const aiRequestId = request.aiRequestId;
     if (typeof aiRequestId === 'string' && aiRequestId.trim().length > 0) {
@@ -106,40 +107,64 @@ function buildInstanceEnvelope(request) {
 function resolveSessionIdForRequest(request, incomingIdentity, aiRequestId) {
     const fromIdentity = trimIdentityString(incomingIdentity?.sessionId);
     const topLevel = trimIdentityString(request.sessionId);
-    const jobId = trimIdentityString(request.jobId);
+    const identityJobId = trimIdentityString(incomingIdentity?.jobId);
     if (fromIdentity !== undefined && topLevel !== undefined && fromIdentity !== topLevel) {
         throw new Error(`identity.sessionId (${fromIdentity}) and top-level sessionId (${topLevel}) must agree`);
     }
-    return fromIdentity ?? topLevel ?? jobId ?? aiRequestId;
+    return fromIdentity ?? topLevel ?? identityJobId ?? aiRequestId;
+}
+function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
+    const aiRequestId = merged.aiRequestId;
+    if (!incomingIdentity || typeof incomingIdentity !== 'object') {
+        logger?.warn('missingRuntimeIdentityObject', (0, gateway_log_meta_js_1.withActivityIdentity)(merged, {
+            message: 'request.identity is missing; upstream must send the mandatory runtime identity object',
+            aiRequestId,
+            debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+        }));
+        return;
+    }
+    const missing = [];
+    if (!trimIdentityString(incomingIdentity.jobId))
+        missing.push('jobId');
+    if (!trimIdentityString(incomingIdentity.taskId))
+        missing.push('taskId');
+    if (missing.length > 0) {
+        logger?.warn('missingUpstreamIdentityFields', (0, gateway_log_meta_js_1.withActivityIdentity)(merged, {
+            message: `Upstream identity is missing required field(s): ${missing.join(', ')}. jobId and taskId must be set on request.identity by the client; the gateway does not generate them.`,
+            missingFields: missing,
+            aiRequestId,
+            debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+        }));
+    }
 }
 function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
     const incomingIdentity = request.identity;
     const sessionId = resolveSessionIdForRequest(request, incomingIdentity, aiRequestId);
-    const legacyJobId = trimIdentityString(incomingIdentity?.jobId) ?? trimIdentityString(request.jobId);
+    const upstreamJobId = trimIdentityString(incomingIdentity?.jobId) ?? '';
+    const upstreamTaskId = trimIdentityString(incomingIdentity?.taskId) ?? '';
     const combinedEnrichment = pickGatewayEnrichmentFields({
         ...graphIdentityExtrasFromRequest(request),
         ...(extras || {})
     });
     const safeEnrichment = mergeActivixEnrichment(incomingIdentity, combinedEnrichment);
-    // Request fields are defaults for this hop; incoming `identity` from upstream wins on conflict.
-    // Gateway enrichment (graph/skill, etc.) fills only keys the outer envelope did not already set.
+    // jobId / taskId: upstream `request.identity` only (never top-level request.jobId / request.taskId).
     const merged = {
         jobTypeId: request.jobTypeId,
         agentId: request.agentId,
-        taskId: request.taskId,
         taskTypeId: request.taskTypeId,
         ...safeEnrichment,
         ...(incomingIdentity || {}),
         sessionId,
         instance: buildInstanceEnvelope(request),
-        aiRequestId
+        aiRequestId,
+        jobId: upstreamJobId,
+        taskId: upstreamTaskId
     };
     merged.sessionId = sessionId;
     merged.instance = buildInstanceEnvelope(request);
     merged.aiRequestId = aiRequestId;
-    if (legacyJobId !== undefined) {
-        merged.jobId = legacyJobId;
-    }
+    merged.jobId = upstreamJobId;
+    merged.taskId = upstreamTaskId;
     return merged;
 }
 /**
@@ -149,13 +174,16 @@ function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
  * **Execution context:** treats `request.identity` as received from upstream. Root fields (`sessionId`,
  * `instance`, and any keys already set on that object) are not replaced by gateway defaults; the gateway
  * only fills missing required pieces and adds local context (e.g. graph linkage) where absent.
+ *
+ * @param logger - Optional Logxer used to WARN when mandatory upstream `identity.jobId` / `identity.taskId` are absent.
  */
-function ensureGatewayRequestIdentity(request, extras) {
+function ensureGatewayRequestIdentity(request, extras, logger) {
     const aiRequestId = readAiRequestIdFromRequest(request);
     const identity = mergeGatewayActivityIdentity(request, aiRequestId, {
         ...graphIdentityExtrasFromRequest(request),
         ...(extras || {})
     });
+    logUpstreamIdentityWarnings(logger, request.identity, identity);
     request.identity = identity;
     return identity;
 }
@@ -291,7 +319,7 @@ class ActivityManager {
      * @returns Activity metadata (contains unique _id/recordId) or undefined if tracking is disabled
      */
     async startActivity(request, startTime) {
-        const identity = ensureGatewayRequestIdentity(request);
+        const identity = ensureGatewayRequestIdentity(request, undefined, this.logger);
         const aiRequestId = identity.aiRequestId;
         // Capture ONLY request data - NO response data at this stage
         // Note: v2.3.2+ excludes flat request/config fields from root level
@@ -311,9 +339,10 @@ class ActivityManager {
         }
         const activityMetadata = {
             aiRequestId,
+            jobId: identity.jobId,
             jobTypeId: request.jobTypeId,
             agentId: request.agentId,
-            taskId: request.taskId,
+            taskId: identity.taskId,
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',
@@ -507,7 +536,7 @@ class ActivityManager {
         }
         // Determine inference type (will be extracted in gateway.ts and passed via request metadata)
         const inferenceType = aiRequest.inferenceType || 'question-answer';
-        const identity = ensureGatewayRequestIdentity(request);
+        const identity = ensureGatewayRequestIdentity(request, undefined, this.logger);
         const aiRequestId = identity.aiRequestId;
         if (!this.activix) {
             return undefined;
@@ -525,9 +554,10 @@ class ActivityManager {
             skillId: skillId ?? skillKey,
             inferenceType, // ✅ Recommended: type of inference
             aiRequestId,
+            jobId: identity.jobId,
             jobTypeId: request.jobTypeId,
             agentId: request.agentId,
-            taskId: request.taskId,
+            taskId: identity.taskId,
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',
@@ -901,7 +931,7 @@ class ActivityManager {
      * @param startTime - When the request started
      */
     async logBadRequest(request, error, details, startTime) {
-        const identity = ensureGatewayRequestIdentity(request);
+        const identity = ensureGatewayRequestIdentity(request, undefined, this.logger);
         const aiRequestId = identity.aiRequestId;
         const endTime = details.endTime;
         const duration = details.duration;
@@ -926,9 +956,10 @@ class ActivityManager {
         const badRequestMetadata = {
             activityType: 'bad-request',
             aiRequestId,
+            jobId: identity.jobId,
             jobTypeId: request.jobTypeId,
             agentId: request.agentId,
-            taskId: request.taskId,
+            taskId: identity.taskId,
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',

package/dist-cjs/activity-manager.d.ts

@@ -15,8 +15,10 @@ type Request = ChatRequest | AIRequest;
  * **Execution context:** treats `request.identity` as received from upstream. Root fields (`sessionId`,
  * `instance`, and any keys already set on that object) are not replaced by gateway defaults; the gateway
  * only fills missing required pieces and adds local context (e.g. graph linkage) where absent.
+ *
+ * @param logger - Optional Logxer used to WARN when mandatory upstream `identity.jobId` / `identity.taskId` are absent.
  */
-export declare function ensureGatewayRequestIdentity(request: ChatRequest | AIRequest, extras?: Partial<ActivityIdentity>): ActivityIdentity;
+export declare function ensureGatewayRequestIdentity(request: ChatRequest | AIRequest, extras?: Partial<ActivityIdentity>, logger?: Logxer): ActivityIdentity;
 type ActivityMetadata = Record<string, any> & {
     activityId?: string;
     recordId?: string;

package/dist-cjs/content-normalizer/content-normalizer.cjs

@@ -187,14 +187,14 @@ function determineContentType(value, parsedContent) {
  * @param response - Router response object
  * @returns Normalized content with metadata
  */
-function normalizeContent(response) {
+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,
@@ -235,7 +235,7 @@ 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,
@@ -324,7 +324,7 @@ 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)
@@ -347,7 +347,7 @@ 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-cjs/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-cjs/flex-md-loader.cjs

@@ -61,6 +61,7 @@ exports.hasFlexMdContract = hasFlexMdContract;
 exports.detectComplianceLevel = detectComplianceLevel;
 const path = __importStar(require("path"));
 const url_1 = require("url");
+const logxer_1 = require("@x12i/logxer");
 let flexMdModule = null;
 let flexMdLoadError = null;
 let flexMdLoading = null;
@@ -374,7 +375,7 @@ async function extractFlexMdOutputFormatFromInstructions(instructions, complianc
  *   - Other flex-md options
  * @returns Parsed JSON object and method used, or null if parsing fails
  */
-async function extractJsonFromFlexMd(content) {
+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
@@ -392,8 +393,9 @@ 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
@@ -403,15 +405,16 @@ 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: logxer_1.DebugLogAbstract.TRACE });
+                        logger?.debug('extractJsonFromFlexMd: parsed json', { json, debugKind: logxer_1.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)
+                });
             }
         }
     }
@@ -419,13 +422,14 @@ 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
@@ -483,7 +487,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
@@ -526,12 +530,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: logxer_1.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: logxer_1.DebugLogAbstract.STATE });
     }
     // If we extracted some structure, return it
     if (Object.keys(result).length > 0) {

package/dist-cjs/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-cjs/gateway-config.cjs

@@ -92,10 +92,10 @@ const template_render_merge_js_1 = require("./template-render-merge.cjs");
 const gateway_rate_limiter_js_1 = require("./gateway-rate-limiter.cjs");
 const gateway_rate_limiter_constants_js_1 = require("./gateway-rate-limiter-constants.cjs");
 /**
- * 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).
  */
-function loadConfig() {
+function loadConfig(logger) {
     const defaultModelConfig = {};
     const defaultInstructionsBlocks = {};
     let defaultTemplateRendering;
@@ -120,26 +120,22 @@ 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']) {
@@ -167,10 +163,10 @@ function getFlexMdMinComplianceLevel() {
 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) {
@@ -179,7 +175,7 @@ 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
@@ -198,14 +194,14 @@ function setupRequestInterceptor(router, logger) {
 /**
  * Initializes gateway components
  */
-function initializeGatewayComponents(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering) {
+function initializeGatewayComponents(config) {
     // Initialize logger FIRST (before other components that might need it)
     const logger = (0, logger_factory_js_1.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-cjs/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-cjs/gateway-conversion.cjs

@@ -77,7 +77,7 @@ 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);
@@ -119,7 +119,7 @@ async function convertStructuredToJson(structuredText, originalRequest, config,
     });
     try {
         // Use flex-md 3.0.0 to extract and parse JSON
-        const flexMdResult = await (0, flex_md_loader_js_1.extractJsonFromFlexMd)(structuredText);
+        const flexMdResult = await (0, flex_md_loader_js_1.extractJsonFromFlexMd)(structuredText, logger);
         if (!flexMdResult || !flexMdResult.json) {
             throw new Error('flex-md SDK could not extract JSON from structured text');
         }

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

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatewayLogDebug = void 0;
+exports.activityIdentityToLogMeta = activityIdentityToLogMeta;
+exports.withActivityIdentity = withActivityIdentity;
+const logxer_1 = require("@x12i/logxer");
+/** Subset of identity forwarded on every structured log line (plus full envelope under `identity`). */
+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;
+}
+function withActivityIdentity(identity, data, debugKind) {
+    return {
+        ...activityIdentityToLogMeta(identity),
+        ...(data || {}),
+        ...(debugKind !== undefined ? { debugKind } : {})
+    };
+}
+exports.gatewayLogDebug = {
+    anomaly: logxer_1.DebugLogAbstract.ANOMALY,
+    trace: logxer_1.DebugLogAbstract.TRACE,
+    intent: logxer_1.DebugLogAbstract.INTENT,
+    event: logxer_1.DebugLogAbstract.EVENT,
+    state: logxer_1.DebugLogAbstract.STATE
+};

package/dist-cjs/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-cjs/gateway-memory.cjs

@@ -117,8 +117,8 @@ 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) {
@@ -128,8 +128,8 @@ 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) {
@@ -186,7 +186,7 @@ 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
             });
         }
     }
@@ -198,7 +198,7 @@ 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-cjs/gateway-messages.cjs

@@ -27,7 +27,7 @@ function isAIRequest(request) {
  */
 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,
@@ -35,11 +35,11 @@ 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',
@@ -62,7 +62,7 @@ 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-cjs/gateway-meta.cjs

@@ -20,12 +20,19 @@ async function testInstructions(instructions, testInput, expectedSchema, options
     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,