agentic-flow 1.2.7 → 1.3.1

package/docs/plans/agent-booster/02-INTEGRATION.md

@@ -0,0 +1,771 @@
+# Agent Booster: Integration Guide
+
+## 🔌 Agentic-Flow Integration
+
+### Overview
+
+Agent Booster integrates seamlessly with agentic-flow as an **optional performance accelerator** for code editing operations. When enabled, it replaces slow LLM-based code application with ultra-fast vector-based semantic merging.
+
+### Integration Strategy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Agentic-Flow Agent                        │
+│                                                               │
+│  Agent receives task: "Add error handling to parseConfig"    │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│              Tool: edit_file (Enhanced)                      │
+│                                                               │
+│  Check: AGENT_BOOSTER_ENABLED?                              │
+└────────┬───────────────────────────────────┬────────────────┘
+         │ YES                                │ NO
+         ▼                                    ▼
+┌────────────────────────┐    ┌──────────────────────────────┐
+│  Agent Booster         │    │  Original Behavior           │
+│  (30ms, $0)           │    │  (LLM rewrite or API)        │
+│                        │    │  (6000ms, $0.01)             │
+│  ├─ Parse AST          │    │                              │
+│  ├─ Vector search      │    │  ├─ Full file rewrite        │
+│  ├─ Smart merge        │    │  │  or                       │
+│  └─ Validate           │    │  └─ Morph LLM API call       │
+│                        │    │                              │
+│  Confidence >= 65%?    │    │                              │
+│  ├─ YES: Return result │    │                              │
+│  └─ NO: Fallback to → │────┘                              │
+└────────────────────────┘                                    │
+         │                                                     │
+         └─────────────────────────────────────────────────────┘
+                                 │
+                                 ▼
+                        ┌────────────────┐
+                        │  Final Result  │
+                        └────────────────┘
+```
+
+### Environment Variables
+
+```bash
+# .env
+
+# ═══════════════════════════════════════════════════════════
+# Agent Booster Configuration
+# ═══════════════════════════════════════════════════════════
+
+# Enable Agent Booster for code edits (default: false)
+AGENT_BOOSTER_ENABLED=true
+
+# Embedding model to use
+# Options: jina-code-v2 (best), all-MiniLM-L6-v2 (fast)
+# Default: jina-code-v2
+AGENT_BOOSTER_MODEL=jina-code-v2
+
+# Confidence threshold (0.0 - 1.0)
+# If confidence < threshold, fallback to LLM
+# Default: 0.65
+AGENT_BOOSTER_CONFIDENCE_THRESHOLD=0.65
+
+# Enable fallback to Morph LLM when confidence is low
+# Default: true
+AGENT_BOOSTER_FALLBACK_TO_MORPH=true
+
+# Morph API key for fallback (optional)
+MORPH_API_KEY=sk-morph-xxx
+
+# Model cache directory (optional)
+# Default: ~/.cache/agent-booster
+AGENT_BOOSTER_CACHE_DIR=/path/to/cache
+
+# Enable debug logging (default: false)
+AGENT_BOOSTER_DEBUG=false
+
+# Maximum number of chunks to extract per file (default: 100)
+AGENT_BOOSTER_MAX_CHUNKS=100
+
+# Enable embedding caching (default: true)
+AGENT_BOOSTER_CACHE_EMBEDDINGS=true
+```
+
+### Tool Implementation
+
+#### Enhanced `edit_file` Tool
+
+```typescript
+// src/tools/edit-file.ts
+
+import { AgentBooster } from 'agent-booster';
+import { readFileSync, writeFileSync } from 'fs';
+
+let booster: AgentBooster | null = null;
+
+// Initialize on first use
+function getBooster(): AgentBooster | null {
+  if (process.env.AGENT_BOOSTER_ENABLED !== 'true') {
+    return null;
+  }
+
+  if (!booster) {
+    booster = new AgentBooster({
+      model: process.env.AGENT_BOOSTER_MODEL || 'jina-code-v2',
+      confidenceThreshold: parseFloat(
+        process.env.AGENT_BOOSTER_CONFIDENCE_THRESHOLD || '0.65'
+      ),
+      fallbackToMorph: process.env.AGENT_BOOSTER_FALLBACK_TO_MORPH === 'true',
+      morphApiKey: process.env.MORPH_API_KEY,
+      debug: process.env.AGENT_BOOSTER_DEBUG === 'true',
+    });
+  }
+
+  return booster;
+}
+
+export const editFileTool = {
+  name: 'edit_file',
+  description: 'Apply semantic code edits to files',
+  parameters: {
+    type: 'object',
+    properties: {
+      file_path: {
+        type: 'string',
+        description: 'Path to the file to edit',
+      },
+      edit_description: {
+        type: 'string',
+        description: 'Description of the edit to apply',
+      },
+      language: {
+        type: 'string',
+        enum: ['javascript', 'typescript', 'python', 'rust'],
+        description: 'Programming language',
+      },
+    },
+    required: ['file_path', 'edit_description'],
+  },
+
+  async execute(params: {
+    file_path: string;
+    edit_description: string;
+    language?: string;
+  }) {
+    const { file_path, edit_description, language } = params;
+
+    // Read original file
+    const originalCode = readFileSync(file_path, 'utf-8');
+
+    // Try Agent Booster first if enabled
+    const booster = getBooster();
+    if (booster) {
+      try {
+        const result = await booster.applyEdit({
+          originalCode,
+          editSnippet: edit_description,
+          language: language || detectLanguage(file_path),
+        });
+
+        // Check confidence
+        if (result.confidence >= booster.config.confidenceThreshold) {
+          // High confidence - use Agent Booster result
+          writeFileSync(file_path, result.mergedCode, 'utf-8');
+
+          return {
+            success: true,
+            method: 'agent-booster',
+            confidence: result.confidence,
+            strategy: result.strategy,
+            latency_ms: result.metadata.latency_ms,
+            cost: 0,
+            message: `Applied edit using Agent Booster (${result.strategy}, confidence: ${(result.confidence * 100).toFixed(1)}%)`,
+          };
+        } else {
+          // Low confidence - fallback
+          console.log(
+            `Agent Booster confidence too low (${(result.confidence * 100).toFixed(1)}%), falling back to LLM`
+          );
+        }
+      } catch (error) {
+        console.error('Agent Booster failed, falling back to LLM:', error);
+      }
+    }
+
+    // Fallback to original behavior (LLM-based)
+    return fallbackToLLM(originalCode, edit_description, file_path);
+  },
+};
+
+// Fallback to LLM-based editing
+async function fallbackToLLM(
+  originalCode: string,
+  editDescription: string,
+  filePath: string
+) {
+  // Option 1: Use Morph LLM API
+  if (process.env.MORPH_API_KEY) {
+    const startTime = Date.now();
+    const response = await fetch('https://api.morphllm.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.MORPH_API_KEY}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'morph-v3-large',
+        messages: [{
+          role: 'user',
+          content: `<instruction>${editDescription}</instruction>\n<code>${originalCode}</code>\n<update>Apply the edit</update>`,
+        }],
+      }),
+    });
+
+    const data = await response.json();
+    const mergedCode = data.choices[0].message.content;
+    const latency = Date.now() - startTime;
+
+    writeFileSync(filePath, mergedCode, 'utf-8');
+
+    return {
+      success: true,
+      method: 'morph-llm',
+      latency_ms: latency,
+      cost: estimateCost(originalCode, mergedCode),
+      message: `Applied edit using Morph LLM API`,
+    };
+  }
+
+  // Option 2: Use main LLM to rewrite file
+  // (existing implementation)
+  return existingEditFileImplementation(originalCode, editDescription, filePath);
+}
+
+function detectLanguage(filePath: string): string {
+  const ext = filePath.split('.').pop();
+  const langMap: Record<string, string> = {
+    'js': 'javascript',
+    'jsx': 'javascript',
+    'ts': 'typescript',
+    'tsx': 'typescript',
+    'py': 'python',
+    'rs': 'rust',
+    'go': 'go',
+    'java': 'java',
+  };
+  return langMap[ext || ''] || 'javascript';
+}
+
+function estimateCost(original: string, merged: string): number {
+  const tokens = (original.length + merged.length) / 4;
+  return (tokens / 1000) * 0.003; // Rough estimate
+}
+```
+
+### CLI Integration
+
+```typescript
+// src/cli/commands/edit.ts
+
+import { Command } from 'commander';
+import { AgentBooster } from 'agent-booster';
+import { readFileSync, writeFileSync } from 'fs';
+
+export const editCommand = new Command('edit')
+  .description('Apply code edits using Agent Booster')
+  .argument('<file>', 'File to edit')
+  .argument('<description>', 'Edit description')
+  .option('--model <model>', 'Embedding model', 'jina-code-v2')
+  .option('--threshold <threshold>', 'Confidence threshold', '0.65')
+  .option('--fallback', 'Fallback to Morph LLM if confidence low', false)
+  .option('--dry-run', 'Show result without writing', false)
+  .action(async (file: string, description: string, options) => {
+    console.log(`📝 Editing ${file}...`);
+    console.log(`📋 Edit: ${description}\n`);
+
+    const booster = new AgentBooster({
+      model: options.model,
+      confidenceThreshold: parseFloat(options.threshold),
+      fallbackToMorph: options.fallback,
+    });
+
+    const originalCode = readFileSync(file, 'utf-8');
+    const startTime = Date.now();
+
+    try {
+      const result = await booster.applyEdit({
+        originalCode,
+        editSnippet: description,
+        language: detectLanguage(file),
+      });
+
+      const latency = Date.now() - startTime;
+
+      // Display results
+      console.log(`✅ Success!`);
+      console.log(`   Strategy: ${result.strategy}`);
+      console.log(`   Confidence: ${(result.confidence * 100).toFixed(1)}%`);
+      console.log(`   Latency: ${latency}ms`);
+      console.log(`   Cost: $0.00\n`);
+
+      if (result.confidence < parseFloat(options.threshold)) {
+        console.log(`⚠️  Warning: Low confidence (${(result.confidence * 100).toFixed(1)}%)`);
+        console.log(`   Consider using --fallback for better accuracy\n`);
+      }
+
+      if (options.dryRun) {
+        console.log('Dry run - no changes written\n');
+        console.log('Preview:');
+        console.log('─'.repeat(80));
+        console.log(result.mergedCode);
+        console.log('─'.repeat(80));
+      } else {
+        writeFileSync(file, result.mergedCode, 'utf-8');
+        console.log(`💾 Saved to ${file}`);
+      }
+    } catch (error) {
+      console.error(`❌ Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+```
+
+### Configuration Presets
+
+```typescript
+// src/config/agent-booster-presets.ts
+
+export const presets = {
+  // Maximum speed, acceptable accuracy
+  fast: {
+    model: 'all-MiniLM-L6-v2',
+    confidenceThreshold: 0.60,
+    fallbackToMorph: false,
+    cacheEmbeddings: true,
+  },
+
+  // Balanced speed and accuracy (recommended)
+  balanced: {
+    model: 'jina-code-v2',
+    confidenceThreshold: 0.65,
+    fallbackToMorph: true,
+    cacheEmbeddings: true,
+  },
+
+  // Maximum accuracy
+  accurate: {
+    model: 'jina-code-v2',
+    confidenceThreshold: 0.75,
+    fallbackToMorph: true,
+    cacheEmbeddings: false,  // Always fresh
+  },
+
+  // Offline mode (no fallback)
+  offline: {
+    model: 'jina-code-v2',
+    confidenceThreshold: 0.50,  // More lenient
+    fallbackToMorph: false,
+    cacheEmbeddings: true,
+  },
+};
+
+// Usage in .env
+// AGENT_BOOSTER_PRESET=balanced
+```
+
+### Metrics & Monitoring
+
+```typescript
+// src/utils/agent-booster-metrics.ts
+
+interface EditMetrics {
+  method: 'agent-booster' | 'morph-llm' | 'llm-rewrite';
+  latency_ms: number;
+  confidence?: number;
+  strategy?: string;
+  cost: number;
+  success: boolean;
+  timestamp: Date;
+}
+
+class MetricsCollector {
+  private metrics: EditMetrics[] = [];
+
+  record(metric: EditMetrics) {
+    this.metrics.push(metric);
+
+    // Optionally log to file
+    if (process.env.AGENT_BOOSTER_METRICS_FILE) {
+      appendFileSync(
+        process.env.AGENT_BOOSTER_METRICS_FILE,
+        JSON.stringify(metric) + '\n'
+      );
+    }
+  }
+
+  getSummary() {
+    const total = this.metrics.length;
+    const boosterEdits = this.metrics.filter(m => m.method === 'agent-booster');
+    const morphEdits = this.metrics.filter(m => m.method === 'morph-llm');
+
+    return {
+      total_edits: total,
+      agent_booster_usage: `${((boosterEdits.length / total) * 100).toFixed(1)}%`,
+      avg_latency_booster: average(boosterEdits.map(m => m.latency_ms)),
+      avg_latency_morph: average(morphEdits.map(m => m.latency_ms)),
+      total_cost_saved: morphEdits.length * 0.01,  // Estimated
+      avg_confidence: average(boosterEdits.map(m => m.confidence || 0)),
+    };
+  }
+}
+
+export const metricsCollector = new MetricsCollector();
+```
+
+### Usage Example
+
+```typescript
+// examples/agentic-flow-with-agent-booster.ts
+
+import { AgenticFlow } from 'agentic-flow';
+import { editFileTool } from './tools/edit-file';
+
+// Configure via .env
+// AGENT_BOOSTER_ENABLED=true
+// AGENT_BOOSTER_MODEL=jina-code-v2
+// AGENT_BOOSTER_CONFIDENCE_THRESHOLD=0.65
+// AGENT_BOOSTER_FALLBACK_TO_MORPH=true
+
+const agent = new AgenticFlow({
+  model: 'claude-sonnet-4',
+  tools: [editFileTool],
+  systemPrompt: `You are a code refactoring assistant.
+Use the edit_file tool to apply code changes.`,
+});
+
+// Agent will automatically use Agent Booster for fast edits
+const result = await agent.run({
+  task: 'Add error handling to all functions in src/utils/parser.ts',
+});
+
+console.log(result);
+
+// Check metrics
+import { metricsCollector } from './utils/agent-booster-metrics';
+console.log('\nPerformance Summary:');
+console.log(metricsCollector.getSummary());
+```
+
+---
+
+## 🖥️ Model Context Protocol (MCP) Server
+
+### Overview
+
+Agent Booster provides a full-featured MCP server that enables seamless integration with MCP clients like Claude Desktop, Cursor, VS Code, and other AI assistants with workspace detection.
+
+### MCP Server Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     MCP Client                               │
+│        (Claude Desktop / Cursor / VS Code)                   │
+└────────────────────┬────────────────────────────────────────┘
+                     │ MCP Protocol (stdio/HTTP)
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│               Agent Booster MCP Server                       │
+│                                                               │
+│  Tools Exposed:                                              │
+│  ├─ agent_booster_apply          (Apply single edit)        │
+│  ├─ agent_booster_batch          (Batch edits)              │
+│  ├─ agent_booster_analyze        (Analyze workspace)        │
+│  └─ agent_booster_status         (Server status)            │
+│                                                               │
+│  Resources:                                                  │
+│  └─ agent_booster://metrics      (Usage metrics)            │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│               Agent Booster Core                             │
+│          (Rust library via native addon)                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Starting the MCP Server
+
+```bash
+# Start stdio server (for Claude Desktop, etc.)
+npx agent-booster mcp
+
+# Start HTTP server
+npx agent-booster mcp --http --port 3000
+
+# With custom config
+npx agent-booster mcp --config ./agent-booster.json
+```
+
+### MCP Client Configuration
+
+#### Claude Desktop
+
+```json
+// ~/Library/Application Support/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "agent-booster": {
+      "command": "npx",
+      "args": ["agent-booster", "mcp"],
+      "env": {
+        "AGENT_BOOSTER_MODEL": "jina-code-v2",
+        "AGENT_BOOSTER_CONFIDENCE_THRESHOLD": "0.65"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+```json
+// .cursor/mcp.json
+{
+  "mcpServers": {
+    "agent-booster": {
+      "command": "npx",
+      "args": ["agent-booster", "mcp"],
+      "cwd": "${workspaceFolder}"
+    }
+  }
+}
+```
+
+#### VS Code (via MCP Extension)
+
+```json
+// .vscode/mcp.json
+{
+  "servers": {
+    "agent-booster": {
+      "command": "npx agent-booster mcp",
+      "workspaceDetection": true
+    }
+  }
+}
+```
+
+### MCP Tools
+
+#### 1. `agent_booster_apply`
+
+Apply a single code edit to a file.
+
+```json
+{
+  "name": "agent_booster_apply",
+  "description": "Apply semantic code edit using vector similarity (200x faster than LLM)",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "file_path": {
+        "type": "string",
+        "description": "Relative path to file from workspace root"
+      },
+      "edit_description": {
+        "type": "string",
+        "description": "Description of the edit to apply"
+      },
+      "language": {
+        "type": "string",
+        "enum": ["javascript", "typescript", "python", "rust", "go"],
+        "description": "Programming language (auto-detected if omitted)"
+      }
+    },
+    "required": ["file_path", "edit_description"]
+  }
+}
+```
+
+**Example Usage (Claude Desktop):**
+
+```
+User: Add error handling to the parseConfig function in src/utils/config.ts
+
+Claude: I'll use agent_booster_apply to add error handling.
+
+[Calls agent_booster_apply with:
+ file_path: "src/utils/config.ts"
+ edit_description: "add try-catch error handling to parseConfig function"]
+
+Response: {
+  "success": true,
+  "confidence": 0.92,
+  "strategy": "exact_replace",
+  "latency_ms": 35,
+  "cost": 0
+}
+
+Claude: I've successfully added error handling to the parseConfig function
+with 92% confidence in 35ms at zero cost!
+```
+
+#### 2. `agent_booster_batch`
+
+Apply multiple edits in parallel.
+
+```json
+{
+  "name": "agent_booster_batch",
+  "description": "Apply multiple code edits in parallel (up to 10x faster)",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "edits": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "file_path": { "type": "string" },
+            "edit_description": { "type": "string" }
+          }
+        },
+        "maxItems": 100
+      }
+    },
+    "required": ["edits"]
+  }
+}
+```
+
+#### 3. `agent_booster_analyze`
+
+Analyze workspace for optimization opportunities.
+
+```json
+{
+  "name": "agent_booster_analyze",
+  "description": "Analyze workspace to identify files suitable for Agent Booster",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "path": {
+        "type": "string",
+        "description": "Path to analyze (default: workspace root)"
+      },
+      "include_metrics": {
+        "type": "boolean",
+        "description": "Include detailed metrics",
+        "default": true
+      }
+    }
+  }
+}
+```
+
+#### 4. `agent_booster_status`
+
+Get server status and configuration.
+
+```json
+{
+  "name": "agent_booster_status",
+  "description": "Get Agent Booster server status and metrics",
+  "inputSchema": {
+    "type": "object",
+    "properties": {}
+  }
+}
+```
+
+### MCP Resources
+
+#### Metrics Resource
+
+```
+agent_booster://metrics
+```
+
+Returns JSON with usage statistics:
+
+```json
+{
+  "total_edits": 1247,
+  "agent_booster_usage": "82.3%",
+  "morph_fallback_usage": "17.7%",
+  "avg_latency_booster_ms": 38,
+  "avg_latency_morph_ms": 5420,
+  "total_cost_saved_usd": 22.14,
+  "avg_confidence": 0.87,
+  "uptime_hours": 12.4
+}
+```
+
+### Workspace Detection
+
+Agent Booster MCP server automatically detects workspace roots by looking for:
+
+- `.git/` directory
+- `package.json`
+- `Cargo.toml`
+- `.agent-booster.json` config file
+
+Files are resolved relative to the detected workspace root.
+
+### Performance Comparison (MCP Context)
+
+```
+Traditional MCP Flow (without Agent Booster):
+
+User request: "Add logging to 10 functions"
+  ↓
+Claude analyzes workspace (5s)
+  ↓
+For each function:
+  ├─ Read file (100ms)
+  ├─ Generate edit via LLM (6000ms)
+  ├─ Apply edit (100ms)
+  └─ Write file (50ms)
+  Total per file: ~6250ms
+
+Total time: 10 files × 6250ms = 62.5 seconds
+Total cost: 10 × $0.01 = $0.10
+
+═════════════════════════════════════════════════════
+
+Agent Booster MCP Flow:
+
+User request: "Add logging to 10 functions"
+  ↓
+Claude analyzes workspace (5s)
+  ↓
+Calls agent_booster_batch with 10 edits:
+  ├─ Parse all files in parallel (200ms)
+  ├─ Generate embeddings in parallel (400ms)
+  ├─ Apply all merges in parallel (300ms)
+  └─ Validate all files in parallel (100ms)
+  Total: ~1000ms = 1 second
+
+Total time: 6 seconds (5s analysis + 1s edits)
+Total cost: $0.00
+
+Speedup: 10x faster
+Savings: $0.10 (100%)
+```
+
+---
+
+## 📊 Metrics Dashboard
+
+Optional web dashboard for monitoring Agent Booster usage:
+
+```bash
+# Start metrics dashboard
+npx agent-booster dashboard --port 8080
+```
+
+View at `http://localhost:8080`:
+
+- Real-time edit metrics
+- Cost savings calculator
+- Performance graphs
+- Confidence distribution
+- Language breakdown
+- Failure analysis