@mxf-dev/core 1.0.0

package/src/types/MxpTypes.ts

@@ -0,0 +1,404 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * MXP Types and Interfaces
+ * 
+ * Defines core types for the Model Exchange Protocol optimization system.
+ * Designed to integrate with existing MXF architecture and services.
+ */
+
+import { AgentId, ChannelId } from './ChannelContext.js';
+import { ContentFormat } from '../schemas/MessageSchemas.js';
+
+/**
+ * Cross-environment CryptoKeyPair type (works in both Node.js and browser)
+ */
+export interface MxpCryptoKeyPair {
+    publicKey: unknown;
+    privateKey: unknown;
+}
+
+/**
+ * MXP Version and Security Levels
+ */
+export const MXP_VERSION = '2.0' as const;
+
+export enum SecurityLevel {
+    STANDARD = 'standard',     // Current MXF security (server-decryptable)
+    ENHANCED = 'enhanced',     // + audit logging, key escrow
+    REGULATED = 'regulated',   // + GDPR/HIPAA features, data residency
+    CLASSIFIED = 'classified'  // + government/military grade (E2E available)
+}
+
+/**
+ * MXP Configuration Interface with Channel and Agent-level Granular Control
+ */
+export interface MxpConfig {
+    version: typeof MXP_VERSION;
+    
+    // Configuration scope and inheritance
+    scope: {
+        channelId?: string;           // Apply to specific channel
+        agentId?: string;             // Apply to specific agent  
+        inheritFromChannel: boolean;  // Agent inherits channel config
+        overrideSettings: boolean;    // Allow local overrides
+    };
+    
+    // Modular feature configuration
+    modules: {
+        tokenOptimization?: TokenOptimizationConfig;
+        bandwidthOptimization?: BandwidthOptimizationConfig;
+        security?: SecurityConfig;
+        analytics?: AnalyticsConfig;
+    };
+    
+    // Service integration toggles
+    integration: {
+        useExistingAggregator: boolean;     // Leverage MxfMessageAggregator
+        useExistingPatternLearning: boolean; // Use PatternLearningService
+        useExistingEventBus: boolean;       // Use EventBus priority queuing
+        useExistingMemory: boolean;         // Use ChannelContextMemoryOperations
+        useSystemLlmService: boolean;       // Use SystemLlmService for optimization
+    };
+}
+
+/**
+ * Token Optimization Configuration with Granular Feature Control
+ */
+export interface TokenOptimizationConfig {
+    enabled: boolean;
+    
+    // Individual strategy toggles
+    strategies: {
+        contextCompression: boolean;
+        promptOptimization: boolean;
+        templateMatching: boolean;
+        entityDeduplication: boolean;
+        toolSchemaReduction: boolean;
+        conversationSummarization: boolean;
+    };
+    
+    // Optimization settings
+    settings: {
+        compressionLevel: 'light' | 'standard' | 'aggressive';
+        systemLlmIntegration: boolean;
+        patternLearningIntegration: boolean;
+        contextWindow: {
+            fullContextMessages: number;      // Keep last N messages uncompressed
+            compressionRatio: number;         // Target compression (0.2 = 80% reduction)
+            referenceMode: boolean;           // Use context references for old messages
+        };
+        templateEngine: {
+            enabled: boolean;
+            maxTemplates: number;
+            confidenceThreshold: number;
+        };
+    };
+}
+
+/**
+ * Token Optimization Strategies
+ */
+export type TokenOptimizationStrategy = 
+    | 'context_compression'
+    | 'prompt_optimization' 
+    | 'template_matching'
+    | 'entity_deduplication'
+    | 'tool_schema_reduction'
+    | 'conversation_summarization'
+    | 'all';
+
+/**
+ * Bandwidth Optimization Configuration
+ */
+export interface BandwidthOptimizationConfig {
+    enabled: boolean;
+    encoding: ContentFormat;
+    compression: 'none' | 'light' | 'standard' | 'aggressive';
+    enhancedBatching: boolean;          // Enhance existing MxfMessageAggregator
+    priorityQueueIntegration: boolean;  // Use EventBus priority system
+    binaryProtocol: {
+        enabled: boolean;
+        thresholdBytes: number;         // Apply binary encoding for messages > N bytes
+        compressionAlgorithm: 'brotli' | 'gzip' | 'zstd';
+    };
+    messageAggregation: {
+        similarityThreshold: number;    // Leverage existing 0.8 threshold
+        maxBatchSize: number;
+        timeoutMs: number;              // Enhance existing 3-minute failsafe
+    };
+}
+
+/**
+ * Security Configuration
+ */
+export interface SecurityConfig {
+    enabled: boolean;
+    level: SecurityLevel;
+    features: {
+        auditLogging?: boolean;
+        keyEscrow?: boolean;
+        dataResidency?: string;
+        endToEndEncryption?: boolean;  // Only for CLASSIFIED level
+        complianceMode?: 'GDPR' | 'HIPAA' | 'SOX' | 'FedRAMP';
+    };
+    keyManagement: {
+        rotationPolicy: 'time' | 'usage' | 'both';
+        rotationInterval: number;
+        keyLength: 256 | 384 | 521;
+        algorithm: 'AES-GCM' | 'ChaCha20-Poly1305';
+        enhanceExistingKeys: boolean;   // Build on ChannelKeyService
+    };
+}
+
+/**
+ * Analytics Configuration
+ */
+export interface AnalyticsConfig {
+    enabled: boolean;
+    realTimeMetrics: boolean;
+    costCalculation: {
+        enabled: boolean;
+        providers: LlmProviderCosts;
+        reportingInterval: 'hourly' | 'daily' | 'weekly' | 'monthly';
+    };
+    performanceTracking: {
+        tokenReduction: boolean;
+        bandwidthSavings: boolean;
+        latencyImpact: boolean;
+        errorRates: boolean;
+    };
+}
+
+/**
+ * LLM Provider Cost Configuration
+ */
+export interface LlmProviderCosts {
+    [provider: string]: {
+        input: number;  // Cost per 1K tokens
+        output: number; // Cost per 1K tokens
+    };
+}
+
+/**
+ * MXP Optimization Result
+ */
+export interface MxpOptimizationResult {
+    operationId: string;
+    timestamp: number;
+    agentId: AgentId;
+    channelId: ChannelId;
+    
+    tokenOptimization?: {
+        originalTokens: number;
+        optimizedTokens: number;
+        reductionPercentage: number;
+        strategy: string;
+    };
+    
+    bandwidthOptimization?: {
+        originalSize: number;
+        compressedSize: number;
+        reductionPercentage: number;
+        encoding: ContentFormat;
+    };
+    
+    security?: {
+        level: SecurityLevel;
+        encryptionApplied: boolean;
+        keyRotated: boolean;
+    };
+    
+    performance: {
+        processingTimeMs: number;
+        memoryUsageMb: number;
+        cpuUtilization: number;
+    };
+    
+    costSavings?: {
+        originalCost: number;
+        optimizedCost: number;
+        savingsAmount: number;
+        savingsPercentage: number;
+    };
+}
+
+/**
+ * MXP Context Compression Result
+ */
+export interface ContextCompressionResult {
+    originalContext: any;
+    compressedContext: any;
+    compressionRatio: number;
+    contextReference?: string;
+    preservedTokens: number;
+    metadata: {
+        strategy: string;
+        systemLlmUsed: boolean;
+        patternLearningApplied: boolean;
+    };
+}
+
+/**
+ * MXP Message Template
+ */
+export interface MessageTemplate {
+    templateId: string;
+    pattern: string;
+    placeholders: string[];
+    usage: {
+        frequency: number;
+        lastUsed: number;
+        confidence: number;
+    };
+    tokenSavings: {
+        originalLength: number;
+        templateLength: number;
+        averageSavings: number;
+    };
+}
+
+/**
+ * MXP Enhanced Key Pair (extends existing ChannelKey)
+ */
+export interface EnhancedKeyPair {
+    keyId: string;
+    secretKey: string;
+    algorithm: string;
+    serverDecryptable: boolean;
+    securityLevel: SecurityLevel;
+    
+    // Progressive security features
+    escrowCopy?: string;
+    e2eKeyPair?: MxpCryptoKeyPair;
+    functionalityImpact?: {
+        messageAggregation: boolean;
+        patternLearning: boolean;
+        serverAnalytics: boolean;
+        crossAgentInsights: boolean;
+    };
+    functionalityWarning?: string;
+}
+
+/**
+ * Default MXP Configuration
+ */
+export const DEFAULT_MXP_CONFIG: MxpConfig = {
+    version: MXP_VERSION,
+    
+    // Default scope - can be applied to any channel or agent
+    scope: {
+        inheritFromChannel: true,
+        overrideSettings: true
+    },
+    
+    modules: {
+        tokenOptimization: {
+            enabled: true,
+            
+            // Granular strategy control - enable key optimizations by default
+            strategies: {
+                contextCompression: true,
+                promptOptimization: true,
+                templateMatching: true,
+                entityDeduplication: false,       // More experimental
+                toolSchemaReduction: false,       // Requires careful testing
+                conversationSummarization: true
+            },
+            
+            // Optimization settings
+            settings: {
+                compressionLevel: 'standard',
+                systemLlmIntegration: true,
+                patternLearningIntegration: true,
+                contextWindow: {
+                    fullContextMessages: 5,
+                    compressionRatio: 0.2,
+                    referenceMode: true
+                },
+                templateEngine: {
+                    enabled: true,
+                    maxTemplates: 100,
+                    confidenceThreshold: 0.8
+                }
+            }
+        },
+        bandwidthOptimization: {
+            enabled: true,
+            encoding: ContentFormat.JSON,
+            compression: 'standard',
+            enhancedBatching: true,
+            priorityQueueIntegration: true,
+            binaryProtocol: {
+                enabled: true,
+                thresholdBytes: 10240,  // 10KB
+                compressionAlgorithm: 'brotli'
+            },
+            messageAggregation: {
+                similarityThreshold: 0.8,  // Use existing MxfMessageAggregator threshold
+                maxBatchSize: 64 * 1024,   // 64KB
+                timeoutMs: 180000          // Use existing 3-minute failsafe
+            }
+        },
+        security: {
+            enabled: true,
+            level: SecurityLevel.ENHANCED,
+            features: {
+                auditLogging: true,
+                keyEscrow: true,
+                complianceMode: 'GDPR'
+            },
+            keyManagement: {
+                rotationPolicy: 'both',
+                rotationInterval: 30 * 24 * 60 * 60 * 1000, // 30 days
+                keyLength: 256,
+                algorithm: 'AES-GCM',
+                enhanceExistingKeys: true
+            }
+        },
+        analytics: {
+            enabled: true,
+            realTimeMetrics: true,
+            costCalculation: {
+                enabled: true,
+                providers: {
+                    'gpt-4o': { input: 0.03, output: 0.06 },
+                    'claude-3.5-sonnet': { input: 0.025, output: 0.075 },
+                    'gemini-pro': { input: 0.02, output: 0.04 }
+                },
+                reportingInterval: 'daily'
+            },
+            performanceTracking: {
+                tokenReduction: true,
+                bandwidthSavings: true,
+                latencyImpact: true,
+                errorRates: true
+            }
+        }
+    },
+    integration: {
+        useExistingAggregator: true,
+        useExistingPatternLearning: true, 
+        useExistingEventBus: true,
+        useExistingMemory: true,
+        useSystemLlmService: true
+    }
+};

