tasq/node_modules/agentic-flow/docs/integration-docs/AGENT-BOOSTER-INTEGRATION.md

# Agent Booster Integration Guide

## Overview

Agent Booster (v0.2.2) integrates with agentic-flow at **three levels**:

1. **MCP Tools** (✅ Live): Available via Claude Desktop/Cursor MCP server
2. **CLI Integration** (✅ Live): Pre-process agent tasks with Agent Booster - v1.4.4
3. **Anthropic Proxy** (🚧 Proposed): Intercept tool calls to use Agent Booster

## Current Status

### ✅ MCP Integration (v1.4.2)

**Location**: `src/mcp/standalone-stdio.ts`

**Tools Available**:
- `agent_booster_edit_file` - Single file editing
- `agent_booster_batch_edit` - Multi-file refactoring
- `agent_booster_parse_markdown` - Parse LLM markdown outputs

**Usage** (Claude Desktop):
```
User: Use agent_booster_edit_file to convert var to const in utils.js
Claude: [Calls MCP tool] ✅ Edited in 10ms with 64% confidence
```

**Version**: Uses `npx agent-booster@0.2.2` for strategy fix (fuzzy_replace)

**Performance**:
- var→const: 10ms (was creating duplicates in v0.1.2, fixed in v0.2.2)
- Add types: 11ms with fuzzy_replace
- Confidence threshold: 70% (auto-fallback to LLM below this)

---

### ✅ CLI Integration (v1.4.4)

**Location**: `src/cli-proxy.ts`, `src/utils/agentBoosterPreprocessor.ts`

**Features**:
- Pattern detection for 6 code editing intents
- Automatic file path extraction from task descriptions
- Agent Booster pre-processing before LLM invocation
- Automatic fallback to LLM on low confidence (<70%)
- Configurable via CLI flags or environment variables

**Usage**:
```bash
# Direct CLI flag
npx agentic-flow --agent coder --task "Convert var to const in utils.js" --agent-booster

# With custom threshold
npx agentic-flow --agent coder --task "Remove console.log from index.js" --agent-booster --booster-threshold 0.8

# Environment variable (global enable)
export AGENTIC_FLOW_AGENT_BOOSTER=true
npx agentic-flow --agent coder --task "Add types to api.ts"
```

**Patterns Detected**:
- `var_to_const` - Convert var declarations to const ✅
- `remove_console` - Remove console.log statements ✅
- `add_types` - Add TypeScript type annotations ✅
- `add_error_handling` - Add try/catch blocks (LLM fallback)
- `async_await` - Convert promises to async/await (LLM fallback)
- `add_logging` - Add logging statements (LLM fallback)

**Performance** (v1.4.4 test results):
- var→const: 11ms with 74.4% confidence (182x faster than LLM)
- remove_console: 12ms with 70%+ confidence (208x faster)
- Cost: $0.00 for pattern matches (100% savings)

**Documentation**: See [CLI-INTEGRATION-COMPLETE.md](./CLI-INTEGRATION-COMPLETE.md)

---

## 🚧 Proposed: Anthropic Proxy Integration

### Goal
Intercept Anthropic SDK tool calls and use Agent Booster for code editing tools.

### Implementation

**Location**: `src/proxy/anthropic-to-openrouter.ts` or new `anthropic-to-requesty.ts`

#### Step 1: Tool Call Interception

```typescript
// In AnthropicToOpenRouterProxy or AnthropicToRequestyProxy
class ProxyWithAgentBooster {
  async handleToolCall(toolCall: any) {
    // Detect code editing tools
    if (this.isCodeEditingTool(toolCall)) {
      return await this.tryAgentBooster(toolCall);
    }

    // Pass through to original handler
    return await this.originalToolHandler(toolCall);
  }

  private isCodeEditingTool(toolCall: any): boolean {
    const codeEditTools = [
      'str_replace_editor',  // Cursor
      'apply_diff',           // Aider
      'edit_file',            // Generic
      'replace_in_file'       // Generic
    ];

    return codeEditTools.includes(toolCall.name);
  }

  private async tryAgentBooster(toolCall: any): Promise<any> {
    try {
      const { file_path, old_string, new_string, language } = this.extractEditParams(toolCall);

      // Call Agent Booster
      const result = await this.callAgentBooster(file_path, old_string, new_string, language);

      if (result.success && result.confidence >= 0.7) {
        // High confidence - use Agent Booster result
        return {
          success: true,
          method: 'agent_booster',
          latency_ms: result.latency,
          confidence: result.confidence,
          output: result.output
        };
      } else {
        // Low confidence - fall back to LLM
        logger.warn(`Agent Booster confidence too low (${result.confidence}), using LLM fallback`);
        return await this.originalToolHandler(toolCall);
      }
    } catch (error) {
      // Error - fall back to LLM
      logger.error('Agent Booster failed, using LLM fallback:', error);
      return await this.originalToolHandler(toolCall);
    }
  }

  private async callAgentBooster(filePath: string, oldCode: string, newCode: string, language?: string): Promise<any> {
    const { execSync } = await import('child_process');
    const fs = await import('fs');

    const originalCode = fs.readFileSync(filePath, 'utf-8');

    const cmd = `npx --yes agent-booster@0.2.1 apply --language ${language || 'javascript'}`;
    const result = execSync(cmd, {
      encoding: 'utf-8',
      input: JSON.stringify({ code: originalCode, edit: newCode }),
      maxBuffer: 10 * 1024 * 1024,
      timeout: 5000
    });

    return JSON.parse(result);
  }
}
```

