@x12i/ai-gateway 7.9.1

package/dist/gateway-retry.js

@@ -0,0 +1,204 @@
+/**
+ * Gateway Retry Module
+ * Handles retry logic for network and server errors
+ *
+ * NOTE: Retry delays use SIMPLE SLEEP (not smart rate limiting).
+ * Between-calls rate limiting is handled separately in gateway-rate-limiter.ts (smart).
+ */
+/**
+ * Determines if an error is a network error (fetch failed, DNS, connectivity)
+ */
+export function isNetworkError(error) {
+    const message = error.message.toLowerCase();
+    const networkPatterns = [
+        'fetch failed',
+        'network error',
+        'dns',
+        'connectivity',
+        'connection',
+        'econnrefused',
+        'enotfound',
+        'etimedout',
+        'econnreset',
+        'api endpoint unavailability'
+    ];
+    return networkPatterns.some(pattern => message.includes(pattern));
+}
+/**
+ * Extracts HTTP status code from error message or error object properties
+ */
+export function extractHttpStatusCode(error) {
+    // Try to extract from error message
+    const statusMatch = error.message.match(/\b(4\d{2}|5\d{2})\b/);
+    if (statusMatch) {
+        return parseInt(statusMatch[1], 10);
+    }
+    // Try to extract from error object properties
+    const errorAny = error;
+    if (errorAny.statusCode) {
+        return errorAny.statusCode;
+    }
+    if (errorAny.status) {
+        return errorAny.status;
+    }
+    if (errorAny.response?.status) {
+        return errorAny.response.status;
+    }
+    return undefined;
+}
+/**
+ * Determines if an HTTP error should be retried
+ * Retryable: 429 (throttling), 5xx (server errors)
+ * Non-retryable: 4xx except 429 (client errors)
+ */
+export function isRetryableHttpError(error, statusCode) {
+    // 429 (throttling) is retryable
+    if (statusCode === 429) {
+        return true;
+    }
+    // 5xx (server errors) are retryable
+    if (statusCode >= 500 && statusCode < 600) {
+        return true;
+    }
+    // 4xx (client errors) are NOT retryable except 429
+    return false;
+}
+/**
+ * Determines if an error should be retried
+ */
+export function isRetryableError(error) {
+    // Network errors are always retryable
+    if (isNetworkError(error)) {
+        return true;
+    }
+    // Check HTTP status code
+    const statusCode = extractHttpStatusCode(error);
+    if (statusCode !== undefined) {
+        return isRetryableHttpError(error, statusCode);
+    }
+    // Timeout errors are retryable
+    if (error.name === 'TimeoutError' || error.message.toLowerCase().includes('timeout')) {
+        return true;
+    }
+    // Default: don't retry unknown errors
+    return false;
+}
+/**
+ * Sleep helper for retry delays
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Invokes router with retry logic for network and server errors
+ * Returns response and retry metadata
+ */
+export async function invokeWithRetry(routerRequest, retryConfig, jobId, router, logger) {
+    const maxRetries = retryConfig.maxRetries ?? 3;
+    const initialDelay = retryConfig.initialDelay ?? 1000;
+    const maxDelay = retryConfig.maxDelay ?? 30000;
+    const backoffMultiplier = retryConfig.backoffMultiplier ?? 2;
+    const enableJitter = retryConfig.enableJitter ?? true;
+    const throttlingDelay = retryConfig.throttlingDelay ?? 5000;
+    let lastError;
+    const retryAttempts = [];
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const response = await router.invoke(routerRequest);
+            // Log success after retry if this wasn't the first attempt
+            if (attempt > 0) {
+                logger.info('Request succeeded after retry', {
+                    jobId,
+                    attempt: attempt + 1,
+                    totalAttempts: attempt + 1,
+                    retryCount: retryAttempts.length
+                });
+            }
+            // Return response with retry metadata if there were retries
+            if (retryAttempts.length > 0) {
+                return {
+                    response,
+                    retryMetadata: {
+                        retryCount: retryAttempts.length,
+                        retryAttempts
+                    }
+                };
+            }
+            return { response };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            // Check if error is retryable
+            if (!isRetryableError(lastError)) {
+                logger.debug('Non-retryable error, not retrying', {
+                    jobId,
+                    error: lastError.message,
+                    errorName: lastError.name,
+                    attempt: attempt + 1
+                });
+                throw lastError;
+            }
+            // If this was the last attempt, throw the error
+            if (attempt >= maxRetries) {
+                logger.warn('Max retries exceeded', {
+                    jobId,
+                    error: lastError.message,
+                    errorName: lastError.name,
+                    totalAttempts: attempt + 1,
+                    maxRetries
+                });
+                throw lastError;
+            }
+            // Calculate delay with exponential backoff
+            const baseDelay = initialDelay * Math.pow(backoffMultiplier, attempt);
+            let delay = Math.min(baseDelay, maxDelay);
+            // Add extra delay for throttling
+            const statusCode = extractHttpStatusCode(lastError);
+            if (statusCode === 429) {
+                delay += throttlingDelay;
+                logger.debug('Throttling detected, adding extra delay', {
+                    jobId,
+                    throttlingDelay,
+                    baseDelay: Math.round(delay - throttlingDelay)
+                });
+            }
+            // Add jitter if enabled
+            if (enableJitter) {
+                const jitter = Math.random() * delay * 0.3; // Up to 30% jitter
+                delay += jitter;
+            }
+            // Classify error type for logging
+            const errorType = isNetworkError(lastError)
+                ? 'network'
+                : statusCode !== undefined
+                    ? `http-${statusCode}`
+                    : 'timeout';
+            // Record retry attempt for activity tracking
+            retryAttempts.push({
+                attempt: attempt + 1,
+                timestamp: Date.now(),
+                error: lastError.message,
+                errorType,
+                delayMs: Math.round(delay)
+            });
+            logger.warn('Retrying request after error', {
+                jobId,
+                error: lastError.message,
+                errorName: lastError.name,
+                errorType,
+                attempt: attempt + 1,
+                maxRetries: maxRetries + 1,
+                delayMs: Math.round(delay),
+                statusCode
+            });
+            await sleep(delay);
+        }
+    }
+    // If we get here, all retries exhausted - throw error with retry metadata
+    const errorWithRetries = lastError;
+    errorWithRetries.retryMetadata = {
+        retryCount: retryAttempts.length,
+        retryAttempts
+    };
+    throw errorWithRetries;
+}