package/src/types/NetworkRecoveryTypes.ts

@@ -0,0 +1,268 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/mxf-dev/mxf
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * Network Recovery Types
+ * 
+ * Type definitions for network error handling, retry logic,
+ * circuit breaker patterns, and graceful degradation strategies.
+ */
+
+/**
+ * Classification of network and API errors for proper handling strategies
+ */
+export enum NetworkErrorType {
+    // Network connectivity issues
+    NETWORK_TIMEOUT = 'NETWORK_TIMEOUT',
+    NETWORK_CONNECTION_REFUSED = 'NETWORK_CONNECTION_REFUSED',
+    NETWORK_DNS_RESOLUTION = 'NETWORK_DNS_RESOLUTION',
+    NETWORK_SOCKET_ERROR = 'NETWORK_SOCKET_ERROR',
+    
+    // API service issues
+    API_BAD_GATEWAY = 'API_BAD_GATEWAY',              // 502
+    API_SERVICE_UNAVAILABLE = 'API_SERVICE_UNAVAILABLE', // 503
+    API_GATEWAY_TIMEOUT = 'API_GATEWAY_TIMEOUT',      // 504
+    API_INTERNAL_ERROR = 'API_INTERNAL_ERROR',        // 500
+    
+    // Authentication and authorization
+    AUTH_UNAUTHORIZED = 'AUTH_UNAUTHORIZED',          // 401
+    AUTH_FORBIDDEN = 'AUTH_FORBIDDEN',                // 403
+    
+    // Rate limiting
+    RATE_LIMITED = 'RATE_LIMITED',                    // 429
+    
+    // Client errors
+    CLIENT_BAD_REQUEST = 'CLIENT_BAD_REQUEST',        // 400
+    CLIENT_UNPROCESSABLE = 'CLIENT_UNPROCESSABLE',    // 422
+    CLIENT_NOT_FOUND = 'CLIENT_NOT_FOUND',            // 404
+    
+    // Other errors
+    UNKNOWN_ERROR = 'UNKNOWN_ERROR'
+}
+
+/**
+ * Determines if an error is retryable based on its type
+ */
+export function isRetryableError(errorType: NetworkErrorType): boolean {
+    const retryableTypes = [
+        NetworkErrorType.NETWORK_TIMEOUT,
+        NetworkErrorType.NETWORK_CONNECTION_REFUSED,
+        NetworkErrorType.NETWORK_DNS_RESOLUTION,
+        NetworkErrorType.NETWORK_SOCKET_ERROR,
+        NetworkErrorType.API_BAD_GATEWAY,
+        NetworkErrorType.API_SERVICE_UNAVAILABLE,
+        NetworkErrorType.API_GATEWAY_TIMEOUT,
+        NetworkErrorType.API_INTERNAL_ERROR,
+        NetworkErrorType.RATE_LIMITED
+    ];
+    
+    return retryableTypes.includes(errorType);
+}
+
+/**
+ * Network recovery configuration options
+ */
+export interface NetworkRecoveryConfig {
+    // Retry configuration
+    maxRetries: number;                    // Maximum retry attempts (default: 3)
+    baseDelayMs: number;                   // Initial retry delay (default: 1000ms)
+    maxDelayMs: number;                    // Maximum retry delay (default: 30000ms)
+    retryMultiplier: number;               // Exponential backoff multiplier (default: 2)
+    
+    // Circuit breaker configuration
+    circuitBreakerThreshold: number;       // Consecutive failures to open circuit (default: 5)
+    circuitBreakerCooldownMs: number;      // Time to wait before retrying (default: 60000ms)
+    circuitBreakerHalfOpenRequests: number; // Requests to try in half-open state (default: 1)
+    
+    // Timeout configuration
+    requestTimeoutMs: number;              // Individual request timeout (default: 30000ms)
+    
+    // Graceful degradation
+    enableGracefulDegradation: boolean;    // Enable fallback responses (default: true)
+    enableDetailedLogging: boolean;        // Log detailed error context (default: true)
+}
+
+/**
+ * Default network recovery configuration
+ */
+export const DEFAULT_NETWORK_RECOVERY_CONFIG: NetworkRecoveryConfig = {
+    maxRetries: 3,
+    baseDelayMs: 1000,
+    maxDelayMs: 30000,
+    retryMultiplier: 2,
+    circuitBreakerThreshold: 5,
+    circuitBreakerCooldownMs: 60000,
+    circuitBreakerHalfOpenRequests: 1,
+    requestTimeoutMs: 30000,
+    enableGracefulDegradation: true,
+    enableDetailedLogging: true
+};
+
+/**
+ * Circuit breaker states
+ */
+export enum CircuitBreakerState {
+    CLOSED = 'CLOSED',       // Normal operation
+    OPEN = 'OPEN',           // Blocking requests
+    HALF_OPEN = 'HALF_OPEN'  // Testing recovery
+}
+
+/**
+ * Circuit breaker status information
+ */
+export interface CircuitBreakerStatus {
+    state: CircuitBreakerState;
+    failureCount: number;
+    lastFailureTime?: Date;
+    nextRetryTime?: Date;
+    successCount: number;
+    totalRequests: number;
+}
+
+/**
+ * Enhanced error information for better debugging
+ */
+export interface NetworkErrorInfo {
+    type: NetworkErrorType;
+    statusCode?: number;
+    message: string;
+    originalError?: Error;
+    timestamp: Date;
+    retryCount?: number;
+    maxRetries?: number;
+    context?: Record<string, any>;
+}
+
+/**
+ * Retry attempt information
+ */
+export interface RetryAttempt {
+    attemptNumber: number;
+    delayMs: number;
+    errorType: NetworkErrorType;
+    timestamp: Date;
+}
+
+/**
+ * Result of a network operation with recovery
+ */
+export interface NetworkOperationResult<T> {
+    success: boolean;
+    data?: T;
+    error?: NetworkErrorInfo;
+    retryAttempts?: RetryAttempt[];
+    circuitBreakerTriggered?: boolean;
+    fallbackUsed?: boolean;
+}
+
+/**
+ * Classifies an error based on status code and error details
+ */
+export function classifyNetworkError(
+    error: any, 
+    statusCode?: number
+): NetworkErrorType {
+    // Check for specific status codes first
+    if (statusCode) {
+        switch (statusCode) {
+            case 400:
+                return NetworkErrorType.CLIENT_BAD_REQUEST;
+            case 401:
+                return NetworkErrorType.AUTH_UNAUTHORIZED;
+            case 403:
+                return NetworkErrorType.AUTH_FORBIDDEN;
+            case 404:
+                return NetworkErrorType.CLIENT_NOT_FOUND;
+            case 422:
+                return NetworkErrorType.CLIENT_UNPROCESSABLE;
+            case 429:
+                return NetworkErrorType.RATE_LIMITED;
+            case 500:
+                return NetworkErrorType.API_INTERNAL_ERROR;
+            case 502:
+                return NetworkErrorType.API_BAD_GATEWAY;
+            case 503:
+                return NetworkErrorType.API_SERVICE_UNAVAILABLE;
+            case 504:
+                return NetworkErrorType.API_GATEWAY_TIMEOUT;
+        }
+    }
+    
+    // Check error message for network issues
+    const errorMessage = error?.message?.toLowerCase() || '';
+    
+    if (errorMessage.includes('timeout')) {
+        return NetworkErrorType.NETWORK_TIMEOUT;
+    }
+    if (errorMessage.includes('econnrefused') || errorMessage.includes('connection refused')) {
+        return NetworkErrorType.NETWORK_CONNECTION_REFUSED;
+    }
+    if (errorMessage.includes('enotfound') || errorMessage.includes('dns')) {
+        return NetworkErrorType.NETWORK_DNS_RESOLUTION;
+    }
+    if (errorMessage.includes('socket') || errorMessage.includes('econnreset')) {
+        return NetworkErrorType.NETWORK_SOCKET_ERROR;
+    }
+    if (errorMessage.includes('fetch failed')) {
+        // Generic fetch failed could be various network issues
+        return NetworkErrorType.NETWORK_CONNECTION_REFUSED;
+    }
+    
+    return NetworkErrorType.UNKNOWN_ERROR;
+}
+
+/**
+ * Calculates retry delay with exponential backoff and jitter
+ */
+export function calculateRetryDelay(
+    attemptNumber: number,
+    config: NetworkRecoveryConfig
+): number {
+    const exponentialDelay = config.baseDelayMs * Math.pow(config.retryMultiplier, attemptNumber - 1);
+    const clampedDelay = Math.min(exponentialDelay, config.maxDelayMs);
+    
+    // Add jitter (±20%) to prevent thundering herd
+    const jitter = clampedDelay * 0.2 * (Math.random() - 0.5);
+    
+    return Math.round(clampedDelay + jitter);
+}
+
+/**
+ * Formats an error for logging with appropriate detail level
+ */
+export function formatNetworkError(
+    error: NetworkErrorInfo,
+    includeStack: boolean = false
+): string {
+    const parts = [
+        `[${error.type}]`,
+        error.statusCode ? `Status ${error.statusCode}` : '',
+        error.message,
+        error.retryCount ? `(Retry ${error.retryCount}/${error.maxRetries})` : ''
+    ].filter(Boolean);
+    
+    let formatted = parts.join(' ');
+    
+    if (includeStack && error.originalError?.stack) {
+        formatted += '\n' + error.originalError.stack;
+    }
+    
+    return formatted;
+}