@x12i/ai-gateway 9.0.8 → 9.1.0

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

package/dist-cjs/types.d.ts

@@ -22,7 +22,22 @@ export interface DiagnosticsOptions {
      * Implementations must size-cap any raw payload included.
      */
     includeRawProviderPayload?: boolean;
+    /**
+     * When false, Activix activity completion omits `response.content.fullResponse` (large provider blob).
+     * When true or omitted, the full payload is stored (subject to `activityFullResponseMaxChars`).
+     */
+    includeFullProviderResponseInActivity?: boolean;
+    /**
+     * Max serialized length for `fullResponse` on activity records when included (JSON string length).
+     * Default applied in gateway when omitted.
+     */
+    activityFullResponseMaxChars?: number;
 }
+/**
+ * Classifies the gateway invocation for tracing and Activix (`runContext`).
+ * Mandatory on {@link AIInvokeRequest} (`AIGateway.invoke`).
+ */
+export type GatewayActionType = 'skill' | 'preSkill' | 'postSkill';
 export type GatewayTraceRequestIds = {
     /** Stable alias of gateway aiRequestId (always set when trace enabled). */
     gatewayAiRequestId: string;
@@ -111,6 +126,14 @@ export type ActivityIdentity = {
     coreSkillId?: string;
     masterSkillId?: string;
     masterSkillActivityId?: string;
+    /**
+     * From {@link AIInvokeRequest.actionType} when present (gateway.invoke); copied into runContext for Activix.
+     */
+    actionType?: GatewayActionType;
+    /**
+     * From {@link AIInvokeRequest.actionRef} when present; copied into runContext for Activix.
+     */
+    actionRef?: string;
 };
 /** Re-export parser template options for gateway consumers (MUST/optional protocol, subPathSearch, etc.). */
 export type { TemplateRenderOptions } from '@x12i/rendrix';
@@ -566,14 +589,6 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Added as system message between instructions and prompt
      */
     context?: string;
-    /**
-     * Task configuration (optional) - Control template behavior and conditional rendering
-     * @deprecated taskConfig is no longer used by Rendrix 3.0.0+
-     * Kept for backward compatibility only - will be ignored
-     */
-    taskConfig?: {
-        includeThoughts?: boolean;
-    };
     /**
      * Working memory (optional) - Affects all template parsing
      * Passed to Rendrix (v4+) for template variable substitution.
@@ -587,16 +602,6 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * the full list or only set `enabled` and inherit `roots` from the gateway default merge.
      */
     templateRenderOptions?: TemplateRenderOptions;
-    /**
-     * Template tokens (optional) - Tier 1 (highest priority) token values
-     * These tokens are passed directly as arguments and override all other memory sources
-     * Common tokens: taskDescription, input (from workingMemory.input), role
-     * Example: { taskDescription: "Extract emails", input: "user@example.com", role: "user" }
-     * Note: The `input` field has been removed. Use workingMemory.input instead.
-     */
-    templateTokens?: {
-        [key: string]: string | number | boolean | object | object[];
-    };
     /**
      * Messages array - Optional, can be used instead of instructions/prompt
      * If provided, will be appended as-is after built messages; instructions template text is still parsed for the system message when present
@@ -643,28 +648,6 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Can be a single type (string) or multiple types (array)
      */
     inferenceType?: string | string[];
-    /**
-     * Enable output schema validation (optional)
-     * When true, validates parsed output against schema from instruction metadata or outputs library
-     * @default false
-     */
-    validateOutputSchema?: boolean;
-    /**
-     * Enable strict validation mode (optional)
-     * When true, validation errors will throw exceptions instead of warnings
-     * @default false
-     */
-    strictValidation?: boolean;
-    /**
-     * Response transformation hooks (optional)
-     * Allows transforming responses at different stages of processing
-     */
-    transformations?: ResponseTransformationConfig;
-    /**
-     * Parse options for outputs library (optional)
-     * Used when inferenceType is provided for parsing inference outputs
-     */
-    parseOptions?: Record<string, unknown>;
     /**
      * Optional diagnostics controls. When omitted or mode != 'trace', the gateway must not
      * attach heavy diagnostic objects or raw provider payloads.
@@ -682,7 +665,7 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
  * Minimum: instructions + prompt (prompt is required for user message)
  *
  * Note: objectTypes is NOT supported in ChatRequest.
- * Use AIRequest with invoke() method for structured output requests.
+ * Use {@link AIInvokeRequest} with invoke() for structured output requests.
  */
 export interface ChatRequest extends BaseLLMRequest {
     /**
@@ -714,18 +697,19 @@ export interface StructuredTextSpec {
     formatHint?: string;
 }
 /**
- * AI request for structured output requests
- * Used exclusively with invoke() method for requests requiring structured output
+ * Payload for {@link AIGateway.invoke}: structured / skill flows with mandatory action classification.
  *
- * Mandatory:
- * - aiRequestId: Required for activity tracking
- * - agentId: Required to identify the agent
- * - instructions: Required (template text)
- * - primaryObjectType OR flexMdFormat: Required for structured output
- *   * primaryObjectType: Standard/custom object type (requires outputs library)
- *   * flexMdFormat: Direct flex-md format specification (no outputs library needed)
+ * Recorded on {@link ActivityIdentity} (`runContext`) and activity roots for Activix.
  */
-export interface AIRequest extends BaseLLMRequest {
+export interface AIInvokeRequest extends BaseLLMRequest {
+    /**
+     * Invocation kind: main skill vs pre/post hooks around skill execution.
+     */
+    actionType: GatewayActionType;
+    /**
+     * Stable reference for the action (e.g. `skills/my-skill`).
+     */
+    actionRef: string;
     /**
      * Encrypted reasoning items for conversation continuity
      * Only include reasoning.encrypted items from previous responses
@@ -739,10 +723,6 @@ export interface AIRequest extends BaseLLMRequest {
         data?: string;
         summary?: any[];
     }>;
-    /**
-     * Skill execution tracking fields
-     * Used when executing skills (instruction keys starting with 'skills/')
-     */
     /**
      * Master skill activity ID - The parent skill activity's ID (when a skill calls another skill)
      * When a skill executes and calls another skill, the parent skill's activityId becomes
@@ -761,6 +741,10 @@ export interface AIRequest extends BaseLLMRequest {
      */
     masterSkillId?: string;
 }
+/**
+ * @deprecated Prefer {@link AIInvokeRequest}; alias kept for existing imports.
+ */
+export type AIRequest = AIInvokeRequest;
 /**
  * Enhanced response with comprehensive metadata and generic type support
  *
@@ -1241,38 +1225,4 @@ export interface ValidationRule {
      */
     message?: string;
 }
-/**
- * Response transformation hooks configuration
- * Allows transforming responses at different stages of processing
- */
-export interface ResponseTransformationConfig {
-    /**
-     * Transform raw text before parsing
-     * @param rawText - Raw text from LLM response
-     * @param metadata - Request metadata (jobId, agentId, etc.)
-     * @returns Transformed raw text
-     */
-    preParse?: (rawText: string, metadata: any) => string;
-    /**
-     * Transform parsed content after parsing
-     * @param parsed - Parsed content (object/array)
-     * @param metadata - Request metadata
-     * @returns Transformed parsed content
-     */
-    postParse?: (parsed: any, metadata: any) => any;
-    /**
-     * Transform parsed content before validation
-     * @param parsed - Parsed content
-     * @param schema - JSON schema (if available)
-     * @returns Transformed parsed content
-     */
-    preValidate?: (parsed: any, schema: any) => any;
-    /**
-     * Transform validated content after validation
-     * @param validated - Validated content
-     * @param metadata - Request metadata
-     * @returns Transformed validated content
-     */
-    postValidate?: (validated: any, metadata: any) => any;
-}
 export type { LLMRequest, LLMResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.0.8",
+  "version": "9.1.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -65,7 +65,7 @@
     "@aws-sdk/s3-request-presigner": "^3.953.0",
     "@x12i/env": "^4.0.1",
     "@x12i/logxer": "^4.3.5",
-    "@x12i/activix": "^6.7.0",
+    "@x12i/activix": "^7.1.0",
     "@x12i/flex-md": "^4.8.0"
   },
   "devDependencies": {