@claude-flow/cli 3.0.0-alpha.108 → 3.0.0-alpha.109

package/README.md

@@ -82,6 +82,27 @@ Claude-Flow v3 introduces **self-learning neural capabilities** that no other ag
 - **Claims System** - Human-agent work ownership with handoff protocols
 - **Byzantine Consensus** - Fault-tolerant coordination even with malicious agents
 
+### Intelligent 3-Tier Model Routing (ADR-026)
+
+Automatically routes tasks to the optimal handler for **75% cost reduction** and **2.5x quota extension** for Claude Max users:
+
+| Tier | Handler | Latency | Cost | Use Cases |
+|------|---------|---------|------|-----------|
+| **1** | Agent Booster (WASM) | <1ms | $0 | Simple transforms: var→const, add-types, remove-console |
+| **2** | Haiku/Sonnet | 500ms-2s | $0.0002-$0.003 | Bug fixes, refactoring, feature implementation |
+| **3** | Opus | 2-5s | $0.015 | Architecture, security design, distributed systems |
+
+**Benchmark Results:** 100% accuracy, 0.57ms avg routing latency
+
+```bash
+# Example: Task automatically routed to appropriate tier
+npx claude-flow@v3alpha hooks pre-task --description "Add type annotations to server.ts"
+# → [AGENT_BOOSTER_AVAILABLE] Skip LLM - use Agent Booster for "add-types"
+
+npx claude-flow@v3alpha hooks pre-task --description "Design OAuth2 with PKCE"
+# → [TASK_MODEL_RECOMMENDATION] Use model="opus" for this task
+```
+
 ---
 
 ## Quick Start

package/dist/src/commands/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,aAAa,CAAC;AAklH1E,eAAO,MAAM,YAAY,EAAE,OA0F1B,CAAC;AAEF,eAAe,YAAY,CAAC"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../src/commands/hooks.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiC,MAAM,aAAa,CAAC;AA02H1E,eAAO,MAAM,YAAY,EAAE,OAiG1B,CAAC;AAEF,eAAe,YAAY,CAAC"}

package/dist/src/commands/hooks.js

@@ -1206,6 +1206,53 @@ const preTaskCommand = {
                 output.writeln(output.bold('Recommendations'));
                 output.printList(result.recommendations);
             }
+            // Enhanced model routing with Agent Booster AST (ADR-026)
+            try {
+                const { getEnhancedModelRouter } = await import('../ruvector/enhanced-model-router.js');
+                const router = getEnhancedModelRouter();
+                const routeResult = await router.route(description, { filePath: ctx.flags.file });
+                output.writeln();
+                output.writeln(output.bold('Intelligent Model Routing'));
+                if (routeResult.tier === 1) {
+                    // Agent Booster can handle this task - skip LLM entirely
+                    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.dim('─'.repeat(60)));
+                    output.writeln(output.bold(output.success(`[AGENT_BOOSTER_AVAILABLE] Skip LLM - use Agent Booster for "${routeResult.agentBoosterIntent?.type}"`)));
+                    output.writeln(output.dim(`Confidence: ${(routeResult.confidence * 100).toFixed(0)}% | Intent: ${routeResult.agentBoosterIntent?.description}`));
+                    output.writeln(output.dim('─'.repeat(60)));
+                }
+                else {
+                    // LLM required - show tier and model recommendation
+                    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)));
+                }
+                // Add routing result for programmatic use
+                result.routeResult = routeResult;
+                result.recommendedModel = routeResult.model;
+                result.modelRouting = {
+                    tier: routeResult.tier,
+                    handler: routeResult.handler,
+                    model: routeResult.model,
+                    confidence: routeResult.confidence,
+                    complexity: routeResult.complexity,
+                    reasoning: routeResult.reasoning,
+                    canSkipLLM: routeResult.canSkipLLM,
+                    agentBoosterIntent: routeResult.agentBoosterIntent
+                };
+            }
+            catch {
+                // Enhanced router not available, skip recommendation
+            }
             return { success: true, data: result };
         }
         catch (error) {
@@ -2979,6 +3026,194 @@ const tokenOptimizeCommand = {
         }
     }
 };
