π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.mdnew file mode 100644index 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]+