@x12i/ai-gateway 7.9.1

package/dist-cjs/gateway-messages.cjs

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Gateway Messages Module
+ * Handles message construction using direct message builder
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructMessages = constructMessages;
+const message_builder_js_1 = require("./message-builder.cjs");
+// Type guard to check if request is AIRequest
+// AIRequest is distinguished by having primaryObjectType, objectTypes, or other AIRequest-specific fields
+function isAIRequest(request) {
+    return 'primaryObjectType' in request ||
+        ('objectTypes' in request && Array.isArray(request.objectTypes)) ||
+        'skillId' in request ||
+        'masterSkillId' in request ||
+        'reasoningEncrypted' in request;
+}
+/**
+ * Constructs messages from instructions/prompt/input/context
+ *
+ * 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
+ */
+async function constructMessages(request, config, logger, parsedSnapshot) {
+    logger.verbose('Constructing messages from request', {
+        jobId: request.jobId,
+        agentId: request.agentId,
+        hasInstructions: !!request.instructions,
+        hasContext: !!request.context,
+        hasPrompt: !!request.prompt,
+        hasWorkingMemory: !!request.workingMemory
+    });
+    // LOGGING: Construct messages phase (instructions should already be resolved)
+    const traceId = request.jobId || `trace-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const agentId = request.agentId;
+    logger.info('instructions.constructMessages.entry', {
+        traceId,
+        jobId: request.jobId,
+        agentId,
+        'instructionsType': typeof request.instructions,
+        'instructionsLength': typeof request.instructions === 'string' ? request.instructions.length : 'N/A',
+        'hasResolvedText': !!request.resolvedInstructionsText
+    });
+    // Always use flex-md format - no modes needed
+    let finalInstructions = request.instructions;
+    // Add examples for few-shot learning if using standard type
+    if (isAIRequest(request)) {
+        const resolvedType = request._resolvedTypes?.primary;
+        if (resolvedType?.isStandard && resolvedType.definition?.examples) {
+            const examples = resolvedType.definition.examples;
+            if (examples.length > 0) {
+                // Use first 3 examples for few-shot learning
+                const fewShotExamples = examples
+                    .slice(0, 3)
+                    .map((ex) => `Input: ${ex.input}\nOutput: ${ex.output}`)
+                    .join('\n\n');
+                // Append to instructions
+                if (typeof finalInstructions === 'string') {
+                    finalInstructions = `${finalInstructions}\n\nExamples:\n${fewShotExamples}`;
+                    logger.debug('Added few-shot examples to instructions', {
+                        jobId: request.jobId,
+                        exampleCount: Math.min(examples.length, 3),
+                        totalExamples: examples.length
+                    });
+                }
+            }
+        }
+    }
+    // Update request with final instructions (for message builder)
+    const requestWithExamples = { ...request, instructions: finalInstructions };
+    // Build messages using direct message builder
+    const result = await (0, message_builder_js_1.buildMessages)(requestWithExamples, config, {
+        useSystemContextFallback: true,
+        includeInputRecognition: isAIRequest(request),
+        includeReinforcement: isAIRequest(request),
+        parsedSnapshot
+    });
+    if (parsedSnapshot && result.metadata) {
+        parsedSnapshot._requestBuilderMetadata = result.metadata;
+    }
+    return result.messages;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Gateway Messages Module
+ * Handles message construction using direct message builder
+ */
+import type { ChatRequest, AIRequest } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+import { type MessageBuilderConfig } from './message-builder.js';
+type Request = ChatRequest | AIRequest;
+/**
+ * Constructs messages from instructions/prompt/input/context
+ *
+ * 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
+ */
+export declare function constructMessages(request: Request, config: MessageBuilderConfig, logger: Logxer, parsedSnapshot?: any): Promise<Array<{
+    role: string;
+    content: string;
+}>>;
+export {};

package/dist-cjs/gateway-meta.cjs

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * Gateway Meta Operations Module
+ * Handles meta operations like instruction optimization and testing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.testInstructions = testInstructions;
+/**
+ * Test instructions by running them and analyzing the response
+ */
+async function testInstructions(instructions, testInput, expectedSchema, options, config, gateway, logger) {
+    // Get internal system action config (instruction audit)
+    const internalConfig = config.internalSystemActions?.instructionAudit;
+    const defaultEngine = config.defaultEngine || 'openai';
+    const defaultModel = internalConfig?.model || 'gpt-5-nano';
+    const defaultProvider = internalConfig?.engine || defaultEngine;
+    const { agentId = 'instruction-tester', model = options.model || defaultModel, // Use internal config default if not provided
+    provider = options.provider || defaultProvider // Use internal config default if not provided
+     } = options;
+    if (!model) {
+        throw new Error('Model must be provided in options.model or configured as default');
+    }
+    // Create test request with internal system action config
+    const testRequest = {
+        jobId: `test-instructions-${Date.now()}`,
+        agentId,
+        instructions,
+        input: testInput,
+        config: {
+            model,
+            provider,
+            temperature: internalConfig?.temperature ?? 0.7, // Use internal config or default
+            maxTokens: internalConfig?.maxTokens ?? 2000 // Use internal config or default
+        }
+    };
+    // Run the test
+    const response = await gateway.invoke(testRequest);
+    // Analyze the response
+    const analysis = {
+        isValidJson: !!response.parsedContent && typeof response.parsedContent === 'object',
+        matchesSchema: false,
+        hasProse: false,
+        issues: [],
+        qualityScore: 0
+    };
+    // Check for prose
+    const contentStr = response.content || '';
+    const proseIndicators = ["I'm sorry", "Please provide", "Sure!", "Here is", "Let me", "I can", "I'll"];
+    analysis.hasProse = proseIndicators.some(indicator => contentStr.toLowerCase().includes(indicator.toLowerCase()));
+    // Check if matches schema
+    if (expectedSchema && response.parsedContent) {
+        const parsed = response.parsedContent;
+        const schemaKeys = Object.keys(expectedSchema);
+        const responseKeys = Object.keys(parsed);
+        analysis.matchesSchema = schemaKeys.every(key => responseKeys.includes(key));
+    }
+    else if (response.parsedContent) {
+        analysis.matchesSchema = true; // No schema to match against
+    }
+    // Collect issues
+    if (!analysis.isValidJson) {
+        analysis.issues.push('Response is not valid JSON');
+    }
+    if (analysis.hasProse) {
+        analysis.issues.push('Response contains conversational prose');
+    }
+    if (!analysis.matchesSchema && expectedSchema) {
+        analysis.issues.push('Response does not match expected schema');
+    }
+    if (!response.parsedContent) {
+        analysis.issues.push('Response missing parsedContent');
+    }
+    // Calculate quality score (0-10)
+    let score = 10;
+    if (!analysis.isValidJson)
+        score -= 5;
+    if (analysis.hasProse)
+        score -= 3;
+    if (!analysis.matchesSchema && expectedSchema)
+        score -= 2;
+    if (!response.parsedContent)
+        score -= 5;
+    analysis.qualityScore = Math.max(0, score);
+    const passed = analysis.issues.length === 0 && analysis.qualityScore >= 7;
+    return {
+        passed,
+        response,
+        analysis
+    };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Gateway Meta Operations Module
+ * Handles meta operations like instruction optimization and testing
+ */
+import type { EnhancedLLMResponse, GatewayConfig } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+import type { AIGateway } from './gateway.js';
+/**
+ * Test instructions by running them and analyzing the response
+ */
+export declare function testInstructions(instructions: string, testInput: string, expectedSchema: Record<string, unknown> | undefined, options: {
+    agentId?: string;
+    model?: string;
+    provider?: string;
+}, config: GatewayConfig, gateway: AIGateway, logger: Logxer): Promise<{
+    passed: boolean;
+    response: EnhancedLLMResponse;
+    analysis: {
+        isValidJson: boolean;
+        matchesSchema: boolean;
+        hasProse: boolean;
+        issues: string[];
+        qualityScore: number;
+    };
+}>;

package/dist-cjs/gateway-provider-auto-register.cjs

@@ -0,0 +1,195 @@
+"use strict";
+/**
+ * Gateway Provider Auto-Registration Module
+ * Automatically registers providers based on environment variables
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.autoRegisterProviders = autoRegisterProviders;
+const PROVIDER_CONFIGS = [
+    {
+        name: 'openai',
+        packageName: '@x12i/ai-provider-openai',
+        className: 'OpenAIProvider',
+        envVar: 'OPENAI_API_KEY'
+    },
+    {
+        name: 'grok',
+        packageName: '@x12i/ai-provider-grok',
+        className: 'GrokProvider',
+        envVar: 'GROK_API_KEY'
+    },
+    {
+        name: 'anthropic',
+        packageName: '@x12i/ai-provider-anthropic',
+        className: 'AnthropicProvider',
+        envVar: 'ANTHROPIC_API_KEY',
+        optional: true // Optional - may not be installed
+    },
+    {
+        name: 'google',
+        packageName: '@x12i/ai-provider-google',
+        className: 'GoogleProvider',
+        envVar: 'GOOGLE_API_KEY',
+        optional: true // Optional - may not be installed
+    },
+    {
+        name: 'cohere',
+        packageName: '@x12i/ai-provider-cohere',
+        className: 'CohereProvider',
+        envVar: 'COHERE_API_KEY',
+        optional: true // Optional - may not be installed
+    },
+    {
+        name: 'mistral',
+        packageName: '@x12i/ai-provider-mistral',
+        className: 'MistralProvider',
+        envVar: 'MISTRAL_API_KEY',
+        optional: true // Optional - may not be installed
+    }
+];
+/**
+ * Auto-registers providers based on environment variables
+ * Only registers providers that:
+ * 1. Have their API key set in environment variables
+ * 2. Have their provider package installed
+ *
+ * @param router - LLM provider router instance
+ * @param logger - Logger instance
+ * @returns Array of provider names that were successfully registered
+ */
+async function autoRegisterProviders(router, logger) {
+    const registeredProviders = [];
+    logger.debug('Auto-registering providers from environment variables');
+    for (const providerConfig of PROVIDER_CONFIGS) {
+        const apiKey = process.env[providerConfig.envVar];
+        // Skip if API key is not set
+        if (!apiKey) {
+            if (!providerConfig.optional) {
+                logger.debug(`Skipping ${providerConfig.name} provider: ${providerConfig.envVar} not set`);
+            }
+            continue;
+        }
+        try {
+            // Dynamically import the provider package
+            // Use dynamic import() for ES module compatibility
+            let ProviderClass;
+            try {
+                const providerModule = await Promise.resolve(`${providerConfig.packageName}`).then(s => __importStar(require(s)));
+                ProviderClass = providerModule[providerConfig.className] || providerModule.default;
+                if (!ProviderClass) {
+                    logger.debug(`Provider class ${providerConfig.className} not found in ${providerConfig.packageName}`);
+                    continue;
+                }
+            }
+            catch (importError) {
+                if (!providerConfig.optional) {
+                    logger.warn(`Failed to import ${providerConfig.packageName}`, {
+                        error: importError instanceof Error ? importError.message : String(importError),
+                        note: `Install it with: npm install ${providerConfig.packageName}`
+                    });
+                }
+                continue;
+            }
+            // Instantiate the provider
+            const provider = new ProviderClass({
+                apiKey: apiKey
+            });
+            // Get provider name for both module creation and logging
+            const providerName = typeof provider.getProviderName === 'function'
+                ? provider.getProviderName()
+                : providerConfig.name;
+            // Register with router as ProviderModule
+            const providerModule = {
+                name: providerName,
+                capabilities: {
+                    modes: {
+                        sync: true,
+                        stream: false,
+                        batch: false
+                    },
+                    operations: ['invoke'],
+                    maxConcurrency: 10
+                },
+                execute: async (request) => {
+                    // Use aiCall if available, otherwise assume invoke
+                    if (typeof provider.aiCall === 'function') {
+                        return await provider.aiCall(request);
+                    }
+                    else if (typeof provider.invoke === 'function') {
+                        return await provider.invoke(request);
+                    }
+                    else {
+                        throw new Error(`Provider ${providerName} has neither aiCall nor invoke method`);
+                    }
+                }
+            };
+            router.registerProvider(providerModule);
+            registeredProviders.push(providerName);
+            logger.info(`Auto-registered provider: ${providerName}`, {
+                provider: providerName,
+                envVar: providerConfig.envVar,
+                hasApiKey: !!apiKey
+            });
+        }
+        catch (error) {
+            logger.error(`Failed to auto-register ${providerConfig.name} provider`, {
+                provider: providerConfig.name,
+                package: providerConfig.packageName,
+                error: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined
+            });
+            // Continue with other providers even if one fails
+        }
+    }
+    if (registeredProviders.length === 0) {
+        logger.warn('No providers were auto-registered. Make sure API keys are set in environment variables:', {
+            requiredEnvVars: PROVIDER_CONFIGS
+                .filter(p => !p.optional)
+                .map(p => p.envVar),
+            optionalEnvVars: PROVIDER_CONFIGS
+                .filter(p => p.optional)
+                .map(p => p.envVar),
+            openRouter: 'Set OPEN_ROUTER_KEY or OPENROUTER_API_KEY (and do not set USE_OPENROUTER=false) to use OpenRouter without registering a provider.',
+            note: 'You can still manually register providers using gateway.register(provider)'
+        });
+    }
+    else {
+        logger.info(`Auto-registered ${registeredProviders.length} provider(s)`, {
+            providers: registeredProviders
+        });
+    }
+    return registeredProviders;
+}

package/dist-cjs/gateway-provider-auto-register.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gateway Provider Auto-Registration Module
+ * Automatically registers providers based on environment variables
+ */
+import type { LLMProviderRouter } from '@x12i/ai-providers-router';
+import type { Logxer } from '@x12i/logxer';
+/**
+ * Auto-registers providers based on environment variables
+ * Only registers providers that:
+ * 1. Have their API key set in environment variables
+ * 2. Have their provider package installed
+ *
+ * @param router - LLM provider router instance
+ * @param logger - Logger instance
+ * @returns Array of provider names that were successfully registered
+ */
+export declare function autoRegisterProviders(router: LLMProviderRouter, logger: Logxer): Promise<string[]>;

package/dist-cjs/gateway-provider.cjs

@@ -0,0 +1,214 @@
+"use strict";
+/**
+ * Gateway Provider Module
+ * Handles provider management
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerProvider = registerProvider;
+exports.unregisterProvider = unregisterProvider;
+exports.getProvider = getProvider;
+exports.listProviders = listProviders;
+exports.setDefaultProvider = setDefaultProvider;
+exports.setFallbackChain = setFallbackChain;
+exports.addRequestInterceptor = addRequestInterceptor;
+exports.addResponseInterceptor = addResponseInterceptor;
+exports.checkHealth = checkHealth;
+exports.checkAllHealth = checkAllHealth;
+/**
+ * Register a provider with the router
+ */
+function registerProvider(provider, router, logger) {
+    // Get provider name - try multiple methods
+    let providerName = 'unknown';
+    if (typeof provider.getProviderName === 'function') {
+        providerName = provider.getProviderName();
+    }
+    else if (provider.name) {
+        providerName = provider.name;
+    }
+    else if (provider.constructor?.name) {
+        providerName = provider.constructor.name.replace('Provider', '').toLowerCase();
+    }
+    logger.debug('Registering provider', { provider: providerName });
+    // Check if provider has required methods
+    if (!provider || (typeof provider.invoke !== 'function' && typeof provider.aiCall !== 'function')) {
+        logger.error('Provider registration failed: must implement invoke() or aiCall()', {
+            provider: providerName,
+            hasInvoke: typeof provider.invoke === 'function',
+            hasAiCall: typeof provider.aiCall === 'function'
+        });
+        throw new Error('Provider must implement LLMProviderInterface (invoke) or AIProviderInterface (aiCall)');
+    }
+    // Create a ProviderModule wrapper for the provider instance
+    logger.debug('Creating ProviderModule wrapper for provider instance', { provider: providerName });
+    // Ensure provider has invoke method
+    let providerWithInvoke = provider;
+    if (typeof provider.aiCall === 'function' && typeof provider.invoke !== 'function') {
+        logger.debug('Provider uses aiCall, creating invoke wrapper', { provider: providerName });
+        providerWithInvoke = {
+            ...provider,
+            invoke: async (request) => {
+                // Convert LLMRequest to format expected by aiCall
+                return await provider.aiCall(request);
+            }
+        };
+    }
+    // Create ProviderModule wrapper
+    const providerModule = {
+        name: providerName,
+        capabilities: {
+            modes: {
+                sync: true,
+                stream: false,
+                batch: false
+            },
+            operations: ['invoke'],
+            maxConcurrency: 10
+        },
+        execute: async (request) => {
+            return await providerWithInvoke.invoke(request);
+        }
+    };
+    // Register with router using registerProvider
+    try {
+        router.registerProvider(providerModule);
+        logger.info('Provider registered as ProviderModule', {
+            provider: providerName,
+            totalProviders: router.listProviders().length
+        });
+    }
+    catch (error) {
+        logger.error('Failed to register provider with router.registerProvider, trying registry directly', {
+            provider: providerName,
+            error: error instanceof Error ? error.message : String(error)
+        });
+        // Fallback: try to access registry directly
+        try {
+            const registry = router.getProviderRegistry();
+            registry.register(providerModule);
+            logger.info('Provider registered via registry fallback', {
+                provider: providerName,
+                totalProviders: router.listProviders().length
+            });
+        }
+        catch (registryError) {
+            logger.error('Failed to register provider via registry', {
+                provider: providerName,
+                error: registryError instanceof Error ? registryError.message : String(registryError)
+            });
+            throw registryError;
+        }
+    }
+}
+/**
+ * Unregister a provider
+ */
+function unregisterProvider(providerName, router, logger) {
+    try {
+        // Try to access registry directly to remove the provider
+        const registry = router.getProviderRegistry();
+        // Since registry doesn't have an unregister method, we'll need to manipulate the map directly
+        // This is a bit hacky but necessary since the API doesn't provide unregister
+        const map = registry.map;
+        if (map && map instanceof Map) {
+            map.delete(providerName);
+            logger.info('Provider unregistered from registry', { provider: providerName });
+        }
+        else {
+            logger.warn('Could not access provider registry map for unregistration', { provider: providerName });
+        }
+    }
+    catch (error) {
+        logger.error('Failed to unregister provider', {
+            provider: providerName,
+            error: error instanceof Error ? error.message : String(error)
+        });
+    }
+}
+/**
+ * Get a provider module
+ */
+function getProvider(providerName, router) {
+    try {
+        const registry = router.getProviderRegistry();
+        return registry.get(providerName);
+    }
+    catch (error) {
+        // Fallback to any access if registry access fails
+        return router.getProvider?.(providerName);
+    }
+}
+/**
+ * List all registered providers
+ */
+function listProviders(router) {
+    return router.listProviders();
+}
+/**
+ * Set default provider
+ *
+ * NOTE: Router doesn't support changing default provider after initialization.
+ * This method is kept for API compatibility but does nothing.
+ * Default provider must be set in router config during initialization.
+ */
+function setDefaultProvider(provider, router, logger) {
+    // Router doesn't support changing default provider after initialization
+    // Default provider must be set in router config during initialization
+    logger.warn('setDefaultProvider called but router does not support changing default provider after initialization', {
+        provider,
+        note: 'Default provider must be set in router config during initialization'
+    });
+}
+/**
+ * Set fallback chain
+ *
+ * NOTE: Router doesn't support changing fallback chain after initialization.
+ * This method is kept for API compatibility but does nothing.
+ * Fallback chain must be set in router config during initialization.
+ */
+function setFallbackChain(chain, router, logger) {
+    // Router doesn't support changing fallback chain after initialization
+    // Fallback chain must be set in router config during initialization
+    logger.warn('setFallbackChain called but router does not support changing fallback chain after initialization', {
+        chain,
+        note: 'Fallback chain must be set in router config during initialization'
+    });
+}
+/**
+ * Add request interceptor
+ */
+function addRequestInterceptor(interceptor, router) {
+    router.addRequestInterceptor(interceptor);
+}
+/**
+ * Add response interceptor
+ */
+function addResponseInterceptor(interceptor, router) {
+    router.addResponseInterceptor(interceptor);
+}
+/**
+ * Check health of a provider
+ */
+async function checkHealth(provider, router) {
+    return router.checkHealth(provider);
+}
+/**
+ * Check health of all providers
+ */
+async function checkAllHealth(router) {
+    const providers = listProviders(router);
+    const results = {};
+    for (const provider of providers) {
+        try {
+            results[provider] = await router.checkHealth(provider);
+        }
+        catch (error) {
+            results[provider] = {
+                provider,
+                healthy: false,
+                error: error instanceof Error ? error.message : String(error)
+            };
+        }
+    }
+    return results;
+}