@x12i/ai-gateway 7.9.1

package/dist/message-builder.js

@@ -0,0 +1,522 @@
+/**
+ * Message Builder
+ * Direct message construction without request-builder package dependency
+ * Handles flex-md format exclusively
+ */
+import { parseTemplate } from './template-parser.js';
+import { mergeTemplateRenderOptions } from './template-render-merge.js';
+import { resolveNestedInstructionsBlock } from './gateway-instructions.js';
+// Type guard
+// AIRequest is distinguished by having primaryObjectType or objectTypes
+// ChatRequest does not have these fields
+function isAIRequest(request) {
+    return 'primaryObjectType' in request || ('objectTypes' in request && Array.isArray(request.objectTypes));
+}
+/**
+ * Builds input recognition rules
+ */
+async function buildInputRecognitionRules(request, config, options) {
+    const { defaultInstructionsBlocks, instructionsBlockOverrides, logger } = config;
+    if (!options.includeInputRecognition || !isAIRequest(request)) {
+        return '';
+    }
+    const rules = [];
+    // Add input recognition rules
+    // Try direct access first (faster, more reliable), then fallback to resolver
+    const rulePaths = [
+        'input.inputRecognitionRule',
+        'input.emptyInputHandling',
+        'input.testInputHandling',
+        'input.inputLocationClarifier'
+    ];
+    const requestInstructionsBlocks = isAIRequest(request) && request.config?.instructionsBlocks
+        ? request.config.instructionsBlocks
+        : undefined;
+    const blockContext = {
+        defaultInstructionsBlocks,
+        instructionsBlockOverrides,
+        requestInstructionsBlocks,
+        config: {},
+        logger
+    };
+    for (const rulePath of rulePaths) {
+        try {
+            // Try direct access to nested structure first
+            const pathParts = rulePath.split('.');
+            let rule;
+            if (pathParts.length === 2) {
+                const [parent, child] = pathParts;
+                const parentObj = defaultInstructionsBlocks[parent];
+                if (parentObj && typeof parentObj === 'object' && !Array.isArray(parentObj)) {
+                    rule = parentObj[child];
+                    if (rule && typeof rule === 'string') {
+                        logger.debug('Resolved rule via direct access', {
+                            rulePath,
+                            valueLength: rule.length
+                        });
+                    }
+                }
+            }
+            // If direct access didn't work, try merged inline overrides / nested defaults
+            if (!rule) {
+                rule = await resolveNestedInstructionsBlock(rulePath, request.agentId || '', request.taskTypeId, blockContext);
+            }
+            if (rule && typeof rule === 'string' && rule.trim() !== '') {
+                rules.push(rule);
+            }
+        }
+        catch (error) {
+            logger.debug('Failed to resolve input rule', {
+                rulePath,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return rules.join('\n\n');
+}
+/**
+ * Builds reinforcement rules
+ */
+async function buildReinforcementRules(request, config, options) {
+    const { defaultInstructionsBlocks, instructionsBlockOverrides, logger } = config;
+    if (!options.includeReinforcement || !isAIRequest(request)) {
+        return '';
+    }
+    const rules = [];
+    // Add reinforcement rules
+    // Try direct access first (faster, more reliable), then fallback to resolver
+    const rulePaths = [
+        'reinforcement.emptyIsSuccess',
+        'reinforcement.inputAlreadyProvided',
+        'reinforcement.noConversation',
+        'reinforcement.failureIndicators'
+    ];
+    const requestInstructionsBlocks = isAIRequest(request) && request.config?.instructionsBlocks
+        ? request.config.instructionsBlocks
+        : undefined;
+    const blockContext = {
+        defaultInstructionsBlocks,
+        instructionsBlockOverrides,
+        requestInstructionsBlocks,
+        config: {},
+        logger
+    };
+    for (const rulePath of rulePaths) {
+        try {
+            // Try direct access to nested structure first
+            const pathParts = rulePath.split('.');
+            let rule;
+            if (pathParts.length === 2) {
+                const [parent, child] = pathParts;
+                const parentObj = defaultInstructionsBlocks[parent];
+                if (parentObj && typeof parentObj === 'object' && !Array.isArray(parentObj)) {
+                    rule = parentObj[child];
+                    if (rule && typeof rule === 'string') {
+                        logger.debug('Resolved rule via direct access', {
+                            rulePath,
+                            valueLength: rule.length
+                        });
+                    }
+                }
+            }
+            // If direct access didn't work, try merged inline overrides / nested defaults
+            if (!rule) {
+                rule = await resolveNestedInstructionsBlock(rulePath, request.agentId || '', request.taskTypeId, blockContext);
+            }
+            if (rule && typeof rule === 'string' && rule.trim() !== '') {
+                rules.push(rule);
+            }
+        }
+        catch (error) {
+            logger.debug('Failed to resolve reinforcement rule', {
+                rulePath,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return rules.join('\n\n');
+}
+/**
+ * Builds user message (prompt + input)
+ */
+async function buildUserMessage(request, config, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions) {
+    const { logger } = config;
+    const parts = [];
+    // Validate that input field is not provided (removed - use workingMemory.input instead)
+    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.`);
+        err.code = 'INPUT_FIELD_DEPRECATED';
+        err.details = {
+            field: 'input',
+            alternative: 'workingMemory.input',
+            message: 'Input data must be provided via workingMemory.input for template rendering'
+        };
+        logger.error('Input field provided but has been removed', {
+            jobId: request.jobId,
+            agentId: request.agentId,
+            errorCode: 'INPUT_FIELD_DEPRECATED',
+            hasPrompt: !!request.prompt,
+            hasWorkingMemory: !!request.workingMemory,
+            hasInputInWorkingMemory: !!request.workingMemory?.input
+        });
+        throw err;
+    }
+    // Determine if we have user content to process (prompt is required for user message)
+    const hasUserContent = isAIRequest(request) && request.prompt;
+    // Input prefix is no longer used - prompt templates handle all formatting
+    // If no prompt is provided, that's an error (prompt is required for user message)
+    if (isAIRequest(request) && !request.prompt) {
+        const err = new Error(`Prompt is required for AI requests. Provide prompt template text. The template should contain variables such as {{input}} resolved from workingMemory.input.`);
+        err.code = 'PROMPT_REQUIRED';
+        err.details = {
+            missingField: 'prompt',
+            hasWorkingMemory: !!request.workingMemory,
+            hasInputInWorkingMemory: !!request.workingMemory?.input
+        };
+        logger.error('Prompt is required for AI requests', {
+            jobId: request.jobId,
+            agentId: request.agentId,
+            errorCode: 'PROMPT_REQUIRED'
+        });
+        throw err;
+    }
+    // Add prompt if provided (always template text; parsed with memory context)
+    if (request.prompt) {
+        if (typeof request.prompt === 'string') {
+            logger.info('Parsing prompt template text', {
+                jobId: request.jobId,
+                agentId: request.agentId,
+                promptLength: request.prompt.length,
+                promptPreview: request.prompt.substring(0, 200),
+                hasWorkingMemory: !!request.workingMemory
+            });
+            try {
+                if (!request.workingMemory) {
+                    const err = new Error(`workingMemory is required for prompt template rendering but was not provided.`);
+                    err.code = 'WORKING_MEMORY_REQUIRED';
+                    err.details = { requiresVariables: true };
+                    logger.error('workingMemory required for prompt template rendering', {
+                        jobId: request.jobId,
+                        agentId: request.agentId,
+                        errorCode: 'WORKING_MEMORY_REQUIRED'
+                    });
+                    throw err;
+                }
+                const parsedPrompt = await parseTemplate(request.prompt, request.workingMemory, undefined, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+                if (!parsedPrompt || parsedPrompt.trim() === '') {
+                    const workingMemoryObj = request.workingMemory;
+                    const err = new Error(`Prompt template rendered to empty string. This may indicate missing template variables or empty template content.`);
+                    err.code = 'PROMPT_RENDERED_EMPTY';
+                    err.details = {
+                        promptLength: request.prompt.length,
+                        renderedLength: 0,
+                        hasWorkingMemory: !!request.workingMemory,
+                        workingMemoryKeys: workingMemoryObj ? Object.keys(workingMemoryObj) : []
+                    };
+                    logger.error('Prompt template rendered to empty string', {
+                        jobId: request.jobId,
+                        agentId: request.agentId,
+                        errorCode: 'PROMPT_RENDERED_EMPTY',
+                        hasWorkingMemory: !!request.workingMemory,
+                        workingMemoryKeys: workingMemoryObj ? Object.keys(workingMemoryObj) : []
+                    });
+                    throw err;
+                }
+                logger.info('Prompt text parsed successfully', {
+                    jobId: request.jobId,
+                    agentId: request.agentId,
+                    originalLength: request.prompt.length,
+                    parsedLength: parsedPrompt.length,
+                    parsedPreview: parsedPrompt.substring(0, 200)
+                });
+                parts.push(parsedPrompt);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                let errorCode = 'PROMPT_TEMPLATE_ERROR';
+                let errorMessage = `Failed to render prompt template: ${err.message}`;
+                if (err.message.includes('not found') || err.message.includes('does not exist')) {
+                    errorCode = 'PROMPT_NOT_FOUND';
+                    errorMessage = err.message;
+                }
+                else if (err.message.includes('rendered to empty')) {
+                    errorCode = 'PROMPT_RENDERED_EMPTY';
+                    errorMessage = err.message;
+                }
+                else if (err.name === 'TemplateResolutionError') {
+                    errorCode = 'TEMPLATE_RESOLUTION_ERROR';
+                    errorMessage = err.message;
+                }
+                else if (err.message.includes('Template variable') || err.message.includes('missing')) {
+                    errorCode = 'TEMPLATE_VARIABLE_MISSING';
+                    errorMessage = err.message;
+                }
+                logger.error('Failed to render prompt template', {
+                    jobId: request.jobId,
+                    agentId: request.agentId,
+                    errorCode,
+                    error: err.message,
+                    errorName: err.name,
+                    errorStack: err.stack
+                });
+                const structuredError = new Error(errorMessage);
+                structuredError.code = errorCode;
+                structuredError.details = {
+                    type: 'prompt',
+                    originalError: err.message
+                };
+                throw structuredError;
+            }
+        }
+        else {
+            const err = new Error(`Prompt must be a string template, but received: ${typeof request.prompt}`);
+            logger.error('Prompt provided as non-string - not supported', {
+                jobId: request.jobId,
+                agentId: request.agentId,
+                promptType: typeof request.prompt
+            });
+            throw err;
+        }
+    }
+    // Input field has been removed - all input must come from workingMemory.input
+    // Prompt templates should contain {{input}} which will be resolved from workingMemory.input
+    // No need to add input separately - it's already in the rendered prompt template
+    const userMessage = parts.join('\n\n');
+    // If prompt was provided, we MUST have a non-empty user message
+    if (request.prompt && (!userMessage || userMessage.trim() === '')) {
+        const err = new Error(`Prompt template was provided but resulted in empty user message. The template may have rendered to empty or failed to resolve.`);
+        err.code = 'PROMPT_NO_USER_MESSAGE';
+        err.details = {
+            promptPreview: typeof request.prompt === 'string' ? request.prompt.substring(0, 200) : request.prompt,
+            hasWorkingMemory: !!request.workingMemory,
+            workingMemoryKeys: request.workingMemory ? Object.keys(request.workingMemory) : [],
+            partsLength: parts.length
+        };
+        logger.error('Prompt provided but resulted in empty user message', {
+            jobId: request.jobId,
+            agentId: request.agentId,
+            prompt: request.prompt,
+            errorCode: 'PROMPT_NO_USER_MESSAGE',
+            partsLength: parts.length,
+            parts: parts.map(p => ({ length: p.length, preview: p.substring(0, 50) }))
+        });
+        throw err;
+    }
+    return userMessage;
+}
+/**
+ * Checks if instructions already meet the required flex-md compliance level
+ * Uses flex-md SDK to validate compliance
+ *
+ * @param instructionsText - Instructions to check
+ * @param complianceLevel - Required compliance level (L0, L1, L2, L3)
+ * @returns true if instructions meet the compliance level
+ */
+async function hasFlexMdContract(instructionsText, complianceLevel = 'L0') {
+    if (!instructionsText || instructionsText.trim() === '') {
+        return false;
+    }
+    try {
+        // Try to use flex-md SDK to validate compliance
+        const { loadFlexMd } = await import('./flex-md-loader.js');
+        const flexMd = await loadFlexMd();
+        // Check if validateMarkdownAgainstOfs is available
+        if (flexMd.validateMarkdownAgainstOfs && typeof flexMd.validateMarkdownAgainstOfs === 'function') {
+            try {
+                // Try to validate - this might require a spec, so we catch errors
+                const result = flexMd.validateMarkdownAgainstOfs(instructionsText, { strictness: complianceLevel });
+                // If validation passes, instructions meet compliance
+                if (result && result.valid !== false) {
+                    return true;
+                }
+            }
+            catch (e) {
+                // Validation function might need more parameters, fall through to pattern matching
+            }
+        }
+    }
+    catch (error) {
+        // flex-md SDK not available or error - fall through to pattern matching
+    }
+    // Fallback: Pattern-based checking
+    const text = instructionsText.toLowerCase();
+    // Check for key flex-md enforcement phrases
+    const flexMdIndicators = [
+        'markdown',
+        'fenced block',
+        '```markdown',
+        '```json',
+        'reply in markdown',
+        'return your entire answer'
+    ];
+    // Check for enforcement language based on compliance level
+    const enforcementIndicators = [];
+    if (complianceLevel === 'L2' || complianceLevel === 'L3') {
+        // L2/L3 require fenced block container
+        enforcementIndicators.push('fenced block', '```markdown', 'single ```markdown', 'entire answer inside', 'nothing else');
+    }
+    if (complianceLevel === 'L1' || complianceLevel === 'L2' || complianceLevel === 'L3') {
+        // L1+ requires section headings
+        enforcementIndicators.push('section', 'heading', 'include these');
+    }
+    // Must have at least one flex-md indicator AND appropriate enforcement indicators
+    const hasFlexMd = flexMdIndicators.some(indicator => text.includes(indicator));
+    const hasEnforcement = enforcementIndicators.length === 0 ||
+        enforcementIndicators.some(indicator => text.includes(indicator));
+    return hasFlexMd && hasEnforcement;
+}
+/**
+ * Main function to build messages
+ */
+export async function buildMessages(request, config, options = {}) {
+    const { useSystemContextFallback = true, includeInputRecognition = true, includeReinforcement = true, parsedSnapshot } = options;
+    const { logger } = config;
+    const messages = [];
+    let usingSystemContext = false;
+    // Step 1: Instructions as template text (parsed with full memory context)
+    let instructionsText = '';
+    // Extract memory context from options
+    const shortTermMemory = options.shortTermMemory;
+    const experienceMemory = options.experienceMemory;
+    const knowledgeMemory = options.knowledgeMemory;
+    const templateRenderOptions = mergeTemplateRenderOptions(config.templateRendering, request.templateRenderOptions);
+    if (request.instructions) {
+        if (typeof request.instructions === 'string') {
+            logger.info('Using instructions as template text', {
+                jobId: request.jobId,
+                agentId: request.agentId,
+                instructionsLength: request.instructions.length,
+                instructionsPreview: request.instructions.substring(0, 200)
+            });
+            instructionsText = request.instructions;
+        }
+        else {
+            instructionsText = JSON.stringify(request.instructions);
+        }
+    }
+    // NO SYSTEM CONTEXT FALLBACK - removed default instruction fallback
+    // Instructions must be provided explicitly - no defaults allowed
+    // If instructionsText is empty here, it's a bad request
+    // Step 2: Parse instructions template with full memory context
+    // Rendrix handles token resolution, so we just parse directly
+    if (instructionsText) {
+        instructionsText = await parseTemplate(instructionsText, request.workingMemory, undefined, // taskConfig removed - no longer used
+        shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+    }
+    // Step 4: Add input recognition rules
+    const inputRules = await buildInputRecognitionRules(request, config, options);
+    if (inputRules) {
+        instructionsText = `${instructionsText}\n\n${inputRules}`;
+    }
+    // Step 5: Add reinforcement rules
+    const reinforcementRules = await buildReinforcementRules(request, config, options);
+    if (reinforcementRules) {
+        instructionsText = `${instructionsText}\n\n${reinforcementRules}`;
+    }
+    // Step 6: Add system message
+    // CRITICAL: We must have instructions - this is a bad request if we don't
+    if (!instructionsText || instructionsText.trim() === '') {
+        const errorMessage = 'No instructions available - cannot proceed without clear instructions. This is a bad request.';
+        logger.error(errorMessage, {
+            jobId: request.jobId,
+            agentId: request.agentId,
+            hasRequestInstructions: !!request.instructions,
+            instructionType: typeof request.instructions,
+            usedSystemContextFallback: usingSystemContext,
+            systemContextFallbackEnabled: useSystemContextFallback
+        });
+        throw new Error(errorMessage);
+    }
+    messages.push({
+        role: 'system',
+        content: instructionsText
+    });
+    // Store resolved/parsed content for activity (parsed = content after resolution + Rendrix, not the key)
+    if (parsedSnapshot) {
+        parsedSnapshot.instructions = instructionsText;
+    }
+    // Log the final system message for verification
+    logger.info('Final system message constructed', {
+        jobId: request.jobId,
+        agentId: request.agentId,
+        messageLength: instructionsText.length,
+        hasMarkdown: instructionsText.toLowerCase().includes('markdown'),
+        hasFencedBlock: instructionsText.includes('```markdown'),
+        hasJson: instructionsText.toLowerCase().includes('json'),
+        messagePreview: instructionsText.substring(0, 500),
+        fullMessage: instructionsText // Log full message for debugging
+    });
+    // Step 7: Add context (if provided) with full memory context
+    if (request.context) {
+        const contextText = typeof request.context === 'string' ? request.context : JSON.stringify(request.context);
+        const parsedContext = await parseTemplate(contextText, request.workingMemory, undefined, // taskConfig removed - no longer used
+        shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+        if (parsedContext && parsedContext.trim() !== '') {
+            messages.push({
+                role: 'assistant',
+                content: parsedContext
+            });
+        }
+    }
+    // Step 8: Build user message with full memory context
+    const userMessage = await buildUserMessage(request, config, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+    if (userMessage && userMessage.trim() !== '') {
+        messages.push({
+            role: 'user',
+            content: userMessage
+        });
+        // Store resolved/parsed prompt for activity (parsed = content after resolution + Rendrix, not the key)
+        if (parsedSnapshot) {
+            parsedSnapshot.prompt = userMessage;
+        }
+        // Log the user message for verification
+        logger.info('Final user message constructed', {
+            jobId: request.jobId,
+            agentId: request.agentId,
+            messageLength: userMessage.length,
+            messagePreview: userMessage.substring(0, 200),
+            fullMessage: userMessage // Log full message for debugging
+        });
+    }
+    else {
+        // If prompt was provided, we MUST have a user message - this is an error
+        if (request.prompt) {
+            const err = new Error(`Prompt template was provided but no user message was created. The template may have rendered to empty or failed to resolve.`);
+            err.code = 'PROMPT_NO_USER_MESSAGE';
+            err.details = {
+                promptPreview: typeof request.prompt === 'string' ? request.prompt.substring(0, 200) : request.prompt,
+                hasWorkingMemory: !!request.workingMemory
+            };
+            logger.error('Prompt provided but no user message created', {
+                jobId: request.jobId,
+                agentId: request.agentId,
+                prompt: request.prompt,
+                errorCode: 'PROMPT_NO_USER_MESSAGE'
+            });
+            throw err;
+        }
+        // If no prompt was provided, it's just a warning (input-only requests are valid)
+        logger.warn('No user message to add', {
+            jobId: request.jobId,
+            agentId: request.agentId,
+            hasPrompt: !!request.prompt
+        });
+    }
+    // Log complete message structure
+    logger.info('Complete message structure', {
+        jobId: request.jobId,
+        agentId: request.agentId,
+        totalMessages: messages.length,
+        systemMessages: messages.filter(m => m.role === 'system').length,
+        userMessages: messages.filter(m => m.role === 'user').length,
+        messageRoles: messages.map(m => m.role),
+        systemMessageLengths: messages.filter(m => m.role === 'system').map(m => m.content.length),
+        userMessageLengths: messages.filter(m => m.role === 'user').map(m => m.content.length)
+    });
+    return {
+        messages,
+        metadata: {
+            usingSystemContext
+        }
+    };
+}

package/dist/object-types-library-integration.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Object Types Library Integration - REMOVED
+ *
+ * The @x12i/outputs-library dependency has been removed.
+ * This file now provides stub functions for backward compatibility.
+ */
+import type { GatewayConfig } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+/**
+ * Initialize ObjectTypesLibrary singleton - STUB
+ * Since ObjectTypesLibrary is removed, this function does nothing
+ */
+export declare function initializeObjectTypesLibrary(config: GatewayConfig, logger: Logxer): Promise<any>;
+/**
+ * Get the current ObjectTypesLibrary instance - STUB
+ * Always returns null since the library is removed
+ */
+export declare function getObjectTypesLibrary(): any;
+/**
+ * Reset the library instance (for testing) - STUB
+ */
+export declare function resetObjectTypesLibrary(): void;

package/dist/object-types-library-integration.js

@@ -0,0 +1,27 @@
+/**
+ * Object Types Library Integration - REMOVED
+ *
+ * The @x12i/outputs-library dependency has been removed.
+ * This file now provides stub functions for backward compatibility.
+ */
+/**
+ * Initialize ObjectTypesLibrary singleton - STUB
+ * Since ObjectTypesLibrary is removed, this function does nothing
+ */
+export async function initializeObjectTypesLibrary(config, logger) {
+    logger.info('ObjectTypesLibrary dependency removed - using simplified object type handling');
+    return null;
+}
+/**
+ * Get the current ObjectTypesLibrary instance - STUB
+ * Always returns null since the library is removed
+ */
+export function getObjectTypesLibrary() {
+    return null;
+}
+/**
+ * Reset the library instance (for testing) - STUB
+ */
+export function resetObjectTypesLibrary() {
+    // Nothing to reset since library is removed
+}