@x12i/ai-gateway 9.0.9 → 9.1.1

package/dist-cjs/gateway-utils.cjs

@@ -37,12 +37,16 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = void 0;
 exports.generateMD5Hash = generateMD5Hash;
 exports.ensureTaskTypeId = ensureTaskTypeId;
 exports.mergeConfig = mergeConfig;
 exports.normalizeRouterUsageTokens = normalizeRouterUsageTokens;
 exports.extractTokenUsageFromRouterResponse = extractTokenUsageFromRouterResponse;
 exports.extractCostUsdFromRouterResponse = extractCostUsdFromRouterResponse;
+exports.pickInvokeRoutingMetadataSlice = pickInvokeRoutingMetadataSlice;
+exports.pickEffectiveModelConfigForMetadata = pickEffectiveModelConfigForMetadata;
+exports.capActivityFullResponsePayload = capActivityFullResponsePayload;
 const crypto = __importStar(require("crypto"));
 const gateway_instructions_js_1 = require("./gateway-instructions.cjs");
 const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
@@ -224,53 +228,90 @@ function firstFiniteNumber(...vals) {
     for (const v of vals) {
         if (typeof v === 'number' && Number.isFinite(v))
             return v;
+        if (typeof v === 'string' && v.trim() !== '') {
+            const n = Number(v);
+            if (Number.isFinite(n))
+                return n;
+        }
     }
     return undefined;
 }
+function isNonZeroTokenCount(n) {
+    return !!(n.prompt || n.completion || n.total);
+}
 /**
  * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
- * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, Responses-style input/output tokens, and missing total (sum prompt+completion).
  */
 function normalizeRouterUsageTokens(usage) {
     if (usage == null || typeof usage !== 'object')
         return undefined;
     const u = usage;
-    const prompt = firstFiniteNumber(u.promptTokens, u.inputTokens, u.prompt, u.prompt_tokens) ?? 0;
-    const completion = firstFiniteNumber(u.completionTokens, u.outputTokens, u.completion, u.completion_tokens) ?? 0;
-    let total = firstFiniteNumber(u.totalTokens, u.total_tokens) ?? 0;
+    const prompt = firstFiniteNumber(u.promptTokens, u.inputTokens, u.input_tokens, u.prompt, u.prompt_tokens) ?? 0;
+    const completion = firstFiniteNumber(u.completionTokens, u.outputTokens, u.output_tokens, u.completion, u.completion_tokens) ?? 0;
+    let total = firstFiniteNumber(u.totalTokens, u.total_tokens, u.total) ?? 0;
     if (!total && (prompt || completion))
         total = prompt + completion;
     return { prompt, completion, total };
 }
 /**
- * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ * Collect usage from one router/provider envelope (single object).
+ * When followRaw is true, also reads `(rawResponse ?? raw).usage` on that envelope.
  */