package/dist/gateway-utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Gateway Utilities Module
+ * Handles utility functions
+ */
+import type { ChatRequest, GatewayConfig } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+/**
+ * Generates MD5 hash of a string
+ */
+export declare function generateMD5Hash(text: string): string;
+/**
+ * Auto-generates taskTypeId from MD5 hash of pre-parsed instructions if not provided
+ */
+export declare function ensureTaskTypeId(request: ChatRequest, logger: Logxer): Promise<string>;
+/**
+ * Merges config with defaults
+ * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
+ */
+export declare function mergeConfig(request: ChatRequest & {
+    useInternalDefaults?: 'skill' | 'audit';
+}, config: GatewayConfig, logger: Logxer): Promise<ChatRequest['config']>;

package/dist/gateway-utils.js

@@ -0,0 +1,181 @@
+/**
+ * Gateway Utilities Module
+ * Handles utility functions
+ */
+import * as crypto from 'crypto';
+import { getPreParsedInstructions } from './gateway-instructions.js';
+import { getModelMaxTokensFromFlexMd } from './flex-md-loader.js';
+/**
+ * Generates MD5 hash of a string
+ */
+export function generateMD5Hash(text) {
+    return crypto.createHash('md5').update(text).digest('hex');
+}
+/**
+ * Auto-generates taskTypeId from MD5 hash of pre-parsed instructions if not provided
+ */
+export async function ensureTaskTypeId(request, logger) {
+    if (request.taskTypeId) {
+        return request.taskTypeId;
+    }
+    const preParsedInstructions = getPreParsedInstructions(request.instructions);
+    // Generate MD5 hash
+    const taskTypeId = generateMD5Hash(preParsedInstructions);
+    logger.debug('Auto-generated taskTypeId from instructions MD5 hash', {
+        jobId: request.jobId,
+        taskTypeId,
+        instructionsLength: preParsedInstructions.length,
+        instructionsPreview: preParsedInstructions.substring(0, 100) + (preParsedInstructions.length > 100 ? '...' : '')
+    });
+    return taskTypeId;
+}
+/**
+ * Merges config with defaults
+ * Supports using internal system action defaults (internalSkill or skillAudit) when useInternalDefaults is set
+ */
+export async function mergeConfig(request, config, logger) {
+    const useInternalDefaults = request.useInternalDefaults;
+    const internalDefaults = useInternalDefaults
+        ? (useInternalDefaults === 'skill'
+            ? config.internalSystemActions?.internalSkill
+            : config.internalSystemActions?.skillAudit)
+        : undefined;
+    logger.verbose('Merging request config with gateway defaults', {
+        jobId: request.jobId,
+        hasRequestConfig: !!request.config,
+        hasModelConfig: !!request.modelConfig,
+        requestModel: request.config?.model,
+        modelConfigModel: request.modelConfig?.model || request.modelConfig?.modelId,
+        requestProvider: request.config?.provider,
+        modelConfigProvider: request.modelConfig?.provider,
+        defaultEngine: config.defaultEngine,
+        useInternalDefaults,
+        hasInternalDefaults: !!internalDefaults
+    });
+    // Default model to "gpt-5-nano" if nothing is provided (most permissive - always works)
+    const defaultModel = 'gpt-5-nano';
+    // Priority: modelConfig > request.config > internalSystemActions[useInternalDefaults] > gateway defaults
+    // First, merge modelConfig into a config-like object if present
+    const modelConfigAsConfig = request.modelConfig ? {
+        model: request.modelConfig.model || request.modelConfig.modelId,
+        provider: request.modelConfig.provider,
+        temperature: request.modelConfig.temperature,
+        maxTokens: request.modelConfig.maxTokens,
+        topP: request.modelConfig.topP,
+        frequencyPenalty: request.modelConfig.frequencyPenalty,
+        presencePenalty: request.modelConfig.presencePenalty,
+        stop: request.modelConfig.stop,
+        // Include any additional properties from modelConfig
+        ...Object.fromEntries(Object.entries(request.modelConfig).filter(([key]) => !['model', 'modelId', 'provider', 'temperature', 'maxTokens', 'topP', 'frequencyPenalty', 'presencePenalty', 'stop'].includes(key)))
+    } : undefined;
+    const merged = {
+        // Start with gateway defaults (lowest priority)
+        temperature: config.temperature ?? 0.7,
+        // maxTokens will be set from flex-md if available, otherwise fallback to 2000
+        topP: config.topP ?? 1.0,
+        frequencyPenalty: config.frequencyPenalty ?? 0.0,
+        presencePenalty: config.presencePenalty ?? 0.0,
+        // Apply internal system action defaults (medium priority) if useInternalDefaults is set
+        ...(internalDefaults ? {
+            model: internalDefaults.model,
+            provider: internalDefaults.engine || config.defaultEngine,
+            temperature: internalDefaults.temperature ?? config.temperature ?? 0.7,
+            // maxTokens from internalDefaults only if explicitly set, otherwise will be auto-detected
+            ...(internalDefaults.maxTokens !== undefined ? { maxTokens: internalDefaults.maxTokens } : {})
+        } : {}),
+        // Request config overrides (higher priority)
+        ...request.config,
+        // ModelConfig overrides (highest priority) - merge only defined values
+        ...(modelConfigAsConfig ? Object.fromEntries(Object.entries(modelConfigAsConfig).filter(([_, value]) => value !== undefined)) : {}),
+        // Ensure model is set: modelConfig > request.config > internalDefaults > default
+        model: modelConfigAsConfig?.model || request.config?.model || internalDefaults?.model || defaultModel,
+        // Ensure provider is set: modelConfig > request.config > internalDefaults > gateway default
+        // Provider is required for router to know which provider to use
+        provider: modelConfigAsConfig?.provider || request.config?.provider || internalDefaults?.engine || config.defaultEngine
+    };
+    // Log if using default model
+    if (!request.config?.model && !internalDefaults?.model) {
+        logger.info('Using default model: gpt-5-nano (no model provided in request)', {
+            jobId: request.jobId,
+            note: 'Default model ensures requests always work regardless of configuration'
+        });
+    }
+    // Auto-get maxTokens from flex-md if not explicitly set in ANY config source
+    // Check all possible sources: request.config, internalDefaults, gateway config
+    const maxTokensExplicitlySet = request.config?.maxTokens !== undefined ||
+        internalDefaults?.maxTokens !== undefined ||
+        config.maxTokens !== undefined;
+    if (!maxTokensExplicitlySet && merged.model && merged.provider) {
+        // Try to get maxTokens from flex-md
+        try {
+            const flexMdMaxTokens = await getModelMaxTokensFromFlexMd(merged.provider, merged.model);
+            if (flexMdMaxTokens && flexMdMaxTokens > 0) {
+                merged.maxTokens = flexMdMaxTokens;
+                logger.debug('Using maxTokens from flex-md', {
+                    jobId: request.jobId,
+                    model: merged.model,
+                    provider: merged.provider,
+                    maxTokens: merged.maxTokens,
+                    source: 'flex-md'
+                });
+            }
+            else {
+                // flex-md doesn't have model info or returned invalid value - use fallback
+                merged.maxTokens = 2000;
+                logger.debug('Using fallback maxTokens (flex-md unavailable or no model info)', {
+                    jobId: request.jobId,
+                    model: merged.model,
+                    provider: merged.provider,
+                    maxTokens: merged.maxTokens,
+                    note: 'Set maxTokens explicitly in config for custom values.'
+                });
+            }
+        }
+        catch (error) {
+            // Error loading flex-md or getting model info - use fallback
+            merged.maxTokens = 2000;
+            logger.debug('Using fallback maxTokens (flex-md error)', {
+                jobId: request.jobId,
+                model: merged.model,
+                provider: merged.provider,
+                maxTokens: merged.maxTokens,
+                error: error instanceof Error ? error.message : String(error),
+                note: 'Set maxTokens explicitly in config for custom values.'
+            });
+        }
+    }
+    else if (!merged.maxTokens) {
+        // If maxTokens wasn't set and wasn't auto-detected, use fallback
+        // This should rarely happen, but handle edge cases
+        merged.maxTokens = 2000;
+        logger.debug('Using fallback maxTokens (not auto-detected and not explicitly set)', {
+            jobId: request.jobId,
+            model: merged.model,
+            provider: merged.provider,
+            maxTokens: merged.maxTokens,
+            maxTokensExplicitlySet
+        });
+    }
+    else {
+        // maxTokens was explicitly set - log which source
+        const source = request.config?.maxTokens !== undefined ? 'request.config' :
+            internalDefaults?.maxTokens !== undefined ? `internalSystemActions.${useInternalDefaults}` :
+                'gateway.config';
+        logger.debug('Using explicitly set maxTokens', {
+            jobId: request.jobId,
+            model: merged.model,
+            provider: merged.provider,
+            maxTokens: merged.maxTokens,
+            source
+        });
+    }
+    logger.debug('Config merged', {
+        jobId: request.jobId,
+        finalModel: merged.model,
+        finalProvider: merged.provider,
+        finalTemperature: merged.temperature,
+        finalMaxTokens: merged.maxTokens,
+        usedInternalDefaults: !!internalDefaults
+    });
+    return merged;
+}

