agentic-qe 2.5.7 → 2.5.9

package/dist/agents/BaseAgent.js

@@ -2,6 +2,7 @@
 /**
  * BaseAgent - Abstract base class for all QE agents
  * Phase 2 B1.2: Decomposed with strategy pattern (~500 LOC target)
+ * Phase 0: LLM Provider integration with RuvLLM support
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseAgentFactory = exports.BaseAgent = exports.validateLearningConfig = exports.isSwarmMemoryManager = void 0;
@@ -12,9 +13,15 @@ const MemoryStoreAdapter_1 = require("../adapters/MemoryStoreAdapter");
 const PerformanceTracker_1 = require("../learning/PerformanceTracker");
 const SwarmMemoryManager_1 = require("../core/memory/SwarmMemoryManager");
 const LearningEngine_1 = require("../learning/LearningEngine");
+// Federated Learning (Phase 0 M0.5 - Team-wide pattern sharing)
+const FederatedManager_1 = require("../learning/FederatedManager");
 const AgentLifecycleManager_1 = require("./lifecycle/AgentLifecycleManager");
 const AgentCoordinator_1 = require("./coordination/AgentCoordinator");
 const AgentMemoryService_1 = require("./memory/AgentMemoryService");
+const RuvllmProvider_1 = require("../providers/RuvllmProvider");
+const LLMProviderFactory_1 = require("../providers/LLMProviderFactory");
+// HybridRouter with RuVector cache (Phase 0.5 - GNN Self-Learning)
+const HybridRouter_1 = require("../providers/HybridRouter");
 const adapters_1 = require("./adapters");
 // Extracted utilities (B1.2)
 const utils_1 = require("./utils");
@@ -24,13 +31,16 @@ class BaseAgent extends events_1.EventEmitter {
     constructor(config) {
         super();
         this.performanceMetrics = { tasksCompleted: 0, averageExecutionTime: 0, errorCount: 0, lastActivity: new Date() };
+        this.federatedInitialized = false;
         this.agentId = { id: config.id || (0, utils_1.generateAgentId)(config.type), type: config.type, created: new Date() };
-        this.capabilities = new Map(config.capabilities.map(cap => [cap.name, cap]));
+        this.capabilities = new Map((config.capabilities || []).map(cap => [cap.name, cap]));
         this.context = config.context;
         this.memoryStore = config.memoryStore;
-        this.eventBus = config.eventBus;
+        this.eventBus = config.eventBus || new events_1.EventEmitter();
         this.enableLearning = config.enableLearning ?? true;
         this.learningConfig = config.learningConfig;
+        // LLM configuration (Phase 0 - default enabled with RuvLLM)
+        this.llmConfig = config.llm ?? { enabled: true, preferredProvider: 'ruvllm' };
         // Early validation (Issue #137)
         const validation = (0, utils_1.validateLearningConfig)(config);
         if (!validation.valid && validation.warning) {
@@ -91,6 +101,10 @@ class BaseAgent extends events_1.EventEmitter {
                     else if (this.enableLearning) {
                         console.warn(`[${this.agentId.id}] Learning disabled: memoryStore is ${this.memoryStore.constructor.name}`);
                     }
+                    // Initialize LLM Provider (Phase 0 - RuvLLM Integration)
+                    await this.initializeLLMProvider();
+                    // Initialize Federated Learning (Phase 0 M0.5)
+                    await this.initializeFederatedLearning();
                     await this.initializeComponents();
                     await this.executeHook('post-initialization');
                     this.coordinator.emitEvent('agent.initialized', { agentId: this.agentId });
@@ -144,6 +158,8 @@ class BaseAgent extends events_1.EventEmitter {
                     await this.executeHook('pre-termination');
                     await this.saveState();
                     await this.cleanup();
+                    await this.cleanupLLM(); // Phase 0: Cleanup LLM resources
+                    await this.cleanupFederated(); // Phase 0 M0.5: Cleanup federated learning
                     this.coordinator.clearAllHandlers();
                 },
                 onPostTermination: async () => {
@@ -356,18 +372,34 @@ class BaseAgent extends events_1.EventEmitter {
                 duration: executionTime, metadata: { taskId: data.assignment.id, accuracy: result.accuracy, metrics: this.extractTaskMetrics(data.result) }
             });
         }
+        // Share successful patterns with team via federated learning (Phase 0 M0.5)
+        if (result.valid && this.federatedInitialized && this.llmProvider) {
+            try {
+                // Generate embedding for the task pattern
+                const taskDescription = `${data.assignment.task.type}: ${JSON.stringify(data.assignment.task.payload || {}).slice(0, 200)}`;
+                const embedding = await this.llmEmbed(taskDescription);
+                await this.shareLearnedPattern({
+                    embedding,
+                    quality: result.accuracy ?? 0.8,
+                    category: data.assignment.task.type,
+                });
+            }
+            catch {
+                // Pattern sharing failed - non-critical, continue
+            }
+        }
         this.emitEvent('hook.post-task.completed', { agentId: this.agentId, result });
     }
     async onTaskError(data) {
         const executionTime = this.taskStartTime ? Date.now() - this.taskStartTime : 0;
         await this.storeMemory(`error:${data.assignment.id}`, {
             error: { message: data.error.message, name: data.error.name },
-            assignment: { id: data.assignment.id, taskType: data.assignment.task.type },
+            assignment: { id: data.assignment.id, taskType: data.assignment.task?.type ?? 'unknown' },
             timestamp: new Date(), agentId: this.agentId.id
         });
         if (this.strategies.lifecycle.onTaskError)
             await this.strategies.lifecycle.onTaskError(data);
-        if (this.strategies.learning?.recordExecution) {
+        if (this.strategies.learning?.recordExecution && data.assignment.task) {
             await this.strategies.learning.recordExecution({
                 task: data.assignment.task, error: data.error, success: false,
                 duration: executionTime, metadata: { taskId: data.assignment.id }
@@ -383,7 +415,8 @@ class BaseAgent extends events_1.EventEmitter {
                 await this[method](data);
         }
         catch (error) {
-            console.error(`Hook ${hookName} failed:`, error);
+            // Use warn - hooks are optional and failures shouldn't break agent operation
+            console.warn(`Hook ${hookName} failed:`, error);
         }
     }
     setupEventHandlers() {
@@ -437,6 +470,503 @@ class BaseAgent extends events_1.EventEmitter {
     async saveState() {
         await this.memoryService.saveState({ performanceMetrics: this.performanceMetrics, timestamp: new Date() });
     }
+    // ============================================
+    // LLM Provider Methods (Phase 0 - RuvLLM Integration)
+    // ============================================
+    /**
+     * Initialize LLM provider for agent use
+     * Supports RuvLLM (local), Claude, OpenRouter, and HybridRouter with RuVector cache
+     */
+    async initializeLLMProvider() {
+        if (!this.llmConfig.enabled) {
+            console.log(`[${this.agentId.id}] LLM disabled by configuration`);
+            return;
+        }
+        try {
+            // If a provider was injected, use it directly
+            if (this.llmConfig.provider) {
+                this.llmProvider = this.llmConfig.provider;
+                console.log(`[${this.agentId.id}] Using injected LLM provider`);
+                return;
+            }
+            // Phase 0.5: Create HybridRouter with RuVector GNN cache for intelligent routing
+            if (this.llmConfig.enableHybridRouter || this.llmConfig.preferredProvider === 'hybrid') {
+                const hybridConfig = {
+                    // RuVector cache configuration (GNN self-learning)
+                    ruvector: {
+                        enabled: true,
+                        baseUrl: this.llmConfig.ruvectorCache?.baseUrl || 'http://localhost:8080',
+                        cacheThreshold: this.llmConfig.ruvectorCache?.cacheThreshold ?? 0.85,
+                        learningEnabled: this.llmConfig.ruvectorCache?.learningEnabled ?? true,
+                        loraRank: this.llmConfig.ruvectorCache?.loraRank ?? 8,
+                        ewcEnabled: this.llmConfig.ruvectorCache?.ewcEnabled ?? true,
+                        ...this.llmConfig.ruvectorCache,
+                    },
+                    // Local LLM via ruvllm
+                    ruvllm: {
+                        name: `${this.agentId.id}-ruvllm`,
+                        enableSessions: this.llmConfig.enableSessions ?? true,
+                        enableTRM: true,
+                        enableSONA: true,
+                        ...this.llmConfig.ruvllm,
+                    },
+                    // Routing strategy
+                    defaultStrategy: this.llmConfig.hybridRouterConfig?.defaultStrategy || HybridRouter_1.RoutingStrategy.BALANCED,
+                    ...this.llmConfig.hybridRouterConfig,
+                };
+                this.hybridRouter = new HybridRouter_1.HybridRouter(hybridConfig);
+                await this.hybridRouter.initialize();
+                this.llmProvider = this.hybridRouter;
+                console.log(`[${this.agentId.id}] HybridRouter initialized with RuVector GNN cache`);
+                return;
+            }
+            // Create RuvLLM provider directly (preferred for local inference)
+            if (this.llmConfig.preferredProvider === 'ruvllm' || !this.llmConfig.preferredProvider) {
+                const ruvllmConfig = {
+                    name: `${this.agentId.id}-ruvllm`,
+                    enableSessions: this.llmConfig.enableSessions ?? true,
+                    enableTRM: true,
+                    enableSONA: true,
+                    debug: false,
+                    ...this.llmConfig.ruvllm
+                };
+                this.llmProvider = new RuvllmProvider_1.RuvllmProvider(ruvllmConfig);
+                await this.llmProvider.initialize();
+                // Create session for this agent if sessions enabled
+                if (this.llmConfig.enableSessions) {
+                    const ruvllm = this.llmProvider;
+                    const session = ruvllm.createSession();
+                    this.llmSessionId = session.id;
+                    console.log(`[${this.agentId.id}] LLM session created: ${this.llmSessionId}`);
+                }
+                console.log(`[${this.agentId.id}] RuvLLM provider initialized`);
+                return;
+            }
+            // Use factory for other providers (Claude, OpenRouter)
+            this.llmFactory = new LLMProviderFactory_1.LLMProviderFactory(this.llmConfig.factoryConfig || {});
+            await this.llmFactory.initialize();
+            this.llmProvider = this.llmFactory.getProvider(this.llmConfig.preferredProvider);
+            if (!this.llmProvider) {
+                console.warn(`[${this.agentId.id}] Preferred provider ${this.llmConfig.preferredProvider} not available, trying auto-select`);
+                this.llmProvider = this.llmFactory.selectBestProvider();
+            }
+            if (this.llmProvider) {
+                console.log(`[${this.agentId.id}] LLM provider initialized: ${this.llmConfig.preferredProvider}`);
+            }
+            else {
+                console.warn(`[${this.agentId.id}] No LLM provider available`);
+            }
+        }
+        catch (error) {
+            // Use warn instead of error - this is expected fallback behavior, not a failure
+            console.warn(`[${this.agentId.id}] LLM initialization failed:`, error.message);
+            // Don't throw - agent can still work without LLM (algorithmic fallback)
+        }
+    }
+    /**
+     * Initialize Federated Learning for team-wide pattern sharing
+     * Phase 0 M0.5 - Reduces Claude Code dependency through collective learning
+     */
+    async initializeFederatedLearning() {
+        if (!this.llmConfig.enableFederated) {
+            return;
+        }
+        try {
+            // Use shared FederatedManager or create new one
+            if (this.llmConfig.federatedManager) {
+                this.federatedManager = this.llmConfig.federatedManager;
+            }
+            else {
+                this.federatedManager = new FederatedManager_1.FederatedManager(this.llmConfig.federatedConfig);
+                await this.federatedManager.initialize();
+            }
+            // Register this agent for federated learning
+            this.ephemeralAgent = this.federatedManager.registerAgent(this.agentId.id);
+            this.federatedInitialized = true;
+            console.log(`[${this.agentId.id}] Federated learning initialized`);
+            // Sync with existing team knowledge on startup
+            try {
+                await this.federatedManager.syncFromTeam(this.agentId.id);
+                console.log(`[${this.agentId.id}] Synced with team knowledge`);
+            }
+            catch {
+                // First agent or no prior knowledge - expected
+            }
+        }
+        catch (error) {
+            // Use warn instead of error - this is expected fallback behavior
+            console.warn(`[${this.agentId.id}] Federated learning initialization failed:`, error.message);
+            // Don't throw - agent can work without federated learning
+        }
+    }
+    /**
+     * Check if federated learning is available
+     */
+    hasFederatedLearning() {
+        return this.federatedInitialized && this.federatedManager !== undefined;
+    }
+    /**
+     * Share a learned pattern with the team via federated learning
+     * Call this when the agent learns something useful (e.g., after successful task)
+     *
+     * @param pattern - The pattern to share (embedding, quality score, category)
+     */
+    async shareLearnedPattern(pattern) {
+        if (!this.federatedManager || !this.federatedInitialized) {
+            return;
+        }
+        const fullPattern = {
+            ...pattern,
+            id: `pattern-${this.agentId.id}-${Date.now()}`,
+            sourceAgent: this.agentId.id,
+            timestamp: Date.now(),
+        };
+        await this.federatedManager.sharePattern(this.agentId.id, fullPattern);
+    }
+    /**
+     * Sync this agent with team-wide learned knowledge
+     * Call this periodically or before complex tasks
+     */
+    async syncWithTeam() {
+        if (!this.federatedManager || !this.federatedInitialized) {
+            return;
+        }
+        await this.federatedManager.syncFromTeam(this.agentId.id);
+    }
+    /**
+     * Submit this agent's learning updates to the team
+     * Call after completing a batch of tasks
+     */
+    async submitLearningUpdate() {
+        if (!this.federatedManager || !this.federatedInitialized) {
+            return;
+        }
+        await this.federatedManager.submitAgentUpdate(this.agentId.id);
+    }
+    /**
+     * Get federated learning metrics
+     */
+    getFederatedMetrics() {
+        if (!this.federatedManager) {
+            return null;
+        }
+        return this.federatedManager.getMetrics();
+    }
+    /**
+     * Check if LLM is available for this agent
+     */
+    hasLLM() {
+        return this.llmProvider !== undefined;
+    }
+    /**
+     * Get LLM provider (for advanced usage)
+     */
+    getLLMProvider() {
+        return this.llmProvider;
+    }
+    /**
+     * Make an LLM completion call
+     * Uses RuvLLM's session management for 50% latency reduction on multi-turn
+     *
+     * @param prompt - The prompt to send to the LLM
+     * @param options - Additional completion options
+     * @returns The LLM response text
+     * @throws Error if LLM is not available
+     */
+    async llmComplete(prompt, options) {
+        if (!this.llmProvider) {
+            throw new Error(`[${this.agentId.id}] LLM not available - initialize agent first`);
+        }
+        const completionOptions = {
+            model: options?.model || this.llmConfig.ruvllm?.defaultModel || 'llama-3.2-3b-instruct',
+            messages: [{ role: 'user', content: prompt }],
+            maxTokens: options?.maxTokens,
+            temperature: options?.temperature,
+            stream: options?.stream,
+            metadata: {
+                ...options?.metadata,
+                sessionId: this.llmSessionId, // Use session for faster multi-turn
+                agentId: this.agentId.id,
+                agentType: this.agentId.type
+            }
+        };
+        const response = await this.llmProvider.complete(completionOptions);
+        // Extract text from response
+        const text = response.content
+            .filter(block => block.type === 'text')
+            .map(block => block.text)
+            .join('\n');
+        return text;
+    }
+    /**
+     * Make a batch LLM completion call (4x throughput)
+     * Uses RuvLLM's native batch API for parallel processing
+     *
+     * @param prompts - Array of prompts to process in parallel
+     * @param options - Shared completion options
+     * @returns Array of response texts in same order as prompts
+     */
+    async llmBatchComplete(prompts, options) {
+        if (!this.llmProvider) {
+            throw new Error(`[${this.agentId.id}] LLM not available - initialize agent first`);
+        }
+        // Check if provider supports batch (RuvLLM does)
+        const ruvllm = this.llmProvider;
+        if (typeof ruvllm.batchComplete === 'function') {
+            const defaultModel = options?.model || this.llmConfig.ruvllm?.defaultModel || 'llama-3.2-3b-instruct';
+            const requests = prompts.map(prompt => ({
+                model: defaultModel,
+                messages: [{ role: 'user', content: prompt }],
+                maxTokens: options?.maxTokens,
+                temperature: options?.temperature,
+                metadata: {
+                    ...options?.metadata,
+                    agentId: this.agentId.id,
+                    agentType: this.agentId.type
+                }
+            }));
+            const responses = await ruvllm.batchComplete(requests);
+            return responses.map(response => response.content
+                .filter(block => block.type === 'text')
+                .map(block => block.text)
+                .join('\n'));
+        }
+        // Fallback: sequential processing for non-batch providers
+        console.warn(`[${this.agentId.id}] Provider doesn't support batch, using sequential`);
+        const results = [];
+        for (const prompt of prompts) {
+            results.push(await this.llmComplete(prompt, options));
+        }
+        return results;
+    }
+    /**
+     * Generate embeddings for text
+     * Uses RuvLLM's SIMD-optimized embedding generation
+     *
+     * @param text - Text to embed
+     * @returns Embedding vector
+     */
+    async llmEmbed(text) {
+        if (!this.llmProvider) {
+            throw new Error(`[${this.agentId.id}] LLM not available - initialize agent first`);
+        }
+        const response = await this.llmProvider.embed({ text });
+        return response.embedding || [];
+    }
+    /**
+     * Chat within agent's session (50% faster for multi-turn)
+     * Only works with RuvLLM provider with sessions enabled
+     *
+     * @param input - User input to chat
+     * @returns Assistant response
+     */
+    async llmChat(input) {
+        if (!this.llmProvider) {
+            throw new Error(`[${this.agentId.id}] LLM not available`);
+        }
+        if (!this.llmSessionId) {
+            // Fallback to regular complete if no session
+            return this.llmComplete(input);
+        }
+        const ruvllm = this.llmProvider;
+        if (typeof ruvllm.sessionChat === 'function') {
+            return ruvllm.sessionChat(this.llmSessionId, input);
+        }
+        // Fallback
+        return this.llmComplete(input);
+    }
+    /**
+     * Get routing decision for observability
+     * Shows which model was selected and why
+     */
+    getLLMRoutingDecision(input) {
+        if (!this.llmProvider) {
+            return null;
+        }
+        const ruvllm = this.llmProvider;
+        if (typeof ruvllm.getRoutingDecision === 'function') {
+            return ruvllm.getRoutingDecision(input);
+        }
+        return null;
+    }
+    /**
+     * Get LLM usage statistics for this agent
+     */
+    getLLMStats() {
+        return {
+            available: this.hasLLM(),
+            sessionId: this.llmSessionId,
+            provider: this.hybridRouter ? 'hybrid' : (this.llmProvider ? 'ruvllm' : undefined),
+            hasRuVectorCache: this.hasRuVectorCache(),
+        };
+    }
+    // ============================================
+    // RuVector Cache Methods (Phase 0.5 - GNN Self-Learning)
+    // ============================================
+    /**
+     * Check if RuVector GNN cache is available
+     */
+    hasRuVectorCache() {
+        return this.hybridRouter !== undefined;
+    }
+    /**
+     * Get RuVector cache metrics
+     * Returns cache hit rate, pattern count, and learning metrics
+     */
+    async getRuVectorMetrics() {
+        if (!this.hybridRouter) {
+            return null;
+        }
+        try {
+            return await this.hybridRouter.getRuVectorMetrics();
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get cache hit rate for this agent's requests
+     */
+    getCacheHitRate() {
+        if (!this.hybridRouter) {
+            return 0;
+        }
+        return this.hybridRouter.getCacheHitRate();
+    }
+    /**
+     * Get routing statistics including cache savings
+     */
+    getRoutingStats() {
+        if (!this.hybridRouter) {
+            return {
+                totalDecisions: 0,
+                localDecisions: 0,
+                cloudDecisions: 0,
+                cacheHits: 0,
+                cacheMisses: 0,
+                cacheHitRate: 0,
+                averageLocalLatency: 0,
+                averageCloudLatency: 0,
+                successRate: 0,
+            };
+        }
+        return this.hybridRouter.getRoutingStats();
+    }
+    /**
+     * Force learning consolidation in the RuVector cache
+     * Triggers LoRA adaptation and EWC++ protection
+     */
+    async forceRuVectorLearn() {
+        if (!this.hybridRouter) {
+            return { success: false, error: 'RuVector not enabled' };
+        }
+        return await this.hybridRouter.forceRuVectorLearn();
+    }
+    /**
+     * Get cost savings report from using RuVector cache
+     */
+    getCostSavingsReport() {
+        if (!this.hybridRouter) {
+            return {
+                totalRequests: 0,
+                localRequests: 0,
+                cloudRequests: 0,
+                totalCost: 0,
+                estimatedCloudCost: 0,
+                savings: 0,
+                savingsPercentage: 0,
+                cacheHits: 0,
+                cacheSavings: 0,
+            };
+        }
+        return this.hybridRouter.getCostSavingsReport();
+    }
+    /**
+     * Make an LLM call with automatic caching and learning
+     * Uses RuVector GNN cache when available for sub-ms pattern matching
+     *
+     * @param prompt - The prompt to process
+     * @param options - Additional options
+     * @returns The response text
+     */
+    async llmCompleteWithLearning(prompt, options) {
+        if (!this.llmProvider) {
+            throw new Error(`[${this.agentId.id}] LLM not available - initialize agent first`);
+        }
+        // If using HybridRouter, it automatically handles caching and learning
+        if (this.hybridRouter) {
+            const completionOptions = {
+                model: options?.model || 'auto',
+                messages: [{ role: 'user', content: prompt }],
+                maxTokens: options?.maxTokens,
+                temperature: options?.temperature,
+                metadata: {
+                    ...options?.metadata,
+                    agentId: this.agentId.id,
+                    agentType: this.agentId.type,
+                    complexity: options?.complexity,
+                },
+            };
+            const response = await this.hybridRouter.complete(completionOptions);
+            // Extract text from response
+            const text = response.content
+                .filter(block => block.type === 'text')
+                .map(block => block.text)
+                .join('\n');
+            return {
+                response: text,
+                source: response.metadata?.source || 'local',
+                confidence: response.metadata?.confidence,
+            };
+        }
+        // Fallback to regular completion
+        const text = await this.llmComplete(prompt, options);
+        return { response: text, source: 'local' };
+    }
+    /**
+     * Cleanup LLM resources on agent termination
+     */
+    async cleanupLLM() {
+        if (this.llmSessionId && this.llmProvider) {
+            const ruvllm = this.llmProvider;
+            if (typeof ruvllm.endSession === 'function') {
+                ruvllm.endSession(this.llmSessionId);
+                console.log(`[${this.agentId.id}] LLM session ended: ${this.llmSessionId}`);
+            }
+        }
+        if (this.llmProvider) {
+            await this.llmProvider.shutdown();
+        }
+        if (this.llmFactory) {
+            await this.llmFactory.shutdown();
+        }
+    }
+    /**
+     * Cleanup federated learning resources on agent termination
+     * Submits final learning updates and unregisters from the coordinator
+     */
+    async cleanupFederated() {
+        if (!this.federatedManager || !this.federatedInitialized) {
+            return;
+        }
+        try {
+            // Submit final learning updates before terminating
+            await this.submitLearningUpdate();
+            // Unregister this agent from federated learning
+            this.federatedManager.unregisterAgent(this.agentId.id);
+            console.log(`[${this.agentId.id}] Federated learning cleanup complete`);
+        }
+        catch (error) {
+            console.warn(`[${this.agentId.id}] Federated cleanup error:`, error.message);
+        }
+        this.federatedInitialized = false;
+        this.ephemeralAgent = undefined;
+        // Only shutdown the manager if we created it (not if it was shared)
+        if (!this.llmConfig.federatedManager && this.federatedManager) {
+            await this.federatedManager.shutdown();
+            this.federatedManager = undefined;
+        }
+    }
 }
 exports.BaseAgent = BaseAgent;
 class BaseAgentFactory {