@x12i/ai-gateway 10.4.4 → 11.0.1

package/dist/troubleshooting-helper.js

@@ -195,7 +195,10 @@ export function validateAIRequest(request) {
         errors.push('instructions is required');
     }
     if (!request.prompt) {
-        errors.push('Prompt is required (input field has been removed - use workingMemory.input instead)');
+        const wmInput = request.workingMemory?.input;
+        if (wmInput === undefined || wmInput === null) {
+            errors.push('prompt or workingMemory.input is required for the user turn');
+        }
     }
     // Validate config
     if (!request.config) {
@@ -581,7 +584,7 @@ export function createValidationTestCases() {
             expectedErrors: ['instructions is required']
         },
         {
-            name: 'Missing prompt',
+            name: 'Missing prompt and workingMemory.input',
             request: {
                 aiRequestId: 'ai-no-prompt',
                 agentId: 'agent-1',
@@ -589,11 +592,11 @@ export function createValidationTestCases() {
                 actionRef: 'validation/x',
                 identity: sampleIdentity('test', 'agent-1'),
                 instructions: 'Test',
-                workingMemory: { input: 'Test' },
+                workingMemory: {},
                 config: { model: 'gpt-4o', provider: 'openai' }
             },
             shouldFail: true,
-            expectedErrors: ['Prompt is required (input field has been removed - use workingMemory.input instead)']
+            expectedErrors: ['prompt or workingMemory.input is required for the user turn']
         },
         {
             name: 'Missing actionRef',

package/dist/types.d.ts

@@ -933,15 +933,11 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      */
     coreSkillId?: string;
     /**
-     * Prompt template text (optional) — parsed with workingMemory and tier memories.
+     * Prompt template text (optional) — parsed with workingMemory and sent as the user turn.
+     * When omitted, workingMemory.input is serialized as the user message.
      * Use variables such as {{input}} resolved from workingMemory.input.
      */
     prompt?: string;
-    /**
-     * Context text (optional) - Template that can use workingMemory
-     * Added as system message between instructions and prompt
-     */
-    context?: string;
     /**
      * Working memory (optional) - Affects all template parsing
      * Passed to Rendrix (v4+) for template variable substitution.
@@ -1042,7 +1038,7 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
  * - agentId: Required to identify the agent
  * - instructions: Required (template text)
  *
- * Minimum: instructions + prompt (prompt is required for user message)
+ * Minimum: instructions + (prompt or workingMemory.input)
  *
  * Note: objectTypes is NOT supported in ChatRequest.
  * Use {@link AIInvokeRequest} with invoke() for structured output requests.

package/dist-cjs/activity-manager.cjs

@@ -549,7 +549,6 @@ export class ActivityManager {
         // Build request object snapshots (raw = incoming; parsed = constructed messages/meta)
         const rawSnapshot = request._rawRequest ?? {
             instructions: request.instructions,
-            context: request.context,
             prompt: request.prompt,
             messages: request.messages,
             workingMemory: request.workingMemory,
@@ -559,31 +558,26 @@ export class ActivityManager {
         const requestData = {};
         // raw snapshot (only allowed fields)
         if (rawSnapshot.instructions !== undefined ||
-            rawSnapshot.context !== undefined ||
             rawSnapshot.prompt !== undefined) {
             requestData.raw = {
                 instructions: rawSnapshot.instructions,
-                context: rawSnapshot.context,
                 prompt: rawSnapshot.prompt
             };
         }
         // parsed snapshot (only allowed fields)
         // Ensure parsed is populated if parsedSnapshot has data, even if individual fields are undefined
         if (parsedSnapshot.instructions !== undefined ||
-            parsedSnapshot.context !== undefined ||
             parsedSnapshot.prompt !== undefined) {
             requestData.parsed = {
                 instructions: parsedSnapshot.instructions,
-                context: parsedSnapshot.context,
                 prompt: parsedSnapshot.prompt
             };
         }
         else if (Object.keys(parsedSnapshot).length > 0) {
-            // If parsedSnapshot exists but doesn't have instructions/context/prompt,
+            // If parsedSnapshot exists but doesn't have instructions/prompt,
             // still create parsed with what's available (mirror of raw request after processing)
             requestData.parsed = {
                 instructions: rawSnapshot.instructions,
-                context: rawSnapshot.context,
                 prompt: rawSnapshot.prompt
             };
         }
@@ -631,11 +625,9 @@ export class ActivityManager {
         // Only attach if any field is present
         const hasRequest = (requestData.raw &&
             (requestData.raw.instructions !== undefined ||
-                requestData.raw.context !== undefined ||
                 requestData.raw.prompt !== undefined)) ||
             (requestData.parsed &&
                 (requestData.parsed.instructions !== undefined ||
-                    requestData.parsed.context !== undefined ||
                     requestData.parsed.prompt !== undefined)) ||
             requestData.messages !== undefined ||
             requestData.workingMemory !== undefined ||
@@ -750,7 +742,6 @@ export class ActivityManager {
         // Build request object snapshots (same as startActivity)
         const rawSnapshot = request._rawRequest ?? {
             instructions: request.instructions,
-            context: request.context,
             prompt: request.prompt,
             messages: request.messages,
             workingMemory: request.workingMemory,
@@ -760,21 +751,17 @@ export class ActivityManager {
         const requestData = {};
         // raw snapshot
         if (rawSnapshot.instructions !== undefined ||
-            rawSnapshot.context !== undefined ||
             rawSnapshot.prompt !== undefined) {
             requestData.raw = {
                 instructions: rawSnapshot.instructions,
-                context: rawSnapshot.context,
                 prompt: rawSnapshot.prompt
             };
         }
         // parsed snapshot
         if (parsedSnapshot.instructions !== undefined ||
-            parsedSnapshot.context !== undefined ||
             parsedSnapshot.prompt !== undefined) {
             requestData.parsed = {
                 instructions: parsedSnapshot.instructions,
-                context: parsedSnapshot.context,
                 prompt: parsedSnapshot.prompt
             };
         }
@@ -802,20 +789,17 @@ export class ActivityManager {
             requestData.workingMemory = rawSnapshot.workingMemory;
         }
         // Add skill-specific request structure
-        if (rawSnapshot.workingMemory || rawSnapshot.context) {
+        if (rawSnapshot.workingMemory) {
             requestData.skill = {
-                variables: rawSnapshot.workingMemory,
-                context: rawSnapshot.context
+                variables: rawSnapshot.workingMemory
             };
         }
         // Only attach if any field is present
         const hasRequest = (requestData.raw &&
             (requestData.raw.instructions !== undefined ||
-                requestData.raw.context !== undefined ||
                 requestData.raw.prompt !== undefined)) ||
             (requestData.parsed &&
                 (requestData.parsed.instructions !== undefined ||
-                    requestData.parsed.context !== undefined ||
                     requestData.parsed.prompt !== undefined)) ||
             requestData.messages !== undefined ||
             requestData.workingMemory !== undefined ||

package/dist-cjs/gateway-memory.cjs

@@ -104,10 +104,6 @@ export function buildWorkingMemory(request, existingWorkingMemory, otherMemories
     if (!workingMemory.job.objective && request.instructions) {
         workingMemory.job.objective = request.instructions;
     }
-    if (!workingMemory.job.context && request.context) {
-        workingMemory.job.context = request.context;
-    }
-    // Input field has been removed - data should come from workingMemory.input
     if (!workingMemory.job.narrative && request.prompt) {
         workingMemory.job.narrative = request.prompt;
     }
@@ -118,9 +114,6 @@ export function buildWorkingMemory(request, existingWorkingMemory, otherMemories
     if (!workingMemory.task.objective && request.instructions) {
         workingMemory.task.objective = request.instructions;
     }
-    if (!workingMemory.task.context && request.context) {
-        workingMemory.task.context = request.context;
-    }
     // Input field has been removed - data should come from workingMemory.input
     if (!workingMemory.task.id && request.identity.taskId) {
         workingMemory.task.id = request.identity.taskId;

package/dist-cjs/gateway-messages.cjs

@@ -13,21 +13,17 @@ function isAIRequest(request) {
         'reasoningEncrypted' in request;
 }
 /**
- * Constructs messages from instructions/prompt/input/context
+ * Constructs messages from instructions and prompt (two-message contract).
  *
  * Uses direct message builder which handles:
- * - Token resolution (3-tier system)
  * - Template parsing (via Rendrix, @x12i/rendrix)
- * - Instruction block resolution and composition
- * - Flex-md format specification
- * - Message assembly
+ * - Message assembly: system (instructions) + user (prompt or input fallback)
  */
 export async function constructMessages(request, config, logger, parsedSnapshot) {
     logger.verbose('Constructing messages from request', {
         jobId: request.identity.jobId,
         agentId: request.agentId,
         hasInstructions: !!request.instructions,
-        hasContext: !!request.context,
         hasPrompt: !!request.prompt,
         hasWorkingMemory: !!request.workingMemory
     });

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

@@ -7,14 +7,11 @@ import type { Logxer } from '@x12i/logxer';
 import { type MessageBuilderConfig } from './message-builder.js';
 type Request = ChatRequest | AIRequest;
 /**
- * Constructs messages from instructions/prompt/input/context
+ * Constructs messages from instructions and prompt (two-message contract).
  *
  * Uses direct message builder which handles:
- * - Token resolution (3-tier system)
  * - Template parsing (via Rendrix, @x12i/rendrix)
- * - Instruction block resolution and composition
- * - Flex-md format specification
- * - Message assembly
+ * - Message assembly: system (instructions) + user (prompt or input fallback)
  */
 export declare function constructMessages(request: Request, config: MessageBuilderConfig, logger: Logxer, parsedSnapshot?: any): Promise<Array<{
     role: string;

package/dist-cjs/gateway-utils.cjs

@@ -209,7 +209,7 @@ export async function mergeConfig(request, config, logger, mergeOptions) {
     });
     if (serverToolsPolicy.forceOpenRouter) {
         merged.provider = 'openrouter';
-        logger.verbose('Required OpenRouter server tool forced provider=openrouter', {
+        logger.verbose('OpenRouter server tool forced provider=openrouter', {
             jobId: request.identity.jobId,
         });
     }

package/dist-cjs/gateway-validation.cjs

@@ -2,6 +2,17 @@
  * Gateway Validation Module
  * Basic validation for clean proxy implementation
  */
+function rejectRemovedContextField(request) {
+    if ('context' in request && request.context !== undefined) {
+        const err = new Error(`The 'context' field has been removed. Context is not sent to the LLM. Merge background data into workingMemory upstream and use the prompt template for the user turn.`);
+        err.code = 'CONTEXT_FIELD_REMOVED';
+        err.details = {
+            field: 'context',
+            alternative: 'workingMemory + prompt template'
+        };
+        throw err;
+    }
+}
 function validateMandatoryRuntimeIdentity(request) {
     const id = request.identity;
     if (id === undefined || id === null || typeof id !== 'object') {
@@ -20,6 +31,7 @@ export function validateChatRequest(request) {
         throw new Error('agentId is required');
     }
     validateMandatoryRuntimeIdentity(request);
+    rejectRemovedContextField(request);
     // 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.`);
@@ -44,6 +56,7 @@ export function validateAIRequest(request) {
         throw new Error('agentId is required for AI requests');
     }
     validateMandatoryRuntimeIdentity(request);
+    rejectRemovedContextField(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(', ')}`);

package/dist-cjs/gateway.cjs

@@ -93,8 +93,54 @@ export class AIGateway {
             const startTime = Date.now();
             // Generate simple task type ID
             const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
-            // Simple message construction
-            const messages = this.buildSimpleMessages(request);
+            const parsedSnapshot = {};
+            let messages = [];
+            try {
+                const builtMessages = await buildMessages(request, this.messageBuilderConfig, {
+                    parsedSnapshot
+                });
+                messages = builtMessages.messages;
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                const endTime = Date.now();
+                const duration = endTime - startTime;
+                const errWithCode = err;
+                const isResolutionError = err.name === 'InstructionNotFoundError' ||
+                    err.name === 'InstructionBackendError' ||
+                    err.name === 'TemplateResolutionError' ||
+                    errWithCode.code === 'PROMPT_NOT_FOUND' ||
+                    errWithCode.code === 'PROMPT_RESOLUTION_ERROR' ||
+                    errWithCode.code === 'PROMPT_RENDERED_EMPTY' ||
+                    errWithCode.code === 'TEMPLATE_RESOLUTION_ERROR' ||
+                    errWithCode.code === 'TEMPLATE_VARIABLE_MISSING' ||
+                    errWithCode.code === 'USER_CONTENT_REQUIRED' ||
+                    err.message.includes('Failed to resolve') ||
+                    err.message.includes('Failed to render prompt template') ||
+                    err.message.includes('not found') ||
+                    err.message.includes('Instruction not found') ||
+                    err.message.includes('Prompt not found');
+                if (isResolutionError && this.activityManager) {
+                    await this.activityManager.logBadRequest(request, err, {
+                        endTime,
+                        duration,
+                        error: err.message,
+                        errorType: errWithCode.code || 'MessageBuildError',
+                        diagnosticInfo: {
+                            errorCode: errWithCode.code,
+                            errorName: err.name,
+                            failureType: 'validation-failure',
+                            stage: 'message-building',
+                            prompt: request.prompt,
+                            instructions: typeof request.instructions === 'string' ? request.instructions.substring(0, 100) : '(object)'
+                        },
+                        failureType: 'validation-failure'
+                    }, startTime);
+                }
+                throw err;
+            }
+            parsedSnapshot.messages = messages;
+            request._parsedRequest = parsedSnapshot;
             // Merge config (modelConfig > request.config > gateway defaults)
             const aiTools = await this.getAiTools();
             const mergedConfig = await mergeConfig(request, this.config, this.logger, {
@@ -247,6 +293,7 @@ export class AIGateway {
                     errWithCode.code === 'PROMPT_RENDERED_EMPTY' ||
                     errWithCode.code === 'TEMPLATE_RESOLUTION_ERROR' ||
                     errWithCode.code === 'TEMPLATE_VARIABLE_MISSING' ||
+                    errWithCode.code === 'USER_CONTENT_REQUIRED' ||
                     err.message.includes('Failed to resolve') ||
                     err.message.includes('Failed to render prompt template') ||
                     err.message.includes('not found') ||
@@ -284,9 +331,6 @@ export class AIGateway {
             parsedSnapshot.messages = messages;
             // parsed.instructions and parsed.prompt are set by buildMessages to the resolved/rendered content
             // (after key resolution and Rendrix). Do not overwrite with raw request keys.
-            if (parsedSnapshot.context === undefined) {
-                parsedSnapshot.context = request.context;
-            }
             // Attach parsedSnapshot to request for activity tracking
             request._parsedRequest = parsedSnapshot;
             // Merge config (modelConfig > request.config > gateway defaults)
@@ -775,37 +819,6 @@ export class AIGateway {
             }
         });
     }
-    /**
-     * Build simple messages from request (instructions and prompt as literal template text; no registry).
-     */
-    buildSimpleMessages(request) {
-        const messages = [];
-        // Add instructions as system message if present
-        if (request.instructions) {
-            const instructions = typeof request.instructions === 'string'
-                ? request.instructions
-                : 'Default instructions';
-            messages.push({ role: 'system', content: instructions });
-        }
-        // Add context as assistant message if present
-        if (request.context) {
-            const context = typeof request.context === 'string'
-                ? request.context
-                : JSON.stringify(request.context);
-            messages.push({ role: 'assistant', content: context });
-        }
-        // Add prompt/input as user message
-        // Input field has been removed - prompt template should contain {{input}} which resolves from workingMemory.input
-        const userContent = request.prompt || '';
-        if (userContent) {
-            messages.push({ role: 'user', content: userContent });
-        }
-        // Add direct messages if present
-        if (request.messages) {
-            messages.push(...request.messages);
-        }
-        return messages;
-    }
     // Provider management methods
     register(provider) {
         this.router.registerProvider(provider);

package/dist-cjs/gateway.d.ts

@@ -29,10 +29,6 @@ export declare class AIGateway {
      * Invoke AI request (with structured output support)
      */
     invoke<TContent = unknown>(request: AIInvokeRequest): Promise<EnhancedLLMResponse<TContent>>;
-    /**
-     * Build simple messages from request (instructions and prompt as literal template text; no registry).
-     */
-    private buildSimpleMessages;
     register(provider: any): void;
     listProviders(): string[];
     getRouter(): LLMProviderRouter;