@ruvector/edge-net 0.1.3 → 0.1.5

package/real-agents.js

@@ -0,0 +1,839 @@
+/**
+ * @ruvector/edge-net REAL Agent System
+ *
+ * Actually functional distributed agents with:
+ * - LOCAL LLM execution via ruvllm (default - no API key needed)
+ * - Cloud LLM API calls (Anthropic Claude, OpenAI) as fallback
+ * - Real embeddings via ruvector AdaptiveEmbedder
+ * - Real relay server sync
+ * - Real task execution
+ *
+ * @module @ruvector/edge-net/real-agents
+ */
+
+import { EventEmitter } from 'events';
+import { createHash, randomBytes } from 'crypto';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================
+// LLM PROVIDER CONFIGURATION
+// ============================================
+
+const LLM_PROVIDERS = {
+    // LOCAL LLM - Default, no API key needed
+    local: {
+        name: 'RuvLLM Local',
+        type: 'local',
+        models: {
+            fast: 'ruvllm-fast',
+            balanced: 'ruvllm-balanced',
+            powerful: 'ruvllm-powerful',
+        },
+    },
+    ruvllm: {
+        name: 'RuvLLM',
+        type: 'local',
+        models: {
+            fast: 'ruvllm-fast',
+            balanced: 'ruvllm-balanced',
+            powerful: 'ruvllm-powerful',
+        },
+    },
+    // Cloud providers as fallback (December 2025 models)
+    anthropic: {
+        name: 'Anthropic Claude',
+        type: 'cloud',
+        baseUrl: 'https://api.anthropic.com/v1',
+        models: {
+            fast: 'claude-3-5-haiku-20241022',
+            balanced: 'claude-sonnet-4-20250514',
+            powerful: 'claude-opus-4-5-20251101',
+        },
+        headers: (apiKey) => ({
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+        }),
+    },
+    openai: {
+        name: 'OpenAI',
+        type: 'cloud',
+        baseUrl: 'https://api.openai.com/v1',
+        models: {
+            fast: 'gpt-4o-mini',
+            balanced: 'gpt-5.2',
+            powerful: 'gpt-5.2-turbo',
+        },
+        headers: (apiKey) => ({
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${apiKey}`,
+        }),
+    },
+};
+
+// Agent type to system prompt mapping
+const AGENT_PROMPTS = {
+    researcher: `You are a research agent. Your task is to analyze, search, summarize, and extract information.
+Be thorough and cite sources when possible. Structure your findings clearly.`,
+
+    coder: `You are a coding agent. Your task is to write, refactor, debug, and test code.
+Write clean, well-documented code. Follow best practices and explain your approach.`,
+
+    reviewer: `You are a code review agent. Your task is to review code for quality, security, and best practices.
+Be constructive and specific. Identify issues and suggest improvements.`,
+
+    tester: `You are a testing agent. Your task is to write tests, validate functionality, and report issues.
+Cover edge cases. Write clear test descriptions.`,
+
+    analyst: `You are an analysis agent. Your task is to analyze data, generate metrics, and create reports.
+Be data-driven. Present findings with evidence.`,
+
+    optimizer: `You are an optimization agent. Your task is to profile, identify bottlenecks, and improve performance.
+Quantify improvements. Focus on measurable gains.`,
+
+    coordinator: `You are a coordination agent. Your task is to orchestrate workflows, route tasks, and manage schedules.
+Be organized and clear about task dependencies.`,
+
+    embedder: `You are an embedding agent specialized in semantic search and vector operations.
+Generate high-quality embeddings for text. Optimize for similarity matching.`,
+};
+
+// ============================================
+// REAL LLM CLIENT
+// ============================================
+
+/**
+ * Real LLM client - uses local ruvllm by default, falls back to cloud APIs
+ */
+export class LLMClient {
+    constructor(options = {}) {
+        // Default to local ruvllm, fallback to cloud if API key provided
+        this.provider = options.provider || 'local';
+        this.apiKey = options.apiKey || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY;
+        this.model = options.model || 'balanced';
+        this.maxTokens = options.maxTokens || 4096;
+
+        // Auto-select cloud provider if API key is set and provider not specified
+        if (!options.provider && this.apiKey) {
+            this.provider = process.env.ANTHROPIC_API_KEY ? 'anthropic' : 'openai';
+        }
+
+        this.config = LLM_PROVIDERS[this.provider];
+        if (!this.config) {
+            throw new Error(`Unknown LLM provider: ${this.provider}`);
+        }
+
+        // Initialize local LLM if using local provider
+        this.ruvllm = null;
+        this.ruvllmInitialized = false;
+    }
+
+    /**
+     * Initialize local ruvllm
+     */
+    async initLocal() {
+        if (this.ruvllmInitialized) return;
+
+        try {
+            const ruvllm = await import('@ruvector/ruvllm');
+            this.ruvllm = new ruvllm.RuvLLM({
+                embeddingDim: 768,
+                learningEnabled: true,
+            });
+            this.ruvllmInitialized = true;
+            console.log('[LLM] Initialized local RuvLLM engine');
+        } catch (error) {
+            console.warn('[LLM] RuvLLM not available:', error.message);
+        }
+    }
+
+    /**
+     * Call LLM - local or cloud
+     */
+    async complete(systemPrompt, userMessage, options = {}) {
+        const isLocal = this.config.type === 'local';
+
+        if (isLocal) {
+            return this.callLocal(systemPrompt, userMessage, options);
+        }
+
+        if (!this.apiKey) {
+            throw new Error('No API key configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or use provider: "local"');
+        }
+
+        const model = this.config.models[options.model || this.model];
+
+        if (this.provider === 'anthropic') {
+            return this.callAnthropic(systemPrompt, userMessage, model, options);
+        } else {
+            return this.callOpenAI(systemPrompt, userMessage, model, options);
+        }
+    }
+
+    /**
+     * Call local RuvLLM
+     */
+    async callLocal(systemPrompt, userMessage, options = {}) {
+        await this.initLocal();
+
+        const modelTier = options.model || this.model;
+        const prompt = `${systemPrompt}\n\n${userMessage}`;
+
+        if (this.ruvllm) {
+            // Use real ruvllm engine
+            const response = this.ruvllm.query(prompt, {
+                maxTokens: options.maxTokens || this.maxTokens,
+                temperature: options.temperature || 0.7,
+            });
+
+            return {
+                content: response.text,
+                model: `ruvllm-${modelTier}`,
+                usage: { input_tokens: prompt.length, output_tokens: response.text.length },
+                stopReason: 'end',
+                confidence: response.confidence,
+                local: true,
+            };
+        }
+
+        // Fallback: Generate response using local heuristics
+        console.log('[LLM] Using fallback local generation');
+        const fallbackResponse = this.generateFallbackResponse(systemPrompt, userMessage);
+
+        return {
+            content: fallbackResponse,
+            model: `ruvllm-${modelTier}-fallback`,
+            usage: { input_tokens: prompt.length, output_tokens: fallbackResponse.length },
+            stopReason: 'end',
+            local: true,
+            fallback: true,
+        };
+    }
+
+    /**
+     * Generate fallback response for basic tasks
+     */
+    generateFallbackResponse(systemPrompt, userMessage) {
+        // Basic task-specific responses
+        if (systemPrompt.includes('research')) {
+            return `Based on the query "${userMessage.slice(0, 100)}...", here are the key findings:\n\n1. The topic requires further investigation.\n2. Multiple sources should be consulted.\n3. Consider the context and requirements carefully.\n\nNote: This is a local fallback response. For more detailed analysis, ensure ruvllm is properly installed.`;
+        }
+
+        if (systemPrompt.includes('coding') || systemPrompt.includes('code')) {
+            return `Here's a code solution for: ${userMessage.slice(0, 50)}...\n\n\`\`\`javascript\n// Implementation based on the requirements\nfunction solution() {\n  // TODO: Implement the specific logic\n  console.log('Task:', '${userMessage.slice(0, 30)}...');\n  return { success: true };\n}\n\`\`\`\n\nNote: This is a local fallback. Install ruvllm for real code generation.`;
+        }
+
+        if (systemPrompt.includes('review')) {
+            return `Code Review for: ${userMessage.slice(0, 50)}...\n\n**Summary:** The code structure appears reasonable.\n\n**Suggestions:**\n- Add error handling\n- Consider edge cases\n- Add documentation\n\nNote: This is a local fallback response.`;
+        }
+
+        if (systemPrompt.includes('test')) {
+            return `Test Plan for: ${userMessage.slice(0, 50)}...\n\n\`\`\`javascript\ndescribe('Feature', () => {\n  it('should work correctly', () => {\n    // Test implementation\n    expect(true).toBe(true);\n  });\n});\n\`\`\`\n\nNote: This is a local fallback response.`;
+        }
+
+        // Generic response
+        return `Response to: ${userMessage.slice(0, 100)}...\n\nThis is a local response generated without cloud API calls. For full LLM capabilities:\n1. Install @ruvector/ruvllm for local AI\n2. Or set ANTHROPIC_API_KEY/OPENAI_API_KEY for cloud\n\nTask acknowledged and processed locally.`;
+    }
+
+    async callAnthropic(systemPrompt, userMessage, model, options = {}) {
+        const response = await fetch(`${this.config.baseUrl}/messages`, {
+            method: 'POST',
+            headers: this.config.headers(this.apiKey),
+            body: JSON.stringify({
+                model,
+                max_tokens: options.maxTokens || this.maxTokens,
+                system: systemPrompt,
+                messages: [{ role: 'user', content: userMessage }],
+            }),
+        });
+
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`Anthropic API error: ${response.status} - ${error}`);
+        }
+
+        const data = await response.json();
+        return {
+            content: data.content[0]?.text || '',
+            model,
+            usage: data.usage,
+            stopReason: data.stop_reason,
+        };
+    }
+
+    async callOpenAI(systemPrompt, userMessage, model, options = {}) {
+        const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: this.config.headers(this.apiKey),
+            body: JSON.stringify({
+                model,
+                max_tokens: options.maxTokens || this.maxTokens,
+                messages: [
+                    { role: 'system', content: systemPrompt },
+                    { role: 'user', content: userMessage },
+                ],
+            }),
+        });
+
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+        }
+
+        const data = await response.json();
+        return {
+            content: data.choices[0]?.message?.content || '',
+            model,
+            usage: data.usage,
+            stopReason: data.choices[0]?.finish_reason,
+        };
+    }
+
+    /**
+     * Check if LLM is configured
+     */
+    isConfigured() {
+        // Local is always configured
+        if (this.config.type === 'local') return true;
+        return !!this.apiKey;
+    }
+
+    /**
+     * Check if using local provider
+     */
+    isLocal() {
+        return this.config.type === 'local';
+    }
+}
+
+// ============================================
+// REAL EMBEDDER (uses ruvector)
+// ============================================
+
+/**
+ * Real embedder using ruvector's AdaptiveEmbedder
+ */
+export class RealEmbedder {
+    constructor(options = {}) {
+        this.embedder = null;
+        this.initialized = false;
+        this.options = options;
+    }
+
+    async initialize() {
+        try {
+            // Try to load ruvector's AdaptiveEmbedder
+            const { AdaptiveEmbedder } = await import('ruvector');
+            this.embedder = new AdaptiveEmbedder();
+            // Support both init() and initialize() methods
+            if (typeof this.embedder.init === 'function') {
+                await this.embedder.init();
+            } else if (typeof this.embedder.initialize === 'function') {
+                await this.embedder.initialize();
+            }
+            this.initialized = true;
+            console.log('[Embedder] Initialized ruvector AdaptiveEmbedder');
+            return true;
+        } catch (error) {
+            console.warn('[Embedder] ruvector not available, using fallback:', error.message);
+            return false;
+        }
+    }
+
+    async embed(text) {
+        if (this.initialized && this.embedder) {
+            return await this.embedder.embed(text);
+        }
+        // Fallback: Use a simple hash-based pseudo-embedding (NOT for production)
+        console.warn('[Embedder] Using fallback hash embeddings - install ruvector for real embeddings');
+        return this.fallbackEmbed(text);
+    }
+
+    async embedBatch(texts) {
+        if (this.initialized && this.embedder) {
+            return await this.embedder.embedBatch(texts);
+        }
+        return Promise.all(texts.map(t => this.fallbackEmbed(t)));
+    }
+
+    fallbackEmbed(text) {
+        // Simple hash-based pseudo-embedding for testing
+        // NOT semantically meaningful - use real embedder in production
+        const hash = createHash('sha256').update(text).digest();
+        const embedding = new Float32Array(384);
+        for (let i = 0; i < 384; i++) {
+            embedding[i] = (hash[i % 32] - 128) / 128;
+        }
+        return embedding;
+    }
+
+    async cosineSimilarity(a, b) {
+        let dot = 0, normA = 0, normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+    }
+}
+
+// ============================================
+// REAL AGENT
+// ============================================
+
+/**
+ * Real agent that executes tasks via LLM
+ */
+export class RealAgent extends EventEmitter {
+    constructor(type, options = {}) {
+        super();
+        this.id = `agent-${type}-${Date.now()}-${randomBytes(4).toString('hex')}`;
+        this.type = type;
+        this.systemPrompt = AGENT_PROMPTS[type] || AGENT_PROMPTS.coder;
+        this.llm = new LLMClient(options);
+        this.embedder = null;
+        this.status = 'idle';
+        this.taskHistory = [];
+        this.cost = { inputTokens: 0, outputTokens: 0 };
+    }
+
+    async initialize() {
+        if (this.type === 'embedder') {
+            this.embedder = new RealEmbedder();
+            await this.embedder.initialize();
+        }
+        return this;
+    }
+
+    /**
+     * Execute a task
+     */
+    async execute(task, context = {}) {
+        if (!this.llm.isConfigured() && this.type !== 'embedder') {
+            throw new Error('LLM not configured. Set ANTHROPIC_API_KEY or OPENAI_API_KEY');
+        }
+
+        this.status = 'executing';
+        this.emit('started', { id: this.id, type: this.type, task });
+
+        const startTime = Date.now();
+
+        try {
+            let result;
+
+            if (this.type === 'embedder' && this.embedder) {
+                // Embedding task
+                result = await this.executeEmbeddingTask(task, context);
+            } else {
+                // LLM task
+                result = await this.executeLLMTask(task, context);
+            }
+
+            const duration = Date.now() - startTime;
+
+            this.taskHistory.push({
+                task,
+                result,
+                duration,
+                timestamp: new Date().toISOString(),
+            });
+
+            this.status = 'idle';
+            this.emit('completed', { id: this.id, result, duration });
+
+            return result;
+
+        } catch (error) {
+            this.status = 'error';
+            this.emit('error', { id: this.id, error: error.message });
+            throw error;
+        }
+    }
+
+    async executeLLMTask(task, context = {}) {
+        // Build user message with context
+        let userMessage = task;
+
+        if (context.files && context.files.length > 0) {
+            userMessage += '\n\n--- FILES ---\n';
+            for (const file of context.files) {
+                try {
+                    const content = readFileSync(file, 'utf-8');
+                    userMessage += `\n### ${file}\n\`\`\`\n${content.slice(0, 10000)}\n\`\`\`\n`;
+                } catch (e) {
+                    userMessage += `\n### ${file}\n(Could not read file: ${e.message})\n`;
+                }
+            }
+        }
+
+        if (context.additionalContext) {
+            userMessage += `\n\n--- ADDITIONAL CONTEXT ---\n${context.additionalContext}`;
+        }
+
+        const response = await this.llm.complete(this.systemPrompt, userMessage, {
+            model: context.model || 'balanced',
+        });
+
+        // Track usage
+        if (response.usage) {
+            this.cost.inputTokens += response.usage.input_tokens || response.usage.prompt_tokens || 0;
+            this.cost.outputTokens += response.usage.output_tokens || response.usage.completion_tokens || 0;
+        }
+
+        return {
+            content: response.content,
+            model: response.model,
+            stopReason: response.stopReason,
+            agentId: this.id,
+            agentType: this.type,
+        };
+    }
+
+    async executeEmbeddingTask(task, context = {}) {
+        const texts = context.texts || [task];
+        const embeddings = await this.embedder.embedBatch(texts);
+
+        return {
+            embeddings: embeddings.map((e, i) => ({
+                text: texts[i].slice(0, 100),
+                embedding: Array.from(e).slice(0, 10), // Preview
+                dimensions: e.length,
+            })),
+            count: embeddings.length,
+            agentId: this.id,
+            agentType: this.type,
+        };
+    }
+
+    getStats() {
+        return {
+            id: this.id,
+            type: this.type,
+            status: this.status,
+            tasksCompleted: this.taskHistory.length,
+            cost: this.cost,
+            configured: this.llm.isConfigured() || this.type === 'embedder',
+        };
+    }
+}
+
+// ============================================
+// REAL RELAY SYNC CLIENT
+// ============================================
+
+/**
+ * Real sync client that connects to the actual relay server
+ */
+export class RelaySyncClient extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.relayUrl = options.relayUrl || 'ws://localhost:8080';
+        this.nodeId = options.nodeId || `node-${randomBytes(8).toString('hex')}`;
+        this.ws = null;
+        this.connected = false;
+        this.ledgerState = { earned: {}, spent: {}, balance: 0 };
+        this.reconnectAttempts = 0;
+        this.maxReconnects = options.maxReconnects || 10;
+    }
+
+    /**
+     * Connect to relay server
+     */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            try {
+                // Use dynamic import for WebSocket in Node
+                this.loadWebSocket().then(WebSocket => {
+                    this.ws = new WebSocket(this.relayUrl);
+
+                    const timeout = setTimeout(() => {
+                        reject(new Error('Connection timeout'));
+                    }, 10000);
+
+                    this.ws.onopen = () => {
+                        clearTimeout(timeout);
+                        this.connected = true;
+                        this.reconnectAttempts = 0;
+
+                        // Register with relay
+                        this.send({
+                            type: 'register',
+                            nodeId: this.nodeId,
+                            capabilities: ['sync', 'agent', 'compute'],
+                        });
+
+                        this.emit('connected');
+                        resolve(true);
+                    };
+
+                    this.ws.onmessage = (event) => {
+                        this.handleMessage(JSON.parse(event.data));
+                    };
+
+                    this.ws.onclose = () => {
+                        this.connected = false;
+                        this.emit('disconnected');
+                        this.scheduleReconnect();
+                    };
+
+                    this.ws.onerror = (error) => {
+                        clearTimeout(timeout);
+                        reject(error);
+                    };
+
+                }).catch(reject);
+            } catch (error) {
+                reject(error);
+            }
+        });
+    }
+
+    async loadWebSocket() {
+        if (typeof WebSocket !== 'undefined') {
+            return WebSocket;
+        }
+        const ws = await import('ws');
+        return ws.default || ws.WebSocket;
+    }
+
+    scheduleReconnect() {
+        if (this.reconnectAttempts < this.maxReconnects) {
+            this.reconnectAttempts++;
+            const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts), 30000);
+            setTimeout(() => this.connect().catch(() => {}), delay);
+        }
+    }
+
+    handleMessage(message) {
+        switch (message.type) {
+            case 'registered':
+                console.log(`[Sync] Registered with relay as ${this.nodeId}`);
+                this.emit('registered', message);
+                break;
+
+            case 'ledger_sync':
+                this.mergeLedgerState(message.state);
+                break;
+
+            case 'peer_state':
+                this.emit('peer_state', message);
+                break;
+
+            case 'time_crystal_sync':
+                this.emit('time_crystal', message);
+                break;
+
+            default:
+                this.emit('message', message);
+        }
+    }
+
+    /**
+     * Send message to relay
+     */
+    send(message) {
+        if (this.connected && this.ws?.readyState === 1) {
+            this.ws.send(JSON.stringify(message));
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Sync ledger state with relay
+     */
+    syncLedger(state) {
+        return this.send({
+            type: 'ledger_sync',
+            nodeId: this.nodeId,
+            state,
+            timestamp: Date.now(),
+        });
+    }
+
+    /**
+     * Merge incoming ledger state (CRDT)
+     */
+    mergeLedgerState(remoteState) {
+        if (!remoteState) return;
+
+        // Merge earned (max wins)
+        for (const [key, value] of Object.entries(remoteState.earned || {})) {
+            const current = this.ledgerState.earned[key] || 0;
+            this.ledgerState.earned[key] = Math.max(current, value);
+        }
+
+        // Merge spent (max wins)
+        for (const [key, value] of Object.entries(remoteState.spent || {})) {
+            const current = this.ledgerState.spent[key] || 0;
+            this.ledgerState.spent[key] = Math.max(current, value);
+        }
+
+        // Recalculate balance
+        const totalEarned = Object.values(this.ledgerState.earned).reduce((a, b) => a + b, 0);
+        const totalSpent = Object.values(this.ledgerState.spent).reduce((a, b) => a + b, 0);
+        this.ledgerState.balance = totalEarned - totalSpent;
+
+        this.emit('ledger_updated', this.ledgerState);
+    }
+
+    /**
+     * Credit rUv
+     */
+    credit(amount, reason) {
+        const key = `${Date.now()}-${reason}`;
+        this.ledgerState.earned[key] = amount;
+        this.ledgerState.balance += amount;
+        this.syncLedger(this.ledgerState);
+        return this.ledgerState.balance;
+    }
+
+    /**
+     * Spend rUv
+     */
+    spend(amount, reason) {
+        if (this.ledgerState.balance < amount) {
+            throw new Error('Insufficient balance');
+        }
+        const key = `${Date.now()}-${reason}`;
+        this.ledgerState.spent[key] = amount;
+        this.ledgerState.balance -= amount;
+        this.syncLedger(this.ledgerState);
+        return this.ledgerState.balance;
+    }
+
+    getBalance() {
+        return this.ledgerState.balance;
+    }
+
+    close() {
+        if (this.ws) {
+            this.ws.close();
+        }
+    }
+}
+
+// ============================================
+// REAL AGENT MANAGER
+// ============================================
+
+/**
+ * Manager for real agents with actual execution
+ */
+export class RealAgentManager extends EventEmitter {
+    constructor(options = {}) {
+        super();
+        this.agents = new Map();
+        this.syncClient = null;
+        this.embedder = null;
+        this.options = options;
+    }
+
+    async initialize() {
+        // Initialize embedder
+        this.embedder = new RealEmbedder();
+        await this.embedder.initialize();
+
+        // Connect to relay if URL provided
+        if (this.options.relayUrl || this.options.enableSync) {
+            this.syncClient = new RelaySyncClient({
+                relayUrl: this.options.relayUrl || 'ws://localhost:8080',
+                nodeId: this.options.nodeId,
+            });
+
+            try {
+                await this.syncClient.connect();
+                console.log('[AgentManager] Connected to relay server');
+            } catch (error) {
+                console.warn('[AgentManager] Relay connection failed:', error.message);
+            }
+        }
+
+        return this;
+    }
+
+    /**
+     * Spawn a real agent
+     */
+    async spawn(type, options = {}) {
+        const agent = new RealAgent(type, {
+            provider: options.provider || this.options.provider || 'anthropic',
+            apiKey: options.apiKey || this.options.apiKey,
+            model: options.model || 'balanced',
+        });
+
+        await agent.initialize();
+        this.agents.set(agent.id, agent);
+
+        // Track agent spawn with credits
+        if (this.syncClient?.connected) {
+            // Deduct spawn cost
+            const spawnCost = { researcher: 1, coder: 2, reviewer: 1.5, tester: 1, analyst: 1, optimizer: 2, coordinator: 3, embedder: 0.5 };
+            try {
+                this.syncClient.spend(spawnCost[type] || 1, `spawn-${type}`);
+            } catch (e) {
+                // Continue even if no credits
+            }
+        }
+
+        this.emit('agent_spawned', { id: agent.id, type });
+        return agent;
+    }
+
+    /**
+     * Execute task on agent
+     */
+    async execute(agentId, task, context = {}) {
+        const agent = this.agents.get(agentId);
+        if (!agent) {
+            throw new Error(`Agent not found: ${agentId}`);
+        }
+
+        const result = await agent.execute(task, context);
+
+        // Credit for completed task
+        if (this.syncClient?.connected) {
+            this.syncClient.credit(1, `task-${agent.type}`);
+        }
+
+        return result;
+    }
+
+    /**
+     * Quick execute - spawn and run in one call
+     */
+    async quickExecute(type, task, context = {}) {
+        const agent = await this.spawn(type, context);
+        return agent.execute(task, context);
+    }
+
+    getAgent(id) {
+        return this.agents.get(id);
+    }
+
+    listAgents() {
+        return Array.from(this.agents.values()).map(a => a.getStats());
+    }
+
+    getBalance() {
+        return this.syncClient?.getBalance() || 0;
+    }
+
+    async close() {
+        if (this.syncClient) {
+            this.syncClient.close();
+        }
+    }
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+// Classes are already exported via 'export class' declarations above
+// Only export non-class items here
+export { AGENT_PROMPTS, LLM_PROVIDERS };
+
+export default RealAgentManager;