-function extractTokenUsageFromRouterResponse(routerResponse) {
-    if (routerResponse == null || typeof routerResponse !== 'object') {
-        return { prompt: 0, completion: 0, total: 0 };
-    }
-    const r = routerResponse;
-    const meta = r.metadata != null && typeof r.metadata === 'object'
-        ? r.metadata
+function collectUsageBucketsFromRoot(root, followRaw) {
+    const meta = root.metadata != null && typeof root.metadata === 'object'
+        ? root.metadata
         : undefined;
-    const buckets = [r.usage];
+    const buckets = [root.usage];
     if (meta) {
         buckets.push(meta.usage);
+        buckets.push(meta.tokens);
         const nested = meta['ai-activities-response'];
         if (nested != null && typeof nested === 'object') {
             buckets.push(nested.usage);
         }
     }
-    const raw = r.rawResponse ?? r.raw;
-    if (raw != null && typeof raw === 'object') {
-        buckets.push(raw.usage);
+    if (followRaw) {
+        const raw = root.rawResponse ?? root.raw;
+        if (raw != null && typeof raw === 'object') {
+            buckets.push(raw.usage);
+        }
     }
+    return buckets;
+}
+function firstNonZeroUsageFromBuckets(buckets) {
     for (const b of buckets) {
         const n = normalizeRouterUsageTokens(b);
-        if (n && (n.prompt || n.completion || n.total))
+        if (n && isNonZeroTokenCount(n))
             return n;
     }
-    return { prompt: 0, completion: 0, total: 0 };
+    return undefined;
+}
+/**
+ * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ * Prefers the raw/provider body (`rawResponse` / `raw`) when it carries non-zero usage before re-reading the outer envelope.
+ */
+function extractTokenUsageFromRouterResponse(routerResponse) {
+    const zeros = { prompt: 0, completion: 0, total: 0 };
+    if (routerResponse == null || typeof routerResponse !== 'object') {
+        return zeros;
+    }
+    const r = routerResponse;
+    const raw = r.rawResponse ?? r.raw;
+    const inner = raw != null && typeof raw === 'object' ? raw : undefined;
+    const roots = inner != null && inner !== r
+        ? [
+            { root: inner, followRaw: false },
+            { root: r, followRaw: true }
+        ]
+        : [{ root: r, followRaw: true }];
+    for (const { root, followRaw } of roots) {
+        const buckets = collectUsageBucketsFromRoot(root, followRaw);
+        const found = firstNonZeroUsageFromBuckets(buckets);
+        if (found)
+            return found;
+    }
+    return zeros;
 }
 /**
  * Best-effort USD cost from router/sync AIResponse shape: metadata.costUsd (preferred),
@@ -319,3 +360,70 @@ function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return undefined;
 }
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+function pickInvokeRoutingMetadataSlice(routerResponse, mergedConfig) {
+    const rr = routerResponse != null && typeof routerResponse === 'object' ? routerResponse : {};
+    const meta = rr.metadata != null && typeof rr.metadata === 'object' ? rr.metadata : {};
+    const cfg = mergedConfig != null && typeof mergedConfig === 'object' ? mergedConfig : {};
+    const provider = meta.provider || rr.provider || cfg.provider;
+    const modelUsed = meta.modelUsed || meta.model || rr.model || cfg.model;
+    const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
+        ? meta.maxTokensRequested
+        : typeof cfg.maxTokens === 'number'
+            ? cfg.maxTokens
+            : undefined;
+    const region = typeof meta.region === 'string' ? meta.region : undefined;
+    const out = {};
+    if (provider !== undefined && provider !== null)
+        out.provider = provider;
+    if (modelUsed !== undefined && modelUsed !== null)
+        out.modelUsed = modelUsed;
+    if (maxTokensRequested !== undefined)
+        out.maxTokensRequested = maxTokensRequested;
+    if (region !== undefined)
+        out.region = region;
+    return out;
+}
+/**
+ * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
+ */
+function pickEffectiveModelConfigForMetadata(mergedConfig) {
+    if (mergedConfig == null || typeof mergedConfig !== 'object')
+        return undefined;
+    const c = mergedConfig;
+    const keys = ['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP'];
+    const out = {};
+    for (const k of keys) {
+        const v = c[k];
+        if (v !== undefined)
+            out[k] = v;
+    }
+    return Object.keys(out).length ? out : undefined;
+}
+/** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
+exports.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512_000;
+/**
+ * Size-cap a provider/router payload before storing on an activity record.
+ * Non-serializable values become a small marker object instead of throwing.
+ */
+function capActivityFullResponsePayload(payload, maxChars = exports.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS) {
+    if (payload == null)
+        return payload;
+    let serialized;
+    try {
+        serialized = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    }
+    catch {
+        return { _truncated: true, _reason: 'not_serializable' };
+    }
+    if (serialized.length <= maxChars)
+        return payload;
+    return {
+        _truncated: true,
+        _originalCharLength: serialized.length,
+        _preview: serialized.slice(0, maxChars)
+    };
+}

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

@@ -2,7 +2,7 @@
  * Gateway Utilities Module
  * Handles utility functions
  */
-import type { ChatRequest, GatewayConfig } from './types.js';
+import type { ChatRequest, GatewayConfig, ModelConfig } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 /**
  * Generates MD5 hash of a string
@@ -21,7 +21,7 @@ export declare function mergeConfig(request: ChatRequest & {
 }, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;
 /**
  * Maps provider/router usage objects to gateway token counts (`metadata.tokens`, Activix, trace attempts).
- * Handles promptTokens/inputTokens, OpenAI-style snake_case, and missing total (sum prompt+completion).
+ * Handles promptTokens/inputTokens, OpenAI-style snake_case, Responses-style input/output tokens, and missing total (sum prompt+completion).
  */
 export declare function normalizeRouterUsageTokens(usage: unknown): {
     prompt: number;
@@ -30,6 +30,7 @@ export declare function normalizeRouterUsageTokens(usage: unknown): {
 } | undefined;
 /**
  * Reads token usage from every stable location the router may populate (see docs/PROVIDERS_ROUTER_DIAGNOSTICS_TRACE_REQUIREMENTS.md).
+ * Prefers the raw/provider body (`rawResponse` / `raw`) when it carries non-zero usage before re-reading the outer envelope.
  */
 export declare function extractTokenUsageFromRouterResponse(routerResponse: unknown): {
     prompt: number;
@@ -42,3 +43,24 @@ export declare function extractTokenUsageFromRouterResponse(routerResponse: unkn
  * Does not compute cost from tokens — adapters must populate normalized fields or raw usage.cost-style keys.
  */
 export declare function extractCostUsdFromRouterResponse(routerResponse: unknown): number | undefined;
+/**
+ * Stable routing facts for gateway response metadata (router metadata + merged config fallbacks).
+ * Matches trace-mode resolution; intended for every successful invoke(), not only diagnostics.trace.
+ */
+export declare function pickInvokeRoutingMetadataSlice(routerResponse: unknown, mergedConfig: unknown): Partial<{
+    provider: string;
+    modelUsed: string;
+    maxTokensRequested: number;
+    region: string;
+}>;
+/**
+ * Allowlisted generation profile from merged config for client introspection (no secrets, no arbitrary extras).
+ */
+export declare function pickEffectiveModelConfigForMetadata(mergedConfig: unknown): Partial<Pick<ModelConfig, 'model' | 'modelId' | 'provider' | 'temperature' | 'maxTokens' | 'topP'>> | undefined;
+/** Default JSON string length cap for Activix `content.fullResponse` when diagnostics allow storing it. */
+export declare const DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS = 512000;
+/**
+ * Size-cap a provider/router payload before storing on an activity record.
+ * Non-serializable values become a small marker object instead of throwing.
+ */
+export declare function capActivityFullResponsePayload(payload: unknown, maxChars?: number): unknown;

package/dist-cjs/gateway-validation.cjs

@@ -36,8 +36,9 @@ function validateChatRequest(request) {
         throw err;
     }
 }
+const GATEWAY_ACTION_TYPES = ['skill', 'preSkill', 'postSkill'];
 /**
- * Validates AIRequest has required fields
+ * Validates AIInvokeRequest has required fields
  */
 function validateAIRequest(request) {
     if (!request.aiRequestId) {
@@ -47,6 +48,14 @@ function validateAIRequest(request) {
         throw new Error('agentId is required for AI requests');
     }
     validateMandatoryRuntimeIdentity(request);
+    if (!request.actionType ||
+        !GATEWAY_ACTION_TYPES.includes(request.actionType)) {
+        throw new Error(`actionType is required and must be one of: ${GATEWAY_ACTION_TYPES.join(', ')}`);
+    }
+    const ref = typeof request.actionRef === 'string' ? request.actionRef.trim() : '';
+    if (!ref) {
+        throw new Error('actionRef is required and must be a non-empty string');
+    }
     // Reject input field - it has been removed
     if ('input' in request && request.input !== undefined) {
         const err = new Error(`The 'input' field has been removed. Use workingMemory.input instead for template rendering. Prompt templates should contain {{input}} which will be resolved from workingMemory.input.`);

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

@@ -2,12 +2,12 @@
  * Gateway Validation Module
  * Basic validation for clean proxy implementation
  */
-import type { ChatRequest, AIRequest } from './types.js';
+import type { ChatRequest, AIInvokeRequest } from './types.js';
 /**
  * Validates ChatRequest has required fields
  */
 export declare function validateChatRequest(request: ChatRequest): void;
 /**
- * Validates AIRequest has required fields
+ * Validates AIInvokeRequest has required fields
  */
-export declare function validateAIRequest(request: AIRequest): void;
+export declare function validateAIRequest(request: AIInvokeRequest): void;

package/dist-cjs/gateway.cjs

@@ -516,9 +516,19 @@ class AIGateway {
             }
             contentType = 'structured';
             parsingMethod = 'flex-md';
-            const tokens = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(routerResponse);
+            let tokens = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(routerResponse);
+            if (!(tokens.prompt || tokens.completion || tokens.total)) {
+                const alt = routerResponse?.rawResponse ?? routerResponse?.raw;
+                if (alt != null && typeof alt === 'object' && alt !== routerResponse) {
+                    const second = (0, gateway_utils_js_1.extractTokenUsageFromRouterResponse)(alt);
+                    if (second.prompt || second.completion || second.total)
+                        tokens = second;
+                }
+            }
             const resolvedCostUsd = (0, gateway_utils_js_1.extractCostUsdFromRouterResponse)(routerResponse);
             const routerMetaForCost = routerResponse?.metadata || {};
+            const routingMetadataSlice = (0, gateway_utils_js_1.pickInvokeRoutingMetadataSlice)(routerResponse, mergedConfig);
+            const effectiveModelConfig = (0, gateway_utils_js_1.pickEffectiveModelConfigForMetadata)(mergedConfig);
             const enhancedResponse = {
                 content: content,
                 parsedContent: parsedContent,
@@ -531,6 +541,8 @@ class AIGateway {
                     agentType: 'ai',
                     contentType,
                     parsingMethod,
+                    ...routingMetadataSlice,
+                    ...(effectiveModelConfig !== undefined ? { effectiveModelConfig } : {}),
                     ...(typeof resolvedCostUsd === 'number'
                         ? {
                             costUsd: resolvedCostUsd,
@@ -540,38 +552,32 @@ class AIGateway {
                         }
                         : {}),
                     ...(traceEnabled
-                        ? (() => {
-                            const meta = routerResponse?.metadata || {};
-                            const provider = meta.provider || routerResponse?.provider || mergedConfig?.provider;
-                            const region = typeof meta.region === 'string' ? meta.region : undefined;
-                            const modelUsed = meta.modelUsed || meta.model || routerResponse?.model || mergedConfig?.model;
-                            const maxTokensRequested = typeof meta.maxTokensRequested === 'number'
-                                ? meta.maxTokensRequested
-                                : typeof mergedConfig?.maxTokens === 'number'
-                                    ? mergedConfig.maxTokens
-                                    : undefined;
-                            return {
-                                provider,
-                                region,
-                                modelUsed,
-                                maxTokensRequested,
-                                requestIds: traceRequestIds,
-                                retryCount: traceRetryCount,
-                                fallbackCount: traceFallbackCount,
-                                attempts: traceAttempts
-                            };
-                        })()
+                        ? {
+                            requestIds: traceRequestIds,
+                            retryCount: traceRetryCount,
+                            fallbackCount: traceFallbackCount,
+                            attempts: traceAttempts
+                        }
                         : {})
                 }
             };
             // Track activity success if activity was started
             if (activity) {
                 try {
+                    const diag = request.diagnostics;
+                    const includeFullProviderBlob = diag?.includeFullProviderResponseInActivity !== false;
+                    const maxFullChars = typeof diag?.activityFullResponseMaxChars === 'number' && diag.activityFullResponseMaxChars > 0
+                        ? diag.activityFullResponseMaxChars
+                        : gateway_utils_js_1.DEFAULT_ACTIVITY_FULL_RESPONSE_MAX_CHARS;
+                    const rawFull = routerResponse.rawResponse || routerResponse;
+                    const fullResponseForActivity = includeFullProviderBlob
+                        ? (0, gateway_utils_js_1.capActivityFullResponsePayload)(rawFull, maxFullChars)
+                        : undefined;
                     // Create activity response with proper structure for ActivityTracker
                     const activityResponse = {
                         content: {
                             rawContent: content, // Store the actual response content as rawContent
-                            fullResponse: routerResponse.rawResponse || routerResponse // Include full router response
+                            ...(fullResponseForActivity !== undefined ? { fullResponse: fullResponseForActivity } : {})
                         },
                         parsed: parsedContent, // Include parsed content in activity record
                         metadata: enhancedResponse.metadata,

package/dist-cjs/gateway.d.ts

@@ -4,7 +4,7 @@
  * Simplified AI Gateway - Clean proxy implementation
  */
 import { LLMProviderRouter } from '@x12i/ai-providers-router';
-import type { GatewayConfig, ChatRequest, AIRequest, EnhancedLLMResponse } from './types.js';
+import type { GatewayConfig, ChatRequest, AIInvokeRequest, EnhancedLLMResponse } from './types.js';
 import type { Logxer } from '@x12i/logxer';
 import { ActivityManager } from './activity-manager.js';
 /**
@@ -25,7 +25,7 @@ export declare class AIGateway {
     /**
      * Invoke AI request (with structured output support)
      */
-    invoke<TContent = unknown>(request: AIRequest): Promise<EnhancedLLMResponse<TContent>>;
+    invoke<TContent = unknown>(request: AIInvokeRequest): Promise<EnhancedLLMResponse<TContent>>;
     /**
      * Build simple messages from request (instructions and prompt as literal template text; no registry).
      */

package/dist-cjs/index.d.ts

@@ -16,11 +16,11 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIRequest, EnhancedLLMResponse, InstructionMetadata, ValidationRule, ResponseTransformationConfig, TemplateRenderOptions } from './types.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions } from './types.js';
 export { mergeTemplateRenderOptions } from './template-render-merge.js';
 export type { UsageTier } from './types.js';
 export { Activix } from '@x12i/activix';
-export type { ActivixRunContext, FindByRunContextCriteria } from '@x12i/activix';
+export type { ActivixRunContext, FindByRunContextCriteria, GetJobActivitiesInput, GetJobActivitiesResult } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogMeta, withActivityIdentity, gatewayLogDebug } from './gateway-log-meta.js';

package/dist-cjs/instruction-optimizer.cjs

@@ -145,8 +145,11 @@ async function optimizeInstructions(gateway, originalInstructions, options) {
     const optimizationRequest = {
         aiRequestId,
         agentId,
+        actionType: 'skill',
+        actionRef: 'internal/instruction-optimizer',
         instructions: INSTRUCTION_OPTIMIZER_INSTRUCTIONS + additionalContext,
         identity,
+        prompt: '{{input}}',
         workingMemory: { input: originalInstructions },
         config: {
             model,

package/dist-cjs/runtime-objects.d.ts

@@ -1,17 +1,6 @@
 import type { Logxer } from '@x12i/logxer';
-import type { Activix } from '@x12i/activix';
-export type ActivixQueryableClient = {
-    getJobActivities(input: {
-        jobId: string;
-        graphId?: string;
-        nodeId?: string;
-        limit?: number;
-    }): Promise<{
-        jobId: string;
-        graphRun?: unknown;
-        activities: unknown[];
-    }>;
-};
+import type { Activix, ActivixQueryableClient } from '@x12i/activix';
+export type { ActivixQueryableClient } from '@x12i/activix';
 export type LogxerQueryableClient = {
     getJobLogs(input: {
         jobId: string;

package/dist-cjs/troubleshooting-helper.cjs

@@ -187,18 +187,27 @@ function validateSingleObjectType(objType, context, index) {
 /**
  * Validates AIRequest structure
  */
+const GATEWAY_ACTION_TYPES_DIAG = ['skill', 'preSkill', 'postSkill'];
 function validateAIRequest(request) {
     const errors = [];
     const warnings = [];
-    // Validate base fields
-    if (!request.jobId) {
-        errors.push('jobId is required');
+    const identityJobId = request.identity && typeof request.identity === 'object' ? request.identity.jobId : undefined;
+    if (!identityJobId && !request.jobId) {
+        errors.push('identity.jobId is required (legacy top-level jobId is deprecated)');
     }
     if (!request.agentId) {
         errors.push('agentId is required');
     }
+    if (!request.actionType ||
+        !GATEWAY_ACTION_TYPES_DIAG.includes(request.actionType)) {
+        errors.push('actionType is required and must be skill, preSkill, or postSkill');
+    }
+    const actionRefTrim = typeof request.actionRef === 'string' ? request.actionRef.trim() : '';
+    if (!actionRefTrim) {
+        errors.push('actionRef is required (non-empty string, e.g. skill id)');
+    }
     if (!request.instructions) {
-        warnings.push('instructions is optional (system-context will be used as fallback)');
+        errors.push('instructions is required');
     }
     if (!request.prompt) {
         errors.push('Prompt is required (input field has been removed - use workingMemory.input instead)');
@@ -449,11 +458,23 @@ function supportsJSONMode(provider, model) {
  * Creates a test AIRequest with minimal valid structure
  */
 function createTestAIRequest(overrides) {
-    return {
-        jobId: 'test-job-' + Date.now(),
+    const aiRequestId = 'test-ai-req-' + Date.now();
+    const base = {
+        aiRequestId,
         agentId: 'test-agent',
+        actionType: 'skill',
+        actionRef: 'tests/createTestAIRequest',
         instructions: 'Test instructions',
-        input: 'Test input',
+        prompt: '{{input}}',
+        workingMemory: { input: 'Test input' },
+        identity: {
+            sessionId: `session-${aiRequestId}`,
+            instance: { instanceId: 'test-agent', type: 'test' },
+            aiRequestId,
+            jobId: `job-${aiRequestId}`,
+            agentId: 'test-agent',
+            taskId: `task-${aiRequestId}`
+        },
         config: {
             model: 'gpt-4o',
             provider: 'openai'
@@ -470,20 +491,33 @@ function createTestAIRequest(overrides) {
         },
         ...overrides
     };
+    return base;
 }
 /**
  * Creates test cases for validation
  */
 function createValidationTestCases() {
+    const sampleIdentity = (jobId, agentId) => ({
+        sessionId: `session-${jobId}`,
+        instance: { instanceId: agentId, type: 'test' },
+        aiRequestId: `ai-${jobId}`,
+        jobId,
+        agentId,
+        taskId: `task-${jobId}`
+    });
     return [
         {
             name: 'Valid minimal request',
             request: {
-                jobId: 'test',
+                aiRequestId: 'ai-valid-min',
                 agentId: 'agent-1',
+                actionType: 'skill',
+                actionRef: 'validation/minimal',
+                identity: sampleIdentity('test', 'agent-1'),
                 instructions: 'Test',
                 prompt: 'test.prompt',
-                workingMemory: { input: 'Test' }
+                workingMemory: { input: 'Test' },
+                config: { model: 'gpt-4o', provider: 'openai' }
             },
             shouldFail: false,
             expectedErrors: []
@@ -491,8 +525,11 @@ function createValidationTestCases() {
         {
             name: 'Valid request with config',
             request: {
-                jobId: 'test',
+                aiRequestId: 'ai-valid-cfg',
                 agentId: 'agent-1',
+                actionType: 'skill',
+                actionRef: 'validation/config',
+                identity: sampleIdentity('test', 'agent-1'),
                 instructions: 'Test',
                 prompt: 'test.prompt',
                 workingMemory: { input: 'Test' },
@@ -505,23 +542,40 @@ function createValidationTestCases() {
             expectedErrors: []
         },
         {
-            name: 'Missing jobId',
+            name: 'Missing identity.jobId',
             request: {
+                aiRequestId: 'ai-no-job',
                 agentId: 'agent-1',
+                actionType: 'skill',
+                actionRef: 'validation/x',
+                identity: {
+                    sessionId: 's',
+                    instance: { instanceId: 'agent-1', type: 'test' },
+                    aiRequestId: 'ai-no-job',
+                    jobId: '',
+                    agentId: 'agent-1',
+                    taskId: 't'
+                },
                 instructions: 'Test',
                 prompt: 'test.prompt',
-                workingMemory: { input: 'Test' }
+                workingMemory: { input: 'Test' },
+                config: { model: 'gpt-4o', provider: 'openai' }
             },
             shouldFail: true,
-            expectedErrors: ['jobId is required']
+            expectedErrors: ['identity.jobId is required (legacy top-level jobId is deprecated)']
         },
         {
             name: 'Missing agentId',
             request: {
-                jobId: 'test',
+                aiRequestId: 'ai-no-agent',
+                actionType: 'skill',
+                actionRef: 'validation/x',
+                identity: sampleIdentity('test', 'agent-1'),
                 instructions: 'Test',
                 prompt: 'test.prompt',
-                workingMemory: { input: 'Test' }
+                workingMemory: { input: 'Test' },
+                config: { model: 'gpt-4o', provider: 'openai' }
+                // intentional: no top-level agentId
             },
             shouldFail: true,
             expectedErrors: ['agentId is required']
@@ -529,10 +583,14 @@ function createValidationTestCases() {
         {
             name: 'Missing instructions',
             request: {
-                jobId: 'test',
+                aiRequestId: 'ai-no-inst',
                 agentId: 'agent-1',
+                actionType: 'skill',
+                actionRef: 'validation/x',
+                identity: sampleIdentity('test', 'agent-1'),
                 prompt: 'test.prompt',
-                workingMemory: { input: 'Test' }
+                workingMemory: { input: 'Test' },
+                config: { model: 'gpt-4o', provider: 'openai' }
             },
             shouldFail: true,
             expectedErrors: ['instructions is required']
@@ -540,12 +598,33 @@ function createValidationTestCases() {
         {
             name: 'Missing prompt',
             request: {
-                jobId: 'test',
+                aiRequestId: 'ai-no-prompt',
                 agentId: 'agent-1',
-                instructions: 'Test'
+                actionType: 'skill',
+                actionRef: 'validation/x',
+                identity: sampleIdentity('test', 'agent-1'),
+                instructions: 'Test',
+                workingMemory: { input: 'Test' },
+                config: { model: 'gpt-4o', provider: 'openai' }
+            },
+            shouldFail: true,
+            expectedErrors: ['Prompt is required (input field has been removed - use workingMemory.input instead)']
+        },
+        {
+            name: 'Missing actionRef',
+            request: {
+                aiRequestId: 'ai-no-ref',
+                agentId: 'agent-1',
+                actionType: 'skill',
+                actionRef: '  ',
+                identity: sampleIdentity('test', 'agent-1'),
+                instructions: 'Test',
+                prompt: 'p',
+                workingMemory: { input: 'Test' },
+                config: { model: 'gpt-4o', provider: 'openai' }
             },
             shouldFail: true,
-            expectedErrors: ['input is required']
+            expectedErrors: ['actionRef is required (non-empty string, e.g. skill id)']
         }
     ];
 }

package/dist-cjs/troubleshooting-helper.d.ts

@@ -57,9 +57,6 @@ export interface DiagnosticInfo {
         validationErrors?: string[];
     };
 }
-/**
- * Validates AIRequest structure
- */
 export declare function validateAIRequest(request: Partial<AIRequest>): ValidationResult;
 /**
  * Validates JSON string