claude-flow-novice 1.6.3 → 1.6.4

package/wiki/Provider-Routing.md

@@ -1,17 +1,17 @@
 # Provider Routing
 
-Intelligent tiered provider routing system that automatically selects optimal AI providers based on agent profiles, task complexity, and cost optimization goals.
+**UPDATED 2025-10-05:** Simplified 2-tier routing system for clarity and cost optimization.
 
 ---
 
 ## Overview
 
-Provider routing enables cost-effective LLM usage by automatically routing agent requests to the most appropriate provider:
+Provider routing enables optimal LLM usage by automatically routing requests to the most appropriate provider:
 
-- **Profile-based overrides** - Agent profiles specify preferred providers
-- **Tiered fallback** - Automatic failover from free to paid tiers
-- **Cost optimization** - Up to 64% reduction in API costs
-- **Quality preservation** - Maintains output quality while reducing costs
+- **Main chat quality** - Claude Max subscription for user-facing interactions
+- **Agent cost optimization** - Z.ai for all Task tool agents
+- **Simple configuration** - Only 2 tiers, easy to understand and maintain
+- **Predictable routing** - Clear separation between main chat and agent operations
 
 ---
 
@@ -19,68 +19,57 @@ Provider routing enables cost-effective LLM usage by automatically routing agent
 
 ### Routing Priority
 
-Provider selection follows this priority hierarchy:
+Provider selection follows this simplified hierarchy:
 
 ```
 1. Agent Profile Override (highest priority)
    └─> Profile.provider field (zai, anthropic, custom)
 
 2. Tiered Provider Router
-   ├─> Tier 1: zai (free, rate limited)
-   ├─> Tier 2: deepseek (budget-friendly)
-   └─> Tier 3: anthropic (premium, fallback)
+   ├─> Tier 0: main-chat → Anthropic Claude Max
+   └─> Tier 1: ALL Task tool agents → Z.ai
 
 3. Default Provider
    └─> anthropic (if no routing configured)
 ```
 
-### Tier Characteristics
+### Current Tier Configuration
 
-| Tier | Provider | Cost | Rate Limit | Use Cases |
-|------|----------|------|------------|-----------|
-| **Tier 1** | zai | Free | 60 req/min | Non-critical tasks, research, drafting |
-| **Tier 2** | deepseek | Budget | 100 req/min | Standard development, testing |
-| **Tier 3** | anthropic | Premium | 1000 req/min | Critical tasks, production code |
+| Tier | Provider | Agent Types | Use Case |
+|------|----------|-------------|----------|
+| **Tier 0** | Anthropic Claude Max | `main-chat` (default) | Main conversational interface |
+| **Tier 1** | Z.ai | ALL other agents | Task tool agent swarms |
 
 ---
 
 ## Configuration
 
-### Global Routing Setup
-
-Enable tiered routing in `.claude-flow/settings.json`:
-
-```json
-{
-  "providers": {
-    "routing": {
-      "enabled": true,
-      "strategy": "tiered",
-      "tiers": [
-        {
-          "name": "zai",
-          "priority": 1,
-          "rateLimit": 60,
-          "fallbackOnError": true
-        },
-        {
-          "name": "deepseek",
-          "priority": 2,
-          "rateLimit": 100,
-          "fallbackOnError": true
-        },
-        {
-          "name": "anthropic",
-          "priority": 3,
-          "rateLimit": 1000,
-          "fallbackOnError": false
-        }
-      ]
-    }
-  }
-}
+### Current Configuration (Simplified 2-Tier System)
+
+Tiered routing is configured in `src/providers/tiered-router.ts`:
+
+```typescript
+const TIER_CONFIGS: TierConfig[] = [
+  {
+    name: "Tier 0: Main Chat (Claude Max)",
+    provider: "anthropic",
+    agentTypes: ["main-chat"],
+    priority: 0,
+  },
+  {
+    name: "Tier 1: Z.ai Agent Orchestration (ALL Task Tool Agents)",
+    provider: "zai",
+    agentTypes: [],  // All agents EXCEPT "main-chat"
+    priority: 1,
+  },
+];
 ```
 
+**Key Points:**
+- **No configuration file needed** - routing is built into the code
+- **Tier 0**: Only `main-chat` (default when no agentType)
+- **Tier 1**: Everything else (fallback for all Task tool agents)
+
 ### Agent Profile Overrides
 
 Override routing for specific agents in `.claude/agents/[agent-name].md`:
@@ -108,22 +97,21 @@ Critical security auditing agent that requires premium provider.
 
 ## Usage Examples
 
-### Example 1: Enable Tiered Routing
+### Example 1: Test Current Routing
 
 ```bash
-# Activate custom routing system
-/custom-routing-activate
+# Test routing configuration
+node scripts/test-provider-routing.cjs
 
 # Expected output:
-# ✅ Custom routing activated
-# Priority: Profile → Tier 1 (zai) → Tier 2 (deepseek) → Tier 3 (anthropic)
-# Cost savings: ~64% (free tier + budget fallback)
+# ✅ Agents will route through tiered system:
+#    Tier 0: Main chat → Anthropic Claude Max
+#    Tier 1: ALL Task tool agents → Z.ai
 ```
 
 **What happens:**
-1. All agents without profile overrides use zai (free) first
-2. If zai fails/rate-limited, fallback to deepseek (budget)
-3. If deepseek fails, fallback to anthropic (premium)
+1. Main chat (no agentType) defaults to "main-chat" → Anthropic Claude Max
+2. ALL Task tool agents route to Z.ai (coder, tester, reviewer, etc.)
 
 ### Example 2: Profile-Based Override
 
@@ -137,8 +125,8 @@ reasoning: Architecture decisions require highest quality reasoning
 ```
 
 **Routing behavior:**
-- `system-architect` ALWAYS uses `anthropic` (ignores tiered routing)
-- Other agents use tiered routing (zai → deepseek → anthropic)
+- `system-architect` ALWAYS uses `anthropic` (profile override)
+- Other agents use tiered routing (main-chat → anthropic, all others → zai)
 
 ### Example 3: Mixed Agent Swarm
 
@@ -150,26 +138,26 @@ mcp__claude-flow-novice__swarm_init({
 })
 
 // Agent 1: researcher (no profile override)
-// → Uses zai (free tier, Tier 1)
+// → Uses Z.ai (Tier 1, default for all agents)
 Task("Researcher", "Research JWT libraries", "researcher")
 
 // Agent 2: system-architect (profile: anthropic)
-// → Uses anthropic (premium, profile override)
+// → Uses Anthropic (profile override)
 Task("Architect", "Design auth system", "system-architect")
 
 // Agent 3: coder (no profile override)
-// → Uses zai (free tier, Tier 1)
+// → Uses Z.ai (Tier 1, default for all agents)
 Task("Coder", "Implement endpoints", "coder")
 
-// Agent 4: security-specialist (profile: anthropic)
-// → Uses anthropic (premium, profile override)
-Task("Security Auditor", "Audit auth", "security-specialist")
+// Agent 4: tester (no profile override)
+// → Uses Z.ai (Tier 1, default for all agents)
+Task("Tester", "Test endpoints", "tester")
 ```
 
 **Cost breakdown:**
-- 2 agents on zai (free) = $0
-- 2 agents on anthropic (premium) = standard cost
-- **Total savings: ~50%** vs all-anthropic approach
+- 3 agents on Z.ai (coder, researcher, tester) = lowest cost
+- 1 agent on Anthropic (system-architect) = standard cost
+- **Total savings: ~75%** vs all-anthropic approach
 
 ### Example 4: Disable Custom Routing
 

package/MEMORY_LEAK_ROOT_CAUSE.md

@@ -1,149 +0,0 @@
-# Memory Leak Root Cause - CONFIRMED
-
-## 🔴 Critical Finding
-
-**Memory leak caused by `find /mnt/c` commands on WSL Windows paths**
-
-## Monitoring Results (10-minute observation)
-
-```
-Timeline:
-[1/20]  [19:06:56] MEM: 15.6GB | Find: 0        ← Baseline
-[3/20]  [19:07:56] MEM: 15.8GB | Find: 2        ← Find commands start 🔴
-[8/20]  [19:10:26] MEM: 26.1GB | Find: 0        ← +10.5GB spike!
-[9/20]  [19:10:56] MEM: 28.5GB | Find: 3        ← Peak find activity
-[10/20] [19:11:26] MEM: 32.0GB | Find: 3        ← Critical heap pressure
-[11-19]           MEM: 36.5GB | Find: 0        ← Stabilized (heap fragmentation)
-[20/20] [19:16:27] MEM: 14.1GB | Find: 0        ← Swarm complete, dropped 22GB
-```
-
-## The Smoking Gun
-
-**4-minute period (19:07 → 19:11):**
-- 2-3 `find /mnt/c` commands running concurrently
-- Memory jumped from 15.6GB → 32.0GB (+16.4GB)
-- **Memory growth rate: 4GB/minute while finds active**
-
-## Why `find /mnt/c` is a Memory Bomb
-
-1. **WSL filesystem translation**: Linux syscalls → Windows API = extremely slow
-2. **Output buffering**: Each find buffers 50-200MB of file paths in memory
-3. **Concurrent execution**: 3 agents × 200MB buffered output = 600MB+
-4. **Heap fragmentation**: Node.js heap can't release memory fast enough
-5. **Result**: 20GB+ memory spike in 4 minutes → crash
-
-## Performance Comparison
-
-| Tool | Time | Memory | Command |
-|------|------|--------|---------|
-| `find /mnt/c/...` | 2-10s | 50-200MB per command | ❌ FORBIDDEN |
-| `Glob("**/*")` | <100ms | <1MB | ✅ USE THIS |
-| `git ls-files` | <50ms | <1MB | ✅ Alternative |
-
-## Fix Applied
-
-### 1. Pre-Command Hook (BLOCKS find commands)
-
-**claude-flow-novice/.claude/settings.json:**
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Bash",
-      "hooks": [{
-        "type": "command",
-        "command": "bash -c 'CMD=$(cat | jq -r \".tool_input.command // empty\"); if echo \"$CMD\" | grep -q \"find /mnt/c\"; then echo \"🔴 BLOCKED: find on /mnt/c paths forbidden (causes memory leak - use Glob tool instead)\" >&2; exit 1; fi; ...'"
-      }]
-    }]
-  }
-}
-```
-
-**ourstories-v2/.claude/settings.json:**
-```json
-{
-  "hooks": {
-    "PreToolUse": [{
-      "matcher": "Bash",
-      "hooks": [{
-        "type": "command",
-        "command": "bash -c 'CMD=$(cat | jq -r \".tool_input.command // empty\"); if echo \"$CMD\" | grep -q \"find /mnt/c\"; then echo \"🔴 BLOCKED: find on /mnt/c paths forbidden (causes memory leak - use Glob tool instead)\" >&2; exit 1; fi'"
-      }]
-    }]
-  }
-}
-```
-
-### 2. CLAUDE.md Updated
-
-Added section: **🚨 CRITICAL: Memory Leak Prevention (WSL/Windows)**
-
-- Prohibits `find /mnt/c` commands
-- Mandates Glob tool instead
-- Documents performance comparison
-
-### 3. Agent Performance Guidelines
-
-Created: `AGENT_PERFORMANCE_GUIDELINES.md`
-
-- Best practices for WSL environments
-- Tool alternatives (Glob, fd, git ls-files)
-- Memory optimization patterns
-
-## Secondary Issue: Orphaned Processes
-
-**Also discovered:**
-- 39 orphaned node processes from previous swarms
-- 5-6 zombie processes stuck in <defunct> state
-- Total: ~3GB additional memory overhead
-
-**Cleanup needed:**
-```bash
-# Kill zombies
-kill -9 <zombie_pids>
-
-# Kill old processes (>1 hour)
-ps -eo pid,etime,cmd | grep node | awk '$2 ~ /-/ {print $1}' | xargs kill -9
-```
-
-## Testing Hook Protection
-
-**After restart, if agent tries:**
-```bash
-find /mnt/c/Users/masha/Documents/claude-flow-novice -name "*.test.*"
-```
-
-**Hook will block with:**
-```
-🔴 BLOCKED: find on /mnt/c paths forbidden (causes memory leak - use Glob tool instead)
-```
-
-**Agent must use instead:**
-```javascript
-Glob("**/*.test.*")  // Fast, <100ms, minimal memory
-```
-
-## Summary
-
-✅ **Root cause identified**: `find /mnt/c` commands on WSL
-✅ **Fix applied**: PreToolUse hook blocks dangerous commands
-✅ **Documentation updated**: CLAUDE.md + guidelines
-✅ **Prevention active**: Both repos protected
-
-**Expected result:** No more 20GB+ memory spikes from find commands.
-
-## Monitoring Script
-
-Created: `scripts/monitor.py`
-
-Run anytime to check for memory leaks:
-```bash
-python3 scripts/monitor.py
-```
-
-Monitors for:
-- Total memory usage
-- Node/Claude process counts
-- Zombie processes
-- Find commands (memory bombs)
-- Hook recursion