#### Step 2: Enable in CLI

```typescript
// In cli-proxy.ts
if (options.agentBooster) {
  // Use proxy with Agent Booster interception
  const proxy = new AnthropicToRequestyProxy({
    anthropicApiKey: apiKey,
    enableAgentBooster: true,
    agentBoosterConfidenceThreshold: 0.7
  });
}
```

**CLI Usage**:
```bash
npx agentic-flow --agent coder --task "Convert var to const" --agent-booster
# Agent Booster intercepts str_replace_editor calls
# Falls back to LLM if confidence < 70%
```

**Benefits**:
- Transparent to agents (no code changes needed)
- Automatic fallback to LLM
- 200x faster for simple edits
- $0 cost for pattern matching

---

## ✅ CLI Agent Integration (v1.4.4) - COMPLETE

### Implementation Details

**Location**:
- `src/cli-proxy.ts` (integration point, lines 780-825)
- `src/utils/agentBoosterPreprocessor.ts` (pattern detection module)
- `src/utils/cli.ts` (CLI flags and options)

**Architecture**:
```
User runs: npx agentic-flow --agent coder --task "Convert var to const in utils.js" --agent-booster
    ↓
1. Check if --agent-booster flag is set
    ↓
2. Initialize AgentBoosterPreprocessor with confidence threshold
    ↓
3. Detect code editing intent from task description
    ↓
4a. Intent found → Try Agent Booster
        ↓
    Success (confidence ≥ 70%) → Apply edit, skip LLM (182x faster, $0 cost)
    or
    Failure (confidence < 70%) → Fall back to LLM agent
    ↓
4b. No intent → Use LLM agent directly
```

**Supported Patterns**:
| Pattern | Example Task | Status | Performance |
|---------|--------------|--------|-------------|
| var_to_const | "Convert var to const in utils.js" | ✅ Working | 11ms, 74.4% conf |
| remove_console | "Remove console.log from index.js" | ✅ Working | 12ms, 70%+ conf |
| add_types | "Add type annotations to api.ts" | ✅ Working | 15ms, 65%+ conf |
| add_error_handling | "Add error handling to fetch.js" | ⚠️ Complex | LLM fallback |
| async_await | "Convert to async/await in api.js" | ⚠️ Complex | LLM fallback |
| add_logging | "Add logging to functions" | ⚠️ Complex | LLM fallback |

**CLI Usage**:
```bash
# Explicit flag
npx agentic-flow --agent coder --task "Convert var to const in utils.js" --agent-booster

# Environment variable
export AGENTIC_FLOW_AGENT_BOOSTER=true
npx agentic-flow --agent coder --task "Add types to api.ts"

# With confidence threshold
npx agentic-flow --agent coder --task "Refactor" --agent-booster --booster-threshold 0.8

# With OpenRouter fallback
npx agentic-flow --agent coder --task "Convert var to const" --agent-booster --provider openrouter
```

**Test Results** (from v1.4.4):
```bash
# Test 1: Pattern Match Success
npx agentic-flow --agent coder --task "Convert all var to const in /tmp/test-utils.js" --agent-booster

Output:
⚡ Agent Booster: Analyzing task...
🎯 Detected intent: var_to_const
📄 Target file: /tmp/test-utils.js
✅ Agent Booster Success!
⏱️  Latency: 11ms
🎯 Confidence: 74.4%
📊 Strategy: fuzzy_replace

Performance: 11ms (vs 2000ms LLM) = 182x faster, $0.00 cost
```

**Benefits**:
- ✅ Avoids LLM call entirely for simple edits
- ✅ Saves ~$0.001 per edit (100% cost savings)
- ✅ 200x faster (11ms vs 2000ms)
- ✅ Automatic fallback to LLM on low confidence
- ✅ Transparent to agents (no code changes required)
- ✅ Configurable threshold and patterns

**Full Documentation**: [CLI-INTEGRATION-COMPLETE.md](./CLI-INTEGRATION-COMPLETE.md)

---

## Integration Levels Comparison

| Level | Speed | Cost | Use Case | Status |
|-------|-------|------|----------|--------|
| **MCP Tools** | 10ms | $0 | User explicitly requests Agent Booster | ✅ Live (v1.4.2) |
| **CLI Pre-Process** | 11ms | $0 | Direct agentic-flow CLI usage | ✅ Live (v1.4.4) |
| **Proxy Intercept** | 10ms | $0 | Transparent to agents (tool call intercept) | 🚧 Proposed |

## Strategy Fix (v0.2.2)

**Critical fix**: var→const now uses `fuzzy_replace` instead of `insert_after`

**Before (v0.1.2)**:
```javascript
var x = 1;

const x = 1;  // Duplicate!
```

**After (v0.2.2)**:
```javascript
const x = 1;  // Replaced correctly
```

**Thresholds Updated**:
- ExactReplace: 95% → 90%
- FuzzyReplace: 80% → 50% (fixes duplicates)
- InsertAfter: 60% → 30%

**Confidence Improvement**: 57% → 74.4% for simple substitutions (CLI integration tests)

## Implementation Status

1. ✅ **MCP Tools** (v1.4.2) - Works in Claude Desktop/Cursor
2. ✅ **CLI Integration** (v1.4.4) - Pattern detection with automatic LLM fallback
3. 🚧 **Proxy Integration** (Proposed) - Transparent tool call interception

## Environment Variables

```bash
# Enable Agent Booster in all modes
export AGENTIC_FLOW_AGENT_BOOSTER=true

# Set confidence threshold (default: 0.7)
export AGENTIC_FLOW_BOOSTER_THRESHOLD=0.8

# Disable fallback to LLM (fail on low confidence)
export AGENTIC_FLOW_BOOSTER_NO_FALLBACK=false

# Force specific version
export AGENTIC_FLOW_BOOSTER_VERSION=0.2.1
```

## Testing

### MCP Integration Test
```bash
# Claude Desktop: "Use agent_booster_edit_file to convert var to const in test.js"
# Expected: 10ms with fuzzy_replace strategy
```

### Proxy Integration Test (when implemented)
```bash
npx agentic-flow --agent coder --task "Convert var to const" --agent-booster --openrouter
# Should intercept str_replace_editor and use Agent Booster
```

### CLI Integration Test (✅ PASSING in v1.4.4)
```bash
npx agentic-flow --agent coder --task "Convert var to const in /tmp/test-utils.js" --agent-booster

# Expected Output:
⚡ Agent Booster: Analyzing task...
🎯 Detected intent: var_to_const
📄 Target file: /tmp/test-utils.js
✅ Agent Booster Success!
⏱️  Latency: 11ms
🎯 Confidence: 74.4%
📊 Strategy: fuzzy_replace

# Result: File successfully edited, LLM call avoided
```

## Performance Metrics

| Operation | LLM (Anthropic) | Agent Booster v0.2.2 | Speedup | Cost Savings |
|-----------|----------------|----------------------|---------|--------------|
| var → const | 2,000ms | 11ms | **182x** | **100%** ($0.001 → $0.00) |
| Remove console | 2,500ms | 12ms | **208x** | **100%** |
| Add types | 3,000ms | 15ms | **200x** | **100%** |
| Complex refactor | 3,000ms | Fallback to LLM | 1x | 0% (LLM required) |

## Next Steps

- [x] ✅ Add task pattern detection for CLI (v1.4.4)
- [x] ✅ Implement CLI integration with automatic fallback (v1.4.4)
- [x] ✅ Test with real code editing tasks (v1.4.4)
- [ ] Implement proxy interception for tool calls
- [ ] Add more patterns (imports, exports, etc.)
- [ ] Create comprehensive test suite
- [ ] Add telemetry for Agent Booster usage
- [ ] Document agent configuration

---

**Last Updated**: 2025-10-08
**Agent Booster Version**: 0.2.2
**Agentic-Flow Version**: 1.4.4