package/dist/gateway-validation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Gateway Validation Module
+ * Basic validation for clean proxy implementation
+ */
+import type { ChatRequest, AIRequest } from './types.js';
+/**
+ * Validates ChatRequest has required fields
+ */
+export declare function validateChatRequest(request: ChatRequest): void;
+/**
+ * Validates AIRequest has required fields
+ */
+export declare function validateAIRequest(request: AIRequest): void;

package/dist/gateway-validation.js

@@ -0,0 +1,50 @@
+/**
+ * Gateway Validation Module
+ * Basic validation for clean proxy implementation
+ */
+/**
+ * Validates ChatRequest has required fields
+ */
+export function validateChatRequest(request) {
+    if (!request.aiRequestId) {
+        throw new Error('aiRequestId is required');
+    }
+    if (!request.agentId) {
+        throw new Error('agentId is required');
+    }
+    // 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.`);
+        err.code = 'INPUT_FIELD_DEPRECATED';
+        err.details = {
+            field: 'input',
+            alternative: 'workingMemory.input',
+            message: 'Input data must be provided via workingMemory.input for template rendering'
+        };
+        throw err;
+    }
+}
+/**
+ * Validates AIRequest has required fields
+ */
+export function validateAIRequest(request) {
+    if (!request.aiRequestId) {
+        throw new Error('aiRequestId is required for AI requests');
+    }
+    if (!request.agentId) {
+        throw new Error('agentId is required for AI requests');
+    }
+    // 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.`);
+        err.code = 'INPUT_FIELD_DEPRECATED';
+        err.details = {
+            field: 'input',
+            alternative: 'workingMemory.input',
+            message: 'Input data must be provided via workingMemory.input for template rendering'
+        };
+        throw err;
+    }
+    // Note: primaryObjectType and secondaryObjectTypes are now optional
+    // The gateway is a clean proxy - no object type validation logic
+}

package/dist/gateway.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @x12i/ai-gateway
+ *
+ * Simplified AI Gateway - Clean proxy implementation
+ */
+import { LLMProviderRouter } from '@x12i/ai-providers-router';
+import type { GatewayConfig, ChatRequest, AIRequest, EnhancedLLMResponse } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+import { ActivityManager } from './activity-manager.js';
+/**
+ * Simplified AI Gateway - Clean proxy implementation
+ */
+export declare class AIGateway {
+    private router;
+    private config;
+    private logger;
+    private activityManager?;
+    private messageBuilderConfig?;
+    private _autoRegisterDone;
+    constructor(config?: GatewayConfig, activityManager?: ActivityManager);
+    /**
+     * Invoke chat request (without structured output requirements)
+     */
+    invokeChat<TContent = unknown>(request: ChatRequest): Promise<EnhancedLLMResponse<TContent>>;
+    /**
+     * Invoke AI request (with structured output support)
+     */
+    invoke<TContent = unknown>(request: AIRequest): 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;
+    getLogger(): Logxer;
+    getActivityManager(): ActivityManager | undefined;
+    setActivityManager(activityManager: ActivityManager): void;
+}