claude.md
1 # delegator/ 2 3 **Context:** Intelligent Agent Coordinator for ECHO 4 5 The Delegator is an MCP server that solves ECHO's resource utilization problem by spawning only the agents needed for a specific session, rather than running all 9 agents simultaneously. 6 7 ## Purpose 8 9 The Delegator provides: 10 - **Intelligent Agent Selection** - Analyze tasks and spawn only required agents 11 - **Session Management** - Track agent lifecycles within user sessions 12 - **Resource Optimization** - Reduce CPU/memory usage by 50-80% 13 - **Dynamic Scaling** - Add/remove agents mid-session as needed 14 - **Task Routing** - Route messages to appropriate active agents 15 16 ## Key Benefits 17 18 - ⚡ **Reduced CPU Usage** - Run 2-4 agents instead of 9 19 - 🚀 **Faster Startup** - Load only necessary LLMs (~7-14GB vs ~48GB) 20 - 🎯 **Better UX** - Relevant agents for the task at hand 21 - 💰 **Resource Efficiency** - Scale based on actual needs 22 - 🧩 **Extensible** - Support for dynamic mid-session spawning 23 24 ## Architecture 25 26 ### Before Delegator 27 ``` 28 Claude Desktop / MCP Client 29 ├──> 9 Independent Agent MCP Servers (ALL running) 30 │ └──> Each has specialized LLM via Ollama (~48GB total) 31 │ 32 └──> Shared Infrastructure 33 ├── PostgreSQL 34 └── Redis 35 ``` 36 37 **Problem:** All 9 agents always running, even for simple tasks 38 39 ### With Delegator 40 ``` 41 Claude Desktop / MCP Client 42 ├──> Delegator MCP Server (intelligent coordinator) 43 │ └──> Spawns only required agents per session 44 │ ├──> Developer (for code tasks) 45 │ ├──> Test Lead (if testing needed) 46 │ └──> CEO (if strategic decision needed) 47 │ 48 └──> Shared Infrastructure 49 ├── PostgreSQL (+ delegator_sessions table) 50 └── Redis 51 ``` 52 53 **Solution:** Delegate spawns 2-4 relevant agents based on task analysis 54 55 ## Example Usage 56 57 ### Simple Bug Fix 58 ``` 59 User: "Fix typo in README" 60 61 Delegator Analysis: 62 - Task type: Code change (documentation) 63 - Complexity: Low 64 - Required agents: Developer (1 agent) 65 66 Spawns: Developer (deepseek-coder:6.7b) 67 Resource usage: ~7GB memory, low CPU 68 Time saved: 80% faster startup 69 ``` 70 71 ### Feature Implementation 72 ``` 73 User: "Add user authentication feature" 74 75 Delegator Analysis: 76 - Task type: Feature development 77 - Complexity: Medium 78 - Required agents: Product Manager, Architect, Developer, Test Lead (4 agents) 79 80 Spawns: PM, Architect, Dev, Test (4 agents) 81 Resource usage: ~20GB memory, medium CPU 82 Time saved: 55% faster startup 83 ``` 84 85 ### Strategic Planning 86 ``` 87 User: "Plan Q2 roadmap and budget allocation" 88 89 Delegator Analysis: 90 - Task type: Strategic planning 91 - Complexity: High 92 - Required agents: CEO, Product Manager, Operations (3 agents) 93 94 Spawns: CEO, PM, Ops (3 agents) 95 Resource usage: ~16GB memory, medium CPU 96 Time saved: 66% faster startup 97 ``` 98 99 ## Directory Structure 100 101 ``` 102 apps/delegator/ 103 ├── claude.md # This file 104 ├── README.md # Project documentation 105 ├── mix.exs # Dependencies + configuration 106 ├── lib/ 107 │ ├── delegator.ex # Main MCP server module 108 │ └── delegator/ 109 │ ├── application.ex # OTP application 110 │ ├── cli.ex # Command-line interface 111 │ ├── task_analyzer.ex # Analyze task requirements 112 │ ├── agent_spawner.ex # Spawn/manage agent processes 113 │ ├── session_manager.ex # Track active sessions 114 │ └── message_router.ex # Route messages to agents 115 ├── test/ 116 │ ├── delegator_test.exs 117 │ ├── task_analyzer_test.exs 118 │ └── agent_spawner_test.exs 119 └── config/ 120 └── config.exs 121 ``` 122 123 ## MCP Tools 124 125 The Delegator provides these MCP tools: 126 127 ### 1. `create_session` 128 129 Create a new delegated agent session for a task 130 131 **Input:** 132 ```json 133 { 134 "task_description": "Implement user authentication", 135 "context": { 136 "priority": "high", 137 "deadline": "2025-12-01", 138 "existing_code": "apps/auth/" 139 } 140 } 141 ``` 142 143 **Output:** 144 ```json 145 { 146 "session_id": "session_20251112_143022_84329", 147 "active_agents": ["product_manager", "senior_architect", "senior_developer", "test_lead"], 148 "estimated_resources": { 149 "memory_gb": 20, 150 "cpu_cores": 4 151 }, 152 "status": "ready" 153 } 154 ``` 155 156 ### 2. `analyze_task` 157 158 Analyze a task and recommend required agents (without spawning) 159 160 **Input:** 161 ```json 162 { 163 "task_description": "Fix typo in README", 164 "analyze_only": true 165 } 166 ``` 167 168 **Output:** 169 ```json 170 { 171 "task_type": "code_change", 172 "complexity": "low", 173 "recommended_agents": ["senior_developer"], 174 "reasoning": "Simple documentation fix requires only developer", 175 "estimated_time": "5 minutes" 176 } 177 ``` 178 179 ### 3. `add_agent_to_session` 180 181 Dynamically add an agent to running session 182 183 **Input:** 184 ```json 185 { 186 "session_id": "session_20251112_143022_84329", 187 "agent_role": "ceo", 188 "reason": "Need strategic approval for approach" 189 } 190 ``` 191 192 **Output:** 193 ```json 194 { 195 "agent_role": "ceo", 196 "status": "spawned", 197 "model": "qwen2.5:14b", 198 "ready_in_seconds": 15 199 } 200 ``` 201 202 ### 4. `remove_agent_from_session` 203 204 Remove an agent from session when no longer needed 205 206 **Input:** 207 ```json 208 { 209 "session_id": "session_20251112_143022_84329", 210 "agent_role": "test_lead", 211 "reason": "Testing completed" 212 } 213 ``` 214 215 **Output:** 216 ```json 217 { 218 "agent_role": "test_lead", 219 "status": "terminated", 220 "resources_freed_gb": 8 221 } 222 ``` 223 224 ### 5. `list_active_sessions` 225 226 List all active delegator sessions 227 228 **Output:** 229 ```json 230 { 231 "sessions": [ 232 { 233 "session_id": "session_20251112_143022_84329", 234 "task_description": "Implement user authentication", 235 "active_agents": ["product_manager", "senior_developer"], 236 "created_at": "2025-11-12T14:30:22Z", 237 "uptime_minutes": 45 238 } 239 ], 240 "total_sessions": 1 241 } 242 ``` 243 244 ### 6. `end_session` 245 246 End a delegated session and clean up agents 247 248 **Input:** 249 ```json 250 { 251 "session_id": "session_20251112_143022_84329" 252 } 253 ``` 254 255 **Output:** 256 ```json 257 { 258 "session_id": "session_20251112_143022_84329", 259 "agents_terminated": ["product_manager", "senior_developer", "test_lead"], 260 "resources_freed_gb": 18, 261 "session_duration_minutes": 47 262 } 263 ``` 264 265 ## Task Analysis Logic 266 267 ### TaskAnalyzer Module 268 269 ```elixir 270 defmodule Delegator.TaskAnalyzer do 271 @doc """ 272 Analyze task description and recommend required agents 273 """ 274 def analyze(task_description, context \\ %{}) do 275 task_type = classify_task(task_description) 276 complexity = determine_complexity(task_description, context) 277 agents = recommend_agents(task_type, complexity) 278 279 %{ 280 task_type: task_type, 281 complexity: complexity, 282 recommended_agents: agents, 283 reasoning: explain_recommendation(task_type, complexity, agents) 284 } 285 end 286 287 defp classify_task(description) do 288 cond do 289 matches?(description, ~r/bug|fix|error|issue/i) -> :bug_fix 290 matches?(description, ~r/feature|add|implement|create/i) -> :feature_development 291 matches?(description, ~r/refactor|cleanup|optimize/i) -> :refactoring 292 matches?(description, ~r/test|qa|quality/i) -> :testing 293 matches?(description, ~r/design|architecture|system/i) -> :architecture 294 matches?(description, ~r/plan|strategy|roadmap|budget/i) -> :strategic_planning 295 matches?(description, ~r/ui|ux|interface|design/i) -> :ui_design 296 matches?(description, ~r/deploy|release|production/i) -> :deployment 297 true -> :general 298 end 299 end 300 301 defp determine_complexity(description, context) do 302 indicators = [ 303 has_deadline?(context), 304 is_critical?(context), 305 is_large_scope?(description), 306 requires_coordination?(description) 307 ] 308 309 case Enum.count(indicators, & &1) do 310 0 -> :low 311 1 -> :low 312 2 -> :medium 313 3 -> :high 314 4 -> :very_high 315 end 316 end 317 318 defp recommend_agents(:bug_fix, :low), do: [:senior_developer] 319 defp recommend_agents(:bug_fix, :medium), do: [:senior_developer, :test_lead] 320 defp recommend_agents(:bug_fix, :high), do: [:senior_developer, :test_lead, :senior_architect] 321 322 defp recommend_agents(:feature_development, :low), do: [:senior_developer, :test_lead] 323 defp recommend_agents(:feature_development, :medium), do: [:product_manager, :senior_developer, :test_lead] 324 defp recommend_agents(:feature_development, :high), do: [:product_manager, :senior_architect, :senior_developer, :test_lead] 325 326 defp recommend_agents(:strategic_planning, _), do: [:ceo, :product_manager, :operations_head] 327 328 defp recommend_agents(:architecture, _), do: [:cto, :senior_architect, :senior_developer] 329 330 defp recommend_agents(:ui_design, _), do: [:uiux_engineer, :senior_developer] 331 332 # ... more mappings 333 end 334 ``` 335 336 ## Session Management 337 338 ### Database Schema 339 340 The delegator uses a `delegator_sessions` table: 341 342 ```sql 343 CREATE TABLE delegator_sessions ( 344 id UUID PRIMARY KEY, 345 task_description TEXT NOT NULL, 346 task_type VARCHAR(50), 347 complexity VARCHAR(20), 348 active_agents JSONB, -- ["ceo", "cto"] 349 context JSONB, 350 status VARCHAR(20), -- "active", "completed", "failed" 351 created_at TIMESTAMP DEFAULT NOW(), 352 ended_at TIMESTAMP, 353 resources_used JSONB -- {"memory_gb": 20, "cpu_cores": 4} 354 ); 355 ``` 356 357 ### SessionManager Module 358 359 ```elixir 360 defmodule Delegator.SessionManager do 361 alias EchoShared.Repo 362 alias Delegator.Schemas.Session 363 364 def create_session(task_description, context, agents) do 365 %Session{} 366 |> Session.changeset(%{ 367 task_description: task_description, 368 task_type: context[:task_type], 369 complexity: context[:complexity], 370 active_agents: agents, 371 context: context, 372 status: "active" 373 }) 374 |> Repo.insert() 375 end 376 377 def add_agent(session_id, agent_role) do 378 session = Repo.get!(Session, session_id) 379 updated_agents = [agent_role | session.active_agents] |> Enum.uniq() 380 381 session 382 |> Session.changeset(%{active_agents: updated_agents}) 383 |> Repo.update() 384 end 385 386 def end_session(session_id) do 387 session = Repo.get!(Session, session_id) 388 389 session 390 |> Session.changeset(%{status: "completed", ended_at: DateTime.utc_now()}) 391 |> Repo.update() 392 end 393 end 394 ``` 395 396 ## Agent Spawning 397 398 ### AgentSpawner Module 399 400 ```elixir 401 defmodule Delegator.AgentSpawner do 402 @agent_paths %{ 403 ceo: "apps/ceo/ceo", 404 cto: "apps/cto/cto", 405 senior_developer: "apps/senior_developer/senior_developer" 406 # ... other agents 407 } 408 409 def spawn_agent(agent_role, session_id) do 410 executable = @agent_paths[agent_role] 411 412 port = Port.open({:spawn_executable, executable}, [ 413 :binary, 414 :exit_status, 415 {:env, [{'SESSION_ID', to_charlist(session_id)}]}, 416 {:args, ['--autonomous']} 417 ]) 418 419 track_agent(session_id, agent_role, port) 420 {:ok, port} 421 end 422 423 def terminate_agent(session_id, agent_role) do 424 case get_agent_port(session_id, agent_role) do 425 nil -> {:error, :not_found} 426 port -> 427 Port.close(port) 428 untrack_agent(session_id, agent_role) 429 {:ok, :terminated} 430 end 431 end 432 433 defp track_agent(session_id, agent_role, port) do 434 # Store in ETS or Agent state 435 :ets.insert(:delegator_agents, {{session_id, agent_role}, port}) 436 end 437 438 defp get_agent_port(session_id, agent_role) do 439 case :ets.lookup(:delegator_agents, {session_id, agent_role}) do 440 [{{^session_id, ^agent_role}, port}] -> port 441 [] -> nil 442 end 443 end 444 end 445 ``` 446 447 ## Message Routing 448 449 When an agent needs to communicate with another agent in the session: 450 451 ```elixir 452 defmodule Delegator.MessageRouter do 453 def route_message(session_id, from_role, to_role, message) do 454 # 1. Check if target agent is active in session 455 case get_active_agents(session_id) do 456 agents when to_role in agents -> 457 # Agent is active, route message 458 EchoShared.MessageBus.send_message(from_role, to_role, message) 459 460 _ -> 461 # Agent not active, suggest spawning 462 {:error, :agent_not_active, suggest_spawn: to_role} 463 end 464 end 465 end 466 ``` 467 468 ## Development & Testing 469 470 ### Running Delegator 471 472 ```bash 473 cd apps/delegator 474 475 # Compile 476 mix deps.get 477 mix compile 478 479 # Run tests 480 mix test 481 482 # Build executable 483 mix escript.build 484 485 # Run as MCP server 486 ./delegator 487 488 # Run in autonomous mode (testing) 489 ./delegator --autonomous 490 ``` 491 492 ### Testing Scenarios 493 494 ```bash 495 # Test task analysis 496 iex> Delegator.TaskAnalyzer.analyze("Fix typo in README") 497 %{ 498 task_type: :bug_fix, 499 complexity: :low, 500 recommended_agents: [:senior_developer], 501 reasoning: "Simple documentation fix" 502 } 503 504 # Test session creation 505 iex> Delegator.create_session("Implement auth", %{priority: "high"}) 506 {:ok, %{session_id: "session_...", active_agents: [...]}} 507 508 # Test agent spawning 509 iex> Delegator.AgentSpawner.spawn_agent(:senior_developer, session_id) 510 {:ok, #Port<0.123>} 511 ``` 512 513 ## Configuration 514 515 ```elixir 516 # config/config.exs 517 config :delegator, 518 agent_paths: %{ 519 ceo: "/path/to/echo/apps/ceo/ceo", 520 cto: "/path/to/echo/apps/cto/cto" 521 # ... other agents 522 }, 523 max_concurrent_sessions: 10, 524 session_timeout_minutes: 60, 525 auto_cleanup_agents: true 526 527 # Complexity thresholds 528 config :delegator, :complexity_rules, 529 low: %{max_agents: 2, max_memory_gb: 10}, 530 medium: %{max_agents: 4, max_memory_gb: 25}, 531 high: %{max_agents: 6, max_memory_gb: 40}, 532 very_high: %{max_agents: 9, max_memory_gb: 50} 533 ``` 534 535 ## Performance Metrics 536 537 ### Resource Savings 538 539 | Task Type | Before (9 agents) | After (delegator) | Savings | 540 |-----------|-------------------|-------------------|---------| 541 | Simple bug fix | 48GB, 9 agents | 7GB, 1 agent | 85% memory, 89% agents | 542 | Feature dev | 48GB, 9 agents | 20GB, 4 agents | 58% memory, 56% agents | 543 | Strategic plan | 48GB, 9 agents | 16GB, 3 agents | 67% memory, 67% agents | 544 | Architecture | 48GB, 9 agents | 25GB, 3 agents | 48% memory, 67% agents | 545 546 **Average savings: 65% memory, 70% agents** 547 548 ### Startup Time 549 550 | Scenario | Before | After | Improvement | 551 |----------|--------|-------|-------------| 552 | Simple task | 45s (load all 9) | 8s (load 1) | 82% faster | 553 | Medium task | 45s (load all 9) | 20s (load 4) | 56% faster | 554 | Complex task | 45s (load all 9) | 35s (load 6) | 22% faster | 555 556 ## Troubleshooting 557 558 ### Session not created 559 **Symptom:** `create_session` returns error 560 561 **Debug:** 562 ```elixir 563 iex> Delegator.TaskAnalyzer.analyze("your task") 564 # Check if task analysis works 565 566 iex> EchoShared.Repo.all(Delegator.Schemas.Session) 567 # Check database connection 568 ``` 569 570 ### Agent not spawning 571 **Symptom:** Agent doesn't start 572 573 **Debug:** 574 ```bash 575 # Test agent executable directly 576 cd apps/senior_developer 577 ./senior_developer --autonomous 578 579 # Check executable exists 580 ls -la apps/*/senior_developer 581 ``` 582 583 ### High memory usage despite delegator 584 **Symptom:** Memory usage still high 585 586 **Debug:** 587 ```bash 588 # Check active sessions 589 iex> Delegator.list_active_sessions() 590 591 # Check agent processes 592 ps aux | grep -E "ceo|cto|developer" 593 594 # Clean up orphaned agents 595 iex> Delegator.cleanup_orphaned_agents() 596 ``` 597 598 ## Future Enhancements 599 600 **Phase 2: Intelligent Mid-Session Adaptation** 601 - Auto-spawn agents when task complexity increases 602 - Auto-terminate agents when no longer needed 603 - Predictive spawning based on task patterns 604 605 **Phase 3: Cost Optimization** 606 - Track $ cost per session (LLM inference) 607 - Recommend cheaper model alternatives 608 - Budget-aware agent selection 609 610 **Phase 4: Multi-Session Orchestration** 611 - Share agents across multiple sessions 612 - Agent pooling for frequently used roles 613 - Load balancing across sessions 614 615 ## Related Documentation 616 617 - **Architecture:** [../../docs/architecture/DELEGATOR_ARCHITECTURE.md](../../docs/architecture/DELEGATOR_ARCHITECTURE.md) 618 - **Quick Start:** [../../docs/guides/DELEGATOR_QUICK_START.md](../../docs/guides/DELEGATOR_QUICK_START.md) 619 - **Parent:** [../../CLAUDE.md](../../CLAUDE.md) - Project overview 620 - **Agents:** [../claude.md](../claude.md) - Agent development patterns 621 622 --- 623 624 **Remember:** The Delegator is about efficiency. Spawn only what's needed, cleanup when done.