Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

Checkpoint: File edits

rUv1636f2ee9451
diff --git a/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md b/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md
new file mode 100644
index 0000000000..1a5a4cb9da
--- /dev/null
+++ b/v3/implementation/adrs/ADR-026-agent-booster-model-routing.md
@@ -0,0 +1,454 @@
+# ADR-026: Agent Booster AST-Based Dynamic Model Routing
+
+**Status:** Proposed
+**Date:** 2026-01-14
+**Author:** System Architecture Designer
+**Version:** 1.0.0
+
+## Context
+
+The current model routing system uses `tiny-dancer` for neural-based complexity analysis to select between `haiku`, `sonnet`, and `opus` models. While effective, this approach:
+
+1. Doesn't leverage AST-based analysis for code-specific tasks
+2. Can't detect when tasks can be handled entirely by Agent Booster (352x faster, $0 cost)
+3. Misses optimization opportunities for simple code transformations
+
+The `agentic-flow` package provides:
+- **AgentBoosterPreprocessor** - Detects code editing intents via AST pattern matching
+- **Agent Booster WASM Engine** - 352x faster code edits (352ms β†’ 1ms)
+- **MorphApply** - AST-based code transformations
+
+## Decision
+
+Integrate Agent Booster's AST capabilities into the model routing pipeline for **intelligent 3-tier routing**:
+
+### Routing Tiers
+
+| Tier | Handler | Latency | Cost | Use Cases |
+|------|---------|---------|------|-----------|
+| **Tier 1: Agent Booster** | WASM Engine | <1ms | $0 | Simple transforms (var→const, add types, etc.) |
+| **Tier 2: Haiku** | Claude haiku | ~500ms | $0.0002/req | Simple tasks, formatting, small edits |
+| **Tier 3: Sonnet/Opus** | Claude sonnet/opus | ~2-5s | $0.003-0.015/req | Complex reasoning, architecture, security |
+
+### Routing Flow
+
+```
+Task Input
+ β”‚
+ β–Ό
+β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+β”‚ AgentBoosterPreprocessor β”‚
+β”‚ detectIntent(task) β”‚
+β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚
+ β”œβ”€β”€ confidence >= 0.8 ──► Tier 1: Agent Booster (WASM)
+ β”‚ β€’ var-to-const
+ β”‚ β€’ add-types
+ β”‚ β€’ add-error-handling
+ β”‚ β€’ async-await
+ β”‚ β€’ add-logging
+ β”‚ β€’ remove-console
+ β”‚
+ β”œβ”€β”€ confidence < 0.8 ──► AST Complexity Analysis
+ β”‚ β”‚
+ β”‚ β–Ό
+ β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
+ β”‚ β”‚ getComplexity β”‚
+ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
+ β”‚ β”‚
+ β”‚ β”œβ”€β”€ complexity < 0.3 ──► Tier 2: Haiku
+ β”‚ β”‚
+ β”‚ β”œβ”€β”€ complexity 0.3-0.6 ──► Tier 2/3: Sonnet
+ β”‚ β”‚
+ β”‚ └── complexity > 0.6 ──► Tier 3: Opus
+ β”‚
+ └── No code intent ──► tiny-dancer model router (existing)
+```
+
+## Implementation
+
+### 1. Enhanced Model Router Interface
+
+```typescript
+// v3/@claude-flow/cli/src/ruvector/model-router.ts
+
+import { AgentBoosterPreprocessor, EditIntent, PreprocessorResult } from 'agentic-flow';
+
+export interface EnhancedRouteResult {
+ tier: 1 | 2 | 3;
+ handler: 'agent-booster' | 'haiku' | 'sonnet' | 'opus';
+ model?: 'haiku' | 'sonnet' | 'opus';
+ confidence: number;
+ complexity?: number;
+ reasoning: string;
+
+ // Agent Booster specific
+ agentBoosterIntent?: EditIntent;
+ canSkipLLM?: boolean;
+ estimatedLatencyMs: number;
+ estimatedCost: number;
+}
+
+export interface EnhancedModelRouterConfig {
+ // Agent Booster settings
+ agentBoosterEnabled: boolean;
+ agentBoosterConfidenceThreshold: number; // Default: 0.8
+ enabledIntents: string[]; // Default: all
+
+ // Complexity thresholds
+ complexityThresholds: {
+ haiku: number; // Default: 0.3
+ sonnet: number; // Default: 0.6
+ opus: number; // Default: 1.0
+ };
+
+ // Existing tiny-dancer settings
+ preferCost: boolean;
+ preferQuality: boolean;
+}
+```
+
+### 2. Enhanced Route Function
+
+```typescript
+// v3/@claude-flow/cli/src/ruvector/model-router.ts
+
+export class EnhancedModelRouter {
+ private preprocessor: AgentBoosterPreprocessor;
+ private tinyDancerRouter: ReturnType<typeof getModelRouter>;
+ private config: EnhancedModelRouterConfig;
+
+ constructor(config?: Partial<EnhancedModelRouterConfig>) {
+ this.config = {
+ agentBoosterEnabled: true,
+ agentBoosterConfidenceThreshold: 0.8,
+ enabledIntents: [
+ 'var-to-const',
+ 'add-types',
+ 'add-error-handling',
+ 'async-await',
+ 'add-logging',
+ 'remove-console'
+ ],
+ complexityThresholds: {
+ haiku: 0.3,
+ sonnet: 0.6,
+ opus: 1.0
+ },
+ preferCost: false,
+ preferQuality: false,
+ ...config
+ };
+
+ this.preprocessor = new AgentBoosterPreprocessor({
+ confidenceThreshold: this.config.agentBoosterConfidenceThreshold,
+ enabledIntents: this.config.enabledIntents
+ });
+ }
+
+ async route(task: string, context?: { filePath?: string }): Promise<EnhancedRouteResult> {
+ // Step 1: Try Agent Booster intent detection
+ if (this.config.agentBoosterEnabled) {
+ const intent = this.preprocessor.detectIntent(task);
+
+ if (intent && intent.confidence >= this.config.agentBoosterConfidenceThreshold) {
+ return {
+ tier: 1,
+ handler: 'agent-booster',
+ confidence: intent.confidence,
+ reasoning: `Agent Booster can handle "${intent.type}" with ${(intent.confidence * 100).toFixed(0)}% confidence`,
+ agentBoosterIntent: intent,
+ canSkipLLM: true,
+ estimatedLatencyMs: 1,
+ estimatedCost: 0
+ };
+ }
+ }
+
+ // Step 2: AST complexity analysis (if file path provided)
+ let complexity: number | undefined;
+ if (context?.filePath) {
+ try {
+ const { analyzeAST } = await import('./adapters/ast-adapter.js');
+ const analysis = await analyzeAST({ path: context.filePath });
+ complexity = analysis.summary.avgComplexity / 100; // Normalize to 0-1
+ } catch {
+ // AST analysis not available, continue with text-based routing
+ }
+ }
+
+ // Step 3: Text-based complexity + tiny-dancer routing
+ const tinyDancerResult = await this.tinyDancerRouter.route(task);
+
+ // Step 4: Combine AST complexity with tiny-dancer result
+ const finalComplexity = complexity !== undefined
+ ? (complexity + tinyDancerResult.complexity) / 2
+ : tinyDancerResult.complexity;
+
+ // Step 5: Determine tier based on complexity
+ const { haiku, sonnet } = this.config.complexityThresholds;
+
+ if (finalComplexity < haiku) {
+ return {
+ tier: 2,
+ handler: 'haiku',
+ model: 'haiku',
+ confidence: tinyDancerResult.confidence,
+ complexity: finalComplexity,
+ reasoning: `Low complexity (${(finalComplexity * 100).toFixed(0)}%) - using haiku`,
+ canSkipLLM: false,
+ estimatedLatencyMs: 500,
+ estimatedCost: 0.0002
+ };
+ }
+
+ if (finalComplexity < sonnet) {
+ return {
+ tier: 2,
+ handler: 'sonnet',
+ model: 'sonnet',
+ confidence: tinyDancerResult.confidence,
+ complexity: finalComplexity,
+ reasoning: `Medium complexity (${(finalComplexity * 100).toFixed(0)}%) - using sonnet`,
+ canSkipLLM: false,
+ estimatedLatencyMs: 2000,
+ estimatedCost: 0.003
+ };
+ }
+
+ return {
+ tier: 3,
+ handler: 'opus',
+ model: 'opus',
+ confidence: tinyDancerResult.confidence,
+ complexity: finalComplexity,
+ reasoning: `High complexity (${(finalComplexity * 100).toFixed(0)}%) - using opus`,
+ canSkipLLM: false,
+ estimatedLatencyMs: 5000,
+ estimatedCost: 0.015
+ };
+ }
+
+ /**
+ * Execute task using the appropriate tier
+ */
+ async execute(task: string, context?: { filePath?: string; originalCode?: string }): Promise<{
+ result: string | PreprocessorResult;
+ routeResult: EnhancedRouteResult;
+ }> {
+ const routeResult = await this.route(task, context);
+
+ if (routeResult.tier === 1 && routeResult.agentBoosterIntent) {
+ // Execute with Agent Booster (skip LLM entirely)
+ const abResult = await this.preprocessor.tryApply(routeResult.agentBoosterIntent);
+ return { result: abResult, routeResult };
+ }
+
+ // Return routing result - caller handles LLM invocation
+ return { result: routeResult.reasoning, routeResult };
+ }
+}
+```
+
+### 3. Pre-Task Hook Integration
+
+```typescript
+// v3/@claude-flow/cli/src/commands/hooks.ts (update preTaskCommand)
+
+// In pre-task action, after existing logic:
+
+// Enhanced model routing with Agent Booster AST
+try {
+ const { EnhancedModelRouter } = await import('../ruvector/enhanced-model-router.js');
+ const router = new EnhancedModelRouter();
+ const routeResult = await router.route(description, { filePath: ctx.flags.file as string });
+
+ output.writeln();
+ output.writeln(output.bold('Intelligent Model Routing'));
+
+ if (routeResult.tier === 1) {
+ // Agent Booster can handle this
+ output.writeln(output.success(` Tier 1: Agent Booster (WASM)`));
+ output.writeln(output.dim(` Intent: ${routeResult.agentBoosterIntent?.type}`));
+ output.writeln(output.dim(` Latency: <1ms | Cost: $0`));
+ output.writeln();
+ output.writeln(output.bold(output.success(`[AGENT_BOOSTER_AVAILABLE] Skip LLM - use Agent Booster for "${routeResult.agentBoosterIntent?.type}"`)));
+ } else {
+ // LLM required
+ output.writeln(` Tier ${routeResult.tier}: ${routeResult.handler.toUpperCase()}`);
+ output.writeln(output.dim(` Complexity: ${((routeResult.complexity || 0) * 100).toFixed(0)}%`));
+ output.writeln(output.dim(` Est. Latency: ${routeResult.estimatedLatencyMs}ms | Cost: $${routeResult.estimatedCost.toFixed(4)}`));
+ output.writeln();
+
+ // Clear instruction for Claude
+ output.writeln(output.dim('─'.repeat(60)));
+ output.writeln(output.bold(output.success(`[TASK_MODEL_RECOMMENDATION] Use model="${routeResult.model}" for this task`)));
+ output.writeln(output.dim(`Complexity: ${((routeResult.complexity || 0) * 100).toFixed(0)}% | Confidence: ${(routeResult.confidence * 100).toFixed(0)}%`));
+ output.writeln(output.dim('─'.repeat(60)));
+ }
+
+ (result as Record<string, unknown>).routeResult = routeResult;
+} catch {
+ // Enhanced router not available, continue with basic routing
+}
+```
+
+### 4. Agent Spawn Integration
+
+```typescript
+// v3/@claude-flow/cli/src/mcp-tools/agent-tools.ts (update determineAgentModel)
+
+import { EnhancedModelRouter } from '../ruvector/enhanced-model-router.js';
+
+async function determineAgentModel(
+ agentType: string,
+ config: Record<string, unknown>,
+ task?: string
+): Promise<{
+ model: ClaudeModel;
+ routedBy: 'explicit' | 'router' | 'agent-booster' | 'default';
+ canSkipLLM?: boolean;
+ agentBoosterIntent?: string;
+}> {
+ // 1. Explicit model in config
+ if (config.model && ['haiku', 'sonnet', 'opus', 'inherit'].includes(config.model as string)) {
+ return { model: config.model as ClaudeModel, routedBy: 'explicit' };
+ }
+
+ // 2. Enhanced routing with Agent Booster AST
+ if (task) {
+ try {
+ const router = new EnhancedModelRouter();
+ const routeResult = await router.route(task, { filePath: config.filePath as string });
+
+ if (routeResult.tier === 1) {
+ // Agent Booster can handle this
+ return {
+ model: 'haiku', // Use haiku as fallback if AB fails
+ routedBy: 'agent-booster',
+ canSkipLLM: true,
+ agentBoosterIntent: routeResult.agentBoosterIntent?.type
+ };
+ }
+
+ return {
+ model: routeResult.model!,
+ routedBy: 'router'
+ };
+ } catch {
+ // Fall through to defaults
+ }
+ }
+
+ // 3. Agent type defaults
+ const defaultModel = AGENT_TYPE_MODEL_DEFAULTS[agentType];
+ if (defaultModel) {
+ return { model: defaultModel, routedBy: 'default' };
+ }
+
+ // 4. Fallback to sonnet
+ return { model: 'sonnet', routedBy: 'default' };
+}
+```
+
+### 5. CLAUDE.md Instructions Update
+
+```markdown
+### πŸ€– AGENT BOOSTER INTEGRATION (AUTOMATIC)
+
+**The routing system now has 3 tiers for optimal cost/performance:**
+
+| Tier | Handler | When Used |
+|------|---------|-----------|
+| **1** | Agent Booster | Simple code transforms (var→const, add types, etc.) - **Skip LLM entirely** |
+| **2** | Haiku | Simple tasks, low complexity (<30%) |
+| **3** | Sonnet/Opus | Complex tasks, high complexity (>30%) |
+
+**When you see these recommendations:**
+
+1. `[AGENT_BOOSTER_AVAILABLE]` β†’ The task can be handled by Agent Booster (352x faster, $0)
+ - Use the `agent_booster_edit_file` MCP tool instead of Task tool
+ - Example: `mcp__agentic-flow__agent_booster_edit_file({ target_filepath: "...", instructions: "...", code_edit: "..." })`
+
+2. `[TASK_MODEL_RECOMMENDATION] Use model="X"` β†’ Use that model in Task tool
+ - Example: `Task({ ..., model: "opus" })`
+
+**Agent Booster Intent Types (Tier 1):**
+- `var-to-const` - Convert var to const/let
+- `add-types` - Add TypeScript types
+- `add-error-handling` - Wrap in try/catch
+- `async-await` - Convert callbacks to async/await
+- `add-logging` - Add console.log statements
+- `remove-console` - Remove console.* calls
+```
+
+## File Structure
+
+```
+v3/@claude-flow/cli/src/
+β”œβ”€β”€ ruvector/
+β”‚ β”œβ”€β”€ model-router.ts # Existing tiny-dancer router
+β”‚ β”œβ”€β”€ enhanced-model-router.ts # NEW: Agent Booster + AST integration
+β”‚ └── adapters/
+β”‚ └── ast-adapter.ts # Existing: AST analysis
+β”œβ”€β”€ mcp-tools/
+β”‚ └── agent-tools.ts # UPDATED: Enhanced routing
+└── commands/
+ └── hooks.ts # UPDATED: Enhanced pre-task output
+```
+
+## Consequences
+
+### Positive
+
+1. **352x faster** code edits when Agent Booster handles them
+2. **$0 cost** for Tier 1 operations (WASM, no API calls)
+3. **Better model selection** via AST complexity analysis
+4. **Graceful fallback** - works without agentic-flow installed
+5. **Cost optimization** - routes simple tasks to cheaper models
+
+### Negative
+
+1. **Additional dependency** on agentic-flow for Agent Booster
+2. **More complex routing logic** to maintain
+3. **Potential for incorrect tier selection** on edge cases
+
+### Neutral
+
+1. **Backwards compatible** - existing routing continues to work
+2. **Optional enhancement** - can disable Agent Booster tier
+
+## Performance Targets
+
+| Metric | Target |
+|--------|--------|
+| Agent Booster intent detection | <1ms |
+| AST complexity analysis | <50ms |
+| Total routing decision | <100ms |
+| Tier 1 execution | <5ms |
+| Cost savings (Tier 1) | 100% |
+| Cost savings (Tier 2 vs 3) | 80-95% |
+
+## Testing Strategy
+
+1. **Unit tests** for EnhancedModelRouter
+2. **Integration tests** for Agent Booster intent detection
+3. **E2E tests** for full routing pipeline
+4. **Benchmark tests** for latency targets
+
+## References
+
+- ADR-017: RuVector Integration Architecture
+- ADR-018: Claude Code Integration
+- Agent Booster: https://github.com/anthropics/agent-booster
+- agentic-flow: https://github.com/ruvnet/agentic-flow
+- tiny-dancer: Neural model router
+
+---
+
+## Implementation Status
+
+**Status:** Proposed
+**Priority:** High
+**Estimated Effort:** 2-3 days
+**Dependencies:** [email protected]+