@x12i/ai-gateway 9.0.9 → 9.1.0

package/dist-cjs/gateway-utils.cjs

@@ -37,12 +37,14 @@ 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.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 +226,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 +358,27 @@ function extractCostUsdFromRouterResponse(routerResponse) {
     }
     return 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

@@ -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,10 @@ 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;
+/** 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,7 +516,15 @@ 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 enhancedResponse = {
@@ -567,11 +575,20 @@ class AIGateway {
             // 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