@x12i/ai-gateway 9.0.9 → 9.1.0

package/dist/troubleshooting-helper.js

@@ -172,18 +172,27 @@ function validateSingleObjectType(objType, context, index) {
 /**
  * Validates AIRequest structure
  */
+const GATEWAY_ACTION_TYPES_DIAG = ['skill', 'preSkill', 'postSkill'];
 export 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)');
@@ -434,11 +443,23 @@ export function supportsJSONMode(provider, model) {
  * Creates a test AIRequest with minimal valid structure
  */
 export 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'
@@ -455,20 +476,33 @@ export function createTestAIRequest(overrides) {
         },
         ...overrides
     };
+    return base;
 }
 /**
  * Creates test cases for validation
  */
 export 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: []
@@ -476,8 +510,11 @@ export 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' },
@@ -490,23 +527,40 @@ export 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']
@@ -514,10 +568,14 @@ export 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']
@@ -525,12 +583,33 @@ export 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/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/dist-cjs/activity-manager.cjs

@@ -165,6 +165,17 @@ function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
     merged.aiRequestId = aiRequestId;
     merged.jobId = upstreamJobId;
     merged.taskId = upstreamTaskId;
+    // gateway.invoke (AIInvokeRequest): request root is canonical for Activix runContext.
+    if ('actionType' in request && 'actionRef' in request) {
+        const inv = request;
+        if (inv.actionType) {
+            merged.actionType = inv.actionType;
+        }
+        const ref = typeof inv.actionRef === 'string' ? inv.actionRef.trim() : '';
+        if (ref) {
+            merged.actionRef = ref;
+        }
+    }
     return merged;
 }
 /**
@@ -263,12 +274,37 @@ class ActivityManager {
                         }
                     }
                 });
-                this.initPromise = this.activix.init().catch((error) => {
-                    // MongoDB config not available - log warning but don't throw.
-                    // This allows tests and development to work without MongoDB.
-                    this.logger.warn('Activity tracking enabled but MongoDB configuration not available. Activity records will not be persisted.', {
+                this.initPromise = this.activix
+                    .init()
+                    .then(() => {
+                    const ax = this.activix;
+                    if (!ax) {
+                        return;
+                    }
+                    const backend = ax.storageBackend;
+                    const mongoDb = backend === 'database' ? (0, activix_1.resolveActivixLogsDatabaseName)() : undefined;
+                    const mongoUriConfigured = Boolean((0, activix_1.resolveActivixMongoUriFromEnv)());
+                    this.logger.info('Activity tracking persistence backend ready', {
+                        storageBackend: backend,
+                        mongoDatabase: mongoDb,
+                        mongoUriConfigured,
+                        mainCollection: collectionName,
+                        badRequestsCollection: badRequestsCollectionName,
+                        skillExecutionsCollection: this.skillExecutionsCollectionName,
+                        ...(backend === 'local'
+                            ? {
+                                note: 'Activix is using local playground storage, not MongoDB. The ai-actions collection will not appear in Mongo until URI is set (MONGO_URI or MONGO_LOGS_URI), Activix can ping the database, and at least one activity is written.'
+                            }
+                            : {
+                                note: 'MongoDB stores one document per activity; the ai-actions collection is created on first insert (empty collections may be hidden in some tools until then).'
+                            })
+                    });
+                })
+                    .catch((error) => {
+                    // Init threw — disable tracker so requests are not blocked.
+                    this.logger.warn('Activity tracking enabled but Activix init failed. Activity records will not be persisted.', {
                         error: error instanceof Error ? error.message : String(error),
-                        hint: 'Set MONGO_URI and MONGO_LOGS_DB (or MONGO_DB) environment variables to enable activity tracking persistence'
+                        hint: 'Set MONGO_URI or MONGO_LOGS_URI and a database name (MONGO_LOGS_DB, MONGO_DB, MONGO_AI_LOGS_DB, or ACTIVIX_DB_NAME). See README: Activity tracking / persistence troubleshooting.'
                     });
                     this.activix = undefined;
                 });
@@ -347,6 +383,8 @@ class ActivityManager {
             startTime,
             status: 'started',
             activityType: 'gateway-invocation',
+            ...(identity.actionType !== undefined && { actionType: identity.actionType }),
+            ...(identity.actionRef !== undefined && identity.actionRef !== '' && { actionRef: identity.actionRef }),
             // Activix v5+: correlation BSON field is `runContext` (same object as `request.identity`)
             runContext: identity
             // Removed root-level fields per v2.3.2:
@@ -561,6 +599,8 @@ class ActivityManager {
             taskTypeId: request.taskTypeId,
             startTime,
             status: 'started',
+            ...(identity.actionType !== undefined && { actionType: identity.actionType }),
+            ...(identity.actionRef !== undefined && identity.actionRef !== '' && { actionRef: identity.actionRef }),
             runContext: identity,
             ...(instructionMetadata.key && { instructionKey: instructionMetadata.key }),
             ...(instructionMetadata.version && { instructionVersion: instructionMetadata.version }),

package/dist-cjs/config/activity-tracking-config.cjs

@@ -1,11 +1,12 @@
 "use strict";
 /**
  * Centralized activity tracking configuration.
- * Single source of truth for package-level collection names.
+ * Package-level Mongo collection names are fixed literals here (no env override).
+ * Main gateway rows: `ai-actions`; bad requests: `bad-requests` (see constants below).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveActivityTrackingConfig = resolveActivityTrackingConfig;
-const ACTIVITY_COLLECTION_NAME = 'ai-activities';
+const ACTIVITY_COLLECTION_NAME = 'ai-actions';
 const BAD_REQUESTS_COLLECTION_NAME = 'bad-requests';
 function resolveActivityTrackingConfig() {
     // Collection names are intentionally hardcoded at package level.

package/dist-cjs/config/activity-tracking-config.d.ts

@@ -1,6 +1,7 @@
 /**
  * Centralized activity tracking configuration.
- * Single source of truth for package-level collection names.
+ * Package-level Mongo collection names are fixed literals here (no env override).
+ * Main gateway rows: `ai-actions`; bad requests: `bad-requests` (see constants below).
  */
 export interface ActivityTrackingConfig {
     mongoUri: string;

package/dist-cjs/gateway-memory.cjs

@@ -18,7 +18,6 @@ function isAIRequest(request) {
  * Merges existing workingMemory (from request or memory component) with request metadata
  *
  * Implements tiered token resolution:
- * - Tier 1 (highest): templateTokens (handled in resolveTemplateParams, merged into shortTermMemory)
  * - Tier 2: workingMemory (this method) - checks existing workingMemory first
  * - Tier 3: derived from request fields or other memories (fallback)
  */
@@ -38,7 +37,6 @@ function buildWorkingMemory(request, existingWorkingMemory, otherMemories) {
     }
     /**
      * Token Resolution with Tiered Fallback
-     * Tier 1: templateTokens (handled in resolveTemplateParams, merged into shortTermMemory)
      * Tier 2: workingMemory (check existing workingMemory first)
      * Tier 3: derive from request fields or other memories
      */
@@ -142,7 +140,7 @@ function buildWorkingMemory(request, existingWorkingMemory, otherMemories) {
 }
 /**
  * Resolves template parameters with smart fallback logic
- * Priority: Request args (tier 1) -> Memory component (tier 2) -> Gateway config (tier 3) -> defaults
+ * Priority: request.workingMemory -> memoryManager resolution -> buildWorkingMemory merge
  */
 async function resolveTemplateParams(request, config, logger) {
     // Tier 1: Request args (highest priority)
@@ -193,19 +191,7 @@ async function resolveTemplateParams(request, config, logger) {
     // Build proper workingMemory structure (merge with request fields if needed)
     // This implements tiered token resolution: tier 2 (workingMemory) and tier 3 (derive from request fields)
     const finalWorkingMemory = buildWorkingMemory(request, workingMemory);
-    // Merge templateTokens (tier 1 - highest priority) into shortTermMemory AFTER memory resolution
-    // This ensures templateTokens override everything (workingMemory and other memories)
-    // 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.identity.jobId,
-            tokenKeys: Object.keys(request.templateTokens)
-        });
-    }
-    // Note: taskConfig removed - Rendrix 3.0.0+ no longer accepts it
-    // taskConfig is deprecated and no longer used
     return {
         workingMemory: finalWorkingMemory
-        // taskConfig removed - Rendrix 3.0.0+ no longer uses it
     };
 }

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

@@ -10,7 +10,6 @@ type Request = ChatRequest | AIRequest;
  * Merges existing workingMemory (from request or memory component) with request metadata
  *
  * Implements tiered token resolution:
- * - Tier 1 (highest): templateTokens (handled in resolveTemplateParams, merged into shortTermMemory)
  * - Tier 2: workingMemory (this method) - checks existing workingMemory first
  * - Tier 3: derived from request fields or other memories (fallback)
  */
@@ -27,7 +26,7 @@ export declare function buildWorkingMemory(request: Request, existingWorkingMemo
 }): unknown;
 /**
  * Resolves template parameters with smart fallback logic
- * Priority: Request args (tier 1) -> Memory component (tier 2) -> Gateway config (tier 3) -> defaults
+ * Priority: request.workingMemory -> memoryManager resolution -> buildWorkingMemory merge
  */
 export declare function resolveTemplateParams(request: Request, config: GatewayConfig, logger: Logxer): Promise<{
     workingMemory: unknown;

package/dist-cjs/gateway-meta.cjs

@@ -30,8 +30,11 @@ async function testInstructions(instructions, testInput, expectedSchema, options
     const testRequest = {
         aiRequestId,
         agentId,
+        actionType: 'skill',
+        actionRef: 'gateway-meta/test-instructions',
         instructions,
         identity: runtimeIdentity,
+        prompt: '{{input}}',
         workingMemory: { input: testInput },
         config: {
             model,