+// Model Router command - intelligent model selection (haiku/sonnet/opus)
+const modelRouteCommand = {
+    name: 'model-route',
+    description: 'Route task to optimal Claude model (haiku/sonnet/opus) based on complexity',
+    options: [
+        { name: 'task', short: 't', type: 'string', description: 'Task description to route', required: true },
+        { name: 'context', short: 'c', type: 'string', description: 'Additional context' },
+        { name: 'prefer-cost', type: 'boolean', description: 'Prefer lower cost models' },
+        { name: 'prefer-quality', type: 'boolean', description: 'Prefer higher quality models' },
+    ],
+    examples: [
+        { command: 'claude-flow hooks model-route -t "fix typo"', description: 'Route simple task (likely haiku)' },
+        { command: 'claude-flow hooks model-route -t "architect auth system"', description: 'Route complex task (likely opus)' },
+    ],
+    action: async (ctx) => {
+        const task = ctx.args[0] || ctx.flags.task;
+        if (!task) {
+            output.printError('Task description required. Use --task or -t flag.');
+            return { success: false, exitCode: 1 };
+        }
+        output.printInfo(`Analyzing task complexity: ${output.highlight(task.slice(0, 50))}...`);
+        try {
+            const result = await callMCPTool('hooks/model-route', {
+                task,
+                context: ctx.flags.context,
+                preferCost: ctx.flags['prefer-cost'],
+                preferQuality: ctx.flags['prefer-quality'],
+            });
+            if (ctx.flags.format === 'json') {
+                output.printJson(result);
+                return { success: true, data: result };
+            }
+            output.writeln();
+            // Model icon based on selection
+            const modelIcons = {
+                haiku: '🌸',
+                sonnet: '📜',
+                opus: '🎭',
+            };
+            const model = result.model || 'sonnet';
+            const icon = modelIcons[model] || '🤖';
+            // Calculate cost savings compared to opus
+            const costMultipliers = { haiku: 0.04, sonnet: 0.2, opus: 1.0 };
+            const costSavings = model !== 'opus'
+                ? `${((1 - costMultipliers[model]) * 100).toFixed(0)}% vs opus`
+                : undefined;
+            // Determine complexity level
+            const complexityScore = typeof result.complexity === 'number' ? result.complexity : 0.5;
+            const complexityLevel = complexityScore > 0.7 ? 'high' : complexityScore > 0.4 ? 'medium' : 'low';
+            output.printBox([
+                `Selected Model: ${icon} ${output.bold(model.toUpperCase())}`,
+                `Confidence: ${(result.confidence * 100).toFixed(1)}%`,
+                `Complexity: ${complexityLevel} (${(complexityScore * 100).toFixed(0)}%)`,
+                costSavings ? `Cost Savings: ${costSavings}` : '',
+            ].filter(Boolean).join('\n'), 'Model Routing Result');
+            output.writeln();
+            output.writeln(output.bold('Reasoning'));
+            output.writeln(output.dim(result.reasoning || 'Based on task complexity analysis'));
+            if (result.implementation) {
+                output.writeln();
+                output.writeln(output.dim(`Implementation: ${result.implementation}`));
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            if (error instanceof MCPClientError) {
+                output.printError(`Model routing failed: ${error.message}`);
+            }
+            else {
+                output.printError(`Unexpected error: ${String(error)}`);
+            }
+            return { success: false, exitCode: 1 };
+        }
+    }
+};
+// Model Outcome command - record routing outcomes for learning
+const modelOutcomeCommand = {
+    name: 'model-outcome',
+    description: 'Record model routing outcome for learning',
+    options: [
+        { name: 'task', short: 't', type: 'string', description: 'Task that was executed', required: true },
+        { name: 'model', short: 'm', type: 'string', description: 'Model that was used (haiku/sonnet/opus)', required: true },
+        { name: 'outcome', short: 'o', type: 'string', description: 'Outcome (success/failure/escalated)', required: true },
+        { name: 'quality', short: 'q', type: 'number', description: 'Quality score 0-1' },
+    ],
+    examples: [
+        { command: 'claude-flow hooks model-outcome -t "fix typo" -m haiku -o success', description: 'Record successful haiku task' },
+        { command: 'claude-flow hooks model-outcome -t "auth system" -m sonnet -o escalated', description: 'Record escalation to opus' },
+    ],
+    action: async (ctx) => {
+        const task = ctx.flags.task;
+        const model = ctx.flags.model;
+        const outcome = ctx.flags.outcome;
+        if (!task || !model || !outcome) {
+            output.printError('Task, model, and outcome are required.');
+            return { success: false, exitCode: 1 };
+        }
+        try {
+            const result = await callMCPTool('hooks/model-outcome', {
+                task,
+                model,
+                outcome,
+                quality: ctx.flags.quality,
+            });
+            output.printSuccess(`Outcome recorded for ${model}: ${outcome}`);
+            if (result.learningUpdate) {
+                output.writeln(output.dim(result.learningUpdate));
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            output.printError(`Failed to record outcome: ${String(error)}`);
+            return { success: false, exitCode: 1 };
+        }
+    }
+};
+// Model Stats command - view routing statistics
+const modelStatsCommand = {
+    name: 'model-stats',
+    description: 'View model routing statistics and learning metrics',
+    options: [
+        { name: 'detailed', short: 'd', type: 'boolean', description: 'Show detailed breakdown' },
+    ],
+    examples: [
+        { command: 'claude-flow hooks model-stats', description: 'View routing stats' },
+        { command: 'claude-flow hooks model-stats --detailed', description: 'Show detailed breakdown' },
+    ],
+    action: async (ctx) => {
+        try {
+            const result = await callMCPTool('hooks/model-stats', {
+                detailed: ctx.flags.detailed,
+            });
+            if (ctx.flags.format === 'json') {
+                output.printJson(result);
+                return { success: true, data: result };
+            }
+            if (!result.available) {
+                output.printWarning(result.message || 'Model router not available');
+                return { success: true, data: result };
+            }
+            // Calculate cost savings based on model distribution
+            const dist = result.modelDistribution || { haiku: 0, sonnet: 0, opus: 0 };
+            const totalTasks = result.totalDecisions || 0;
+            const costMultipliers = { haiku: 0.04, sonnet: 0.2, opus: 1.0 };
+            let totalCost = 0;
+            let maxCost = totalTasks; // If all were opus
+            for (const [model, count] of Object.entries(dist)) {
+                if (model !== 'inherit') {
+                    totalCost += count * (costMultipliers[model] || 1);
+                }
+            }
+            const costSavings = maxCost > 0 ? ((1 - totalCost / maxCost) * 100).toFixed(1) : '0';
+            output.writeln();
+            output.printBox([
+                `Total Tasks Routed: ${totalTasks}`,
+                `Avg Complexity: ${((result.avgComplexity || 0) * 100).toFixed(1)}%`,
+                `Avg Confidence: ${((result.avgConfidence || 0) * 100).toFixed(1)}%`,
+                `Cost Savings: ${costSavings}% vs all-opus`,
+                `Circuit Breaker Trips: ${result.circuitBreakerTrips || 0}`,
+            ].join('\n'), 'Model Routing Statistics');
+            if (dist && Object.keys(dist).length > 0) {
+                output.writeln();
+                output.writeln(output.bold('Model Distribution'));
+                output.printTable({
+                    columns: [
+                        { key: 'model', header: 'Model', width: 10 },
+                        { key: 'count', header: 'Tasks', width: 8, align: 'right' },
+                        { key: 'percentage', header: '%', width: 8, align: 'right' },
+                        { key: 'costMultiplier', header: 'Cost', width: 8, align: 'right' },
+                    ],
+                    data: Object.entries(dist)
+                        .filter(([model]) => model !== 'inherit')
+                        .map(([model, count]) => ({
+                        model: model.toUpperCase(),
+                        count,
+                        percentage: totalTasks > 0 ? `${((count / totalTasks) * 100).toFixed(1)}%` : '0%',
+                        costMultiplier: `${costMultipliers[model] || 1}x`,
+                    })),
+                });
+            }
+            return { success: true, data: result };
+        }
+        catch (error) {
+            output.printError(`Failed to get stats: ${String(error)}`);
+            return { success: false, exitCode: 1 };
+        }
+    }
+};
 // Main hooks command
 export const hooksCommand = {
     name: 'hooks',
@@ -3009,6 +3244,10 @@ export const hooksCommand = {
         coverageGapsCommand,
         // Token optimization
         tokenOptimizeCommand,
+        // Model routing (tiny-dancer integration)
+        modelRouteCommand,
+        modelOutcomeCommand,
+        modelStatsCommand,
         // Backward-compatible aliases for v2
         routeTaskCommand,
         sessionStartCommand,
@@ -3053,7 +3292,10 @@ export const hooksCommand = {
             `${output.highlight('coverage-route')}  - Route tasks based on coverage gaps (ruvector)`,
             `${output.highlight('coverage-suggest')}- Suggest coverage improvements`,
             `${output.highlight('coverage-gaps')}   - List all coverage gaps with agents`,
-            `${output.highlight('token-optimize')} - Token optimization (30-50% savings)`
+            `${output.highlight('token-optimize')} - Token optimization (30-50% savings)`,
+            `${output.highlight('model-route')}    - Route to optimal model (haiku/sonnet/opus)`,
+            `${output.highlight('model-outcome')}  - Record model routing outcome`,
+            `${output.highlight('model-stats')}    - View model routing statistics`
         ]);
         output.writeln();
         output.writeln('Run "claude-flow hooks <subcommand> --help" for subcommand help');