Add comprehensive agent activity tracking

- Enhanced Agent struct with current_activity, current_files, and activity_history fields - Created ActivityTracker module to infer activities from tool calls - Integrated activity tracking into MCP server tool routing - Updated task board APIs to include activity information - Agents now show real-time status like 'Reading file.ex', 'Editing main.py', 'Sequential thinking', etc. - Added activity history to track recent agent actions - All file operations and tool calls are now tracked and displayed
2025-09-06 09:58:59 -07:00
parent 1056672e7c
commit 8df694b71c
28 changed files with 4770 additions and 321 deletions
--- a/docs/MCP_COMPLIANCE_ENHANCEMENTS.md
+++ b/docs/MCP_COMPLIANCE_ENHANCEMENTS.md
@@ -0,0 +1,253 @@
+# MCP Compliance Enhancement Summary
+
+## Overview
+This document summarizes the enhanced Model Context Protocol (MCP) compliance features implemented in the Agent Coordinator system, focusing on session management, security, and real-time streaming capabilities.
+
+## Implemented Features
+
+### 1. 🔐 Enhanced Session Management
+
+#### Session Token Authentication
+- **Implementation**: Modified `register_agent` to return cryptographically secure session tokens
+- **Token Format**: 32-byte secure random tokens, Base64 encoded
+- **Expiry**: 60-minute session timeout with automatic cleanup
+- **Headers**: Support for `Mcp-Session-Id` header (MCP compliant) and `X-Session-Id` (legacy)
+
+#### Session Validation Flow
+```
+Client                    Server
+  |                         |
+  |-- POST /mcp/request ---->|
+  |    register_agent        |
+  |                         |
+  |<-- session_token --------|
+  |    expires_at            |
+  |                         |
+  |-- Subsequent requests -->|
+  |    Mcp-Session-Id: token |
+  |                         |
+  |<-- Authenticated resp ---|
+```
+
+#### Key Components
+- **SessionManager GenServer**: Manages token lifecycle and validation
+- **Secure token generation**: Uses `:crypto.strong_rand_bytes/1`
+- **Automatic cleanup**: Periodic removal of expired sessions
+- **Backward compatibility**: Supports legacy X-Session-Id headers
+
+### 2. 📋 MCP Protocol Version Compliance
+
+#### Protocol Headers
+- **MCP-Protocol-Version**: `2025-06-18` (current specification)
+- **Server**: `AgentCoordinator/1.0` identification
+- **Applied to**: All JSON responses via enhanced `send_json_response/3`
+
+#### CORS Enhancement
+- **Session Headers**: Added `mcp-session-id`, `mcp-protocol-version` to allowed headers
+- **Exposed Headers**: Protocol version and server headers exposed to clients
+- **Security**: Enhanced origin validation with localhost and HTTPS preference
+
+### 3. 🔒 Security Enhancements
+
+#### Origin Validation
+```elixir
+defp validate_origin(origin) do
+  case URI.parse(origin) do
+    %URI{host: host} when host in ["localhost", "127.0.0.1", "::1"] -> origin
+    %URI{host: host} when is_binary(host) ->
+      if String.starts_with?(origin, "https://") or
+         String.contains?(host, ["localhost", "127.0.0.1", "dev", "local"]) do
+        origin
+      else
+        Logger.warning("Potentially unsafe origin: #{origin}")
+        "*"
+      end
+    _ -> "*"
+  end
+end
+```
+
+#### Authenticated Method Protection
+Protected methods requiring valid session tokens:
+- `agents/register` ✓
+- `agents/unregister` ✓
+- `agents/heartbeat` ✓
+- `tasks/create` ✓
+- `tasks/complete` ✓
+- `codebase/register` ✓
+- `stream/subscribe` ✓
+
+### 4. 📡 Server-Sent Events (SSE) Support
+
+#### Real-time Streaming Endpoint
+- **Endpoint**: `GET /mcp/stream`
+- **Transport**: Streamable HTTP (MCP specification)
+- **Authentication**: Requires valid session token
+- **Content-Type**: `text/event-stream`
+
+#### SSE Event Format
+```
+event: connected
+data: {"session_id":"agent_123","protocol_version":"2025-06-18","timestamp":"2025-01-11T..."}
+
+event: heartbeat
+data: {"timestamp":"2025-01-11T...","session_id":"agent_123"}
+```
+
+#### Features
+- **Connection establishment**: Sends initial `connected` event
+- **Heartbeat**: Periodic keepalive events
+- **Session tracking**: Events include session context
+- **Graceful disconnection**: Handles client disconnects
+
+## Technical Implementation Details
+
+### File Structure
+```
+lib/agent_coordinator/
+├── session_manager.ex          # Session token management
+├── mcp_server.ex              # Enhanced register_agent
+├── http_interface.ex          # HTTP/SSE endpoints + security
+└── application.ex             # Supervision tree
+```
+
+### Session Manager API
+```elixir
+# Create new session
+{:ok, session_info} = SessionManager.create_session(agent_id, capabilities)
+
+# Validate existing session
+{:ok, session_info} = SessionManager.validate_session(token)
+{:error, :expired} = SessionManager.validate_session(old_token)
+
+# Manual cleanup (automatic via timer)
+SessionManager.cleanup_expired_sessions()
+```
+
+### HTTP Interface Enhancements
+```elixir
+# Session validation middleware
+case validate_session_for_method(method, conn, context) do
+  {:ok, session_info} -> # Process request
+  {:error, auth_error} -> # Return 401 Unauthorized
+end
+
+# MCP headers on all responses
+defp put_mcp_headers(conn) do
+  conn
+  |> put_resp_header("mcp-protocol-version", "2025-06-18")
+  |> put_resp_header("server", "AgentCoordinator/1.0")
+end
+```
+
+## Usage Examples
+
+### 1. Agent Registration with Session Token
+```bash
+curl -X POST http://localhost:4000/mcp/request \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "agents/register",
+    "params": {
+      "name": "My Agent Blue Koala",
+      "capabilities": ["coding", "testing"],
+      "codebase_id": "my_project"
+    }
+  }'
+
+# Response:
+{
+  "jsonrpc": "2.0",
+  "id": "1",
+  "result": {
+    "agent_id": "My Agent Blue Koala",
+    "session_token": "abc123...",
+    "expires_at": "2025-01-11T15:30:00Z"
+  }
+}
+```
+
+### 2. Authenticated Tool Call
+```bash
+curl -X POST http://localhost:4000/mcp/request \
+  -H "Content-Type: application/json" \
+  -H "Mcp-Session-Id: abc123..." \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "2",
+    "method": "tools/call",
+    "params": {
+      "name": "get_task_board",
+      "arguments": {"agent_id": "My Agent Blue Koala"}
+    }
+  }'
+```
+
+### 3. Server-Sent Events Stream
+```javascript
+const eventSource = new EventSource('/mcp/stream', {
+  headers: {
+    'Mcp-Session-Id': 'abc123...'
+  }
+});
+
+eventSource.onmessage = function(event) {
+  const data = JSON.parse(event.data);
+  console.log('Received:', data);
+};
+```
+
+## Testing and Verification
+
+### Automated Test Script
+- **File**: `test_session_management.exs`
+- **Coverage**: Registration flow, session validation, protocol headers
+- **Usage**: `elixir test_session_management.exs`
+
+### Manual Testing
+1. Start server: `mix phx.server`
+2. Register agent via `/mcp/request`
+3. Use returned session token for authenticated calls
+4. Verify MCP headers in responses
+5. Test SSE stream endpoint
+
+## Benefits
+
+### 🔐 Security
+- **Token-based authentication**: Prevents unauthorized access
+- **Session expiry**: Limits exposure of compromised tokens
+- **Origin validation**: Mitigates CSRF and unauthorized origins
+- **Method-level protection**: Granular access control
+
+### 📋 MCP Compliance
+- **Official protocol version**: Headers indicate MCP 2025-06-18 support
+- **Streamable HTTP**: Real-time capabilities via SSE
+- **Proper error handling**: Standard JSON-RPC error responses
+- **Session context**: Request metadata for debugging
+
+### 🚀 Developer Experience
+- **Backward compatibility**: Legacy headers still supported
+- **Clear error messages**: Detailed authentication failure reasons
+- **Real-time updates**: Live agent status via SSE
+- **Easy testing**: Comprehensive test utilities
+
+## Future Enhancements
+
+### Planned Features
+- **PubSub integration**: Event-driven SSE updates
+- **Session persistence**: Redis/database backing
+- **Rate limiting**: Per-session request throttling
+- **Audit logging**: Session activity tracking
+- **WebSocket upgrade**: Bidirectional real-time communication
+
+### Configuration Options
+- **Session timeout**: Configurable expiry duration
+- **Security levels**: Strict/permissive origin validation
+- **Token rotation**: Automatic refresh mechanisms
+- **Multi-tenancy**: Workspace-scoped sessions
+
+---
+
+*This implementation provides a solid foundation for MCP-compliant session management while maintaining the flexibility to extend with additional features as requirements evolve.*
--- a/docs/MULTI_INTERFACE.md
+++ b/docs/MULTI_INTERFACE.md
@@ -0,0 +1,279 @@
+# Agent Coordinator Multi-Interface MCP Server
+
+The Agent Coordinator now supports multiple interface modes to accommodate different client types and use cases, from local VSCode integration to remote web applications.
+
+## Interface Modes
+
+### 1. STDIO Mode (Default)
+Traditional MCP over stdin/stdout for local clients like VSCode.
+
+**Features:**
+- Full tool access (filesystem, VSCode, terminal tools)
+- Local security context (trusted)
+- Backward compatible with existing MCP clients
+
+**Usage:**
+```bash
+./scripts/mcp_launcher_multi.sh stdio
+# or
+./scripts/mcp_launcher.sh  # original launcher
+```
+
+### 2. HTTP Mode
+REST API interface for remote clients and web applications.
+
+**Features:**
+- HTTP endpoints for MCP operations
+- Tool filtering (removes local-only tools)
+- CORS support for web clients
+- Remote security context (sandboxed)
+
+**Usage:**
+```bash
+./scripts/mcp_launcher_multi.sh http 8080
+```
+
+**Endpoints:**
+- `GET /health` - Health check
+- `GET /mcp/capabilities` - Server capabilities and filtered tools
+- `GET /mcp/tools` - List available tools (filtered by context)
+- `POST /mcp/tools/:tool_name` - Execute specific tool
+- `POST /mcp/request` - Full MCP JSON-RPC request
+- `GET /agents` - Agent status (requires authorization)
+
+### 3. WebSocket Mode
+Real-time interface for web clients requiring live updates.
+
+**Features:**
+- Real-time MCP JSON-RPC over WebSocket
+- Tool filtering for remote clients
+- Session management and heartbeat
+- Automatic cleanup on disconnect
+
+**Usage:**
+```bash
+./scripts/mcp_launcher_multi.sh websocket 8081
+```
+
+**Endpoint:**
+- `ws://localhost:8081/mcp/ws` - WebSocket connection
+
+### 4. Remote Mode
+Both HTTP and WebSocket on the same port for complete remote access.
+
+**Usage:**
+```bash
+./scripts/mcp_launcher_multi.sh remote 8080
+```
+
+### 5. All Mode
+All interface modes simultaneously for maximum compatibility.
+
+**Usage:**
+```bash
+./scripts/mcp_launcher_multi.sh all 8080
+```
+
+## Tool Filtering
+
+The system intelligently filters available tools based on client context:
+
+### Local Clients (STDIO)
+- **Context**: Trusted, local machine
+- **Tools**: All tools available
+- **Use case**: VSCode extension, local development
+
+### Remote Clients (HTTP/WebSocket)
+- **Context**: Sandboxed, remote access
+- **Tools**: Filtered to exclude local-only operations
+- **Use case**: Web applications, CI/CD, remote dashboards
+
+### Tool Categories
+
+**Always Available (All Contexts):**
+- Agent coordination: `register_agent`, `create_task`, `get_task_board`, `heartbeat`
+- Memory/Knowledge: `create_entities`, `read_graph`, `search_nodes`
+- Documentation: `get-library-docs`, `resolve-library-id`
+- Reasoning: `sequentialthinking`
+
+**Local Only (Filtered for Remote):**
+- Filesystem: `read_file`, `write_file`, `create_file`, `delete_file`
+- VSCode: `vscode_*` tools
+- Terminal: `run_in_terminal`, `get_terminal_output`
+- System: Local file operations
+
+## Configuration
+
+Configuration is managed through environment variables and config files:
+
+### Environment Variables
+- `MCP_INTERFACE_MODE`: Interface mode (`stdio`, `http`, `websocket`, `remote`, `all`)
+- `MCP_HTTP_PORT`: HTTP server port (default: 8080)
+- `MCP_WS_PORT`: WebSocket port (default: 8081)
+
+### Configuration File
+See `mcp_interfaces_config.json` for detailed configuration options.
+
+## Security Considerations
+
+### Local Context (STDIO)
+- Full filesystem access
+- Trusted environment
+- No network exposure
+
+### Remote Context (HTTP/WebSocket)
+- Sandboxed environment
+- Tool filtering active
+- CORS protection
+- No local file access
+
+### Tool Filtering Rules
+1. **Allowlist approach**: Safe tools are explicitly allowed for remote clients
+2. **Pattern matching**: Local-only tools identified by name patterns
+3. **Schema analysis**: Tools with local-only parameters are filtered
+4. **Context-aware**: Different tool sets per connection type
+
+## Client Examples
+
+### HTTP Client (Python)
+```python
+import requests
+
+# Get available tools
+response = requests.get("http://localhost:8080/mcp/tools")
+tools = response.json()
+
+# Register an agent
+agent_data = {
+    "arguments": {
+        "name": "Remote Agent",
+        "capabilities": ["analysis", "coordination"]
+    }
+}
+response = requests.post("http://localhost:8080/mcp/tools/register_agent", 
+                        json=agent_data)
+```
+
+### WebSocket Client (JavaScript)
+```javascript
+const ws = new WebSocket('ws://localhost:8080/mcp/ws');
+
+ws.onopen = () => {
+    // Initialize connection
+    ws.send(JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "initialize",
+        params: {
+            protocolVersion: "2024-11-05",
+            clientInfo: { name: "web-client", version: "1.0.0" }
+        }
+    }));
+};
+
+ws.onmessage = (event) => {
+    const response = JSON.parse(event.data);
+    console.log('MCP Response:', response);
+};
+```
+
+### VSCode MCP (Traditional)
+```json
+{
+    "mcpServers": {
+        "agent-coordinator": {
+            "command": "./scripts/mcp_launcher_multi.sh",
+            "args": ["stdio"]
+        }
+    }
+}
+```
+
+## Testing
+
+Run the test suite to verify all interface modes:
+
+```bash
+# Start the server in remote mode
+./scripts/mcp_launcher_multi.sh remote 8080 &
+
+# Run tests
+python3 scripts/test_multi_interface.py
+
+# Stop the server
+kill %1
+```
+
+## Use Cases
+
+### VSCode Extension Development
+```bash
+./scripts/mcp_launcher_multi.sh stdio
+```
+Full local tool access for development workflows.
+
+### Web Dashboard
+```bash
+./scripts/mcp_launcher_multi.sh remote 8080
+```
+Remote access with HTTP API and WebSocket for real-time updates.
+
+### CI/CD Integration
+```bash
+./scripts/mcp_launcher_multi.sh http 8080
+```
+REST API access for automated workflows.
+
+### Development/Testing
+```bash
+./scripts/mcp_launcher_multi.sh all 8080
+```
+All interfaces available for comprehensive testing.
+
+## Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   STDIO Client  │    │   HTTP Client   │    │ WebSocket Client│
+│    (VSCode)     │    │  (Web/API)     │    │   (Web/Real-time)│
+└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
+          │                      │                      │
+          │ Full Tools           │ Filtered Tools       │ Filtered Tools
+          │                      │                      │
+          v                      v                      v
+┌─────────────────────────────────────────────────────────────────────┐
+│                    Interface Manager                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                │
+│  │   STDIO     │  │    HTTP     │  │  WebSocket  │                │
+│  │ Interface   │  │ Interface   │  │ Interface   │                │
+│  └─────────────┘  └─────────────┘  └─────────────┘                │
+└─────────────────────┬───────────────────────────────────────────────┘
+                      │
+                      v
+┌─────────────────────────────────────────────────────────────────────┐
+│                     Tool Filter                                    │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
+│  │ Local Context   │  │ Remote Context  │  │  Web Context    │     │
+│  │ (Full Access)   │  │  (Sandboxed)   │  │  (Restricted)   │     │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
+└─────────────────────┬───────────────────────────────────────────────┘
+                      │
+                      v
+┌─────────────────────────────────────────────────────────────────────┐
+│                     MCP Server                                     │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐     │
+│  │ Agent Registry  │  │ Task Manager    │  │ External MCPs   │     │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Benefits
+
+1. **Flexible Deployment**: Choose the right interface for your use case
+2. **Security**: Automatic tool filtering prevents unauthorized local access
+3. **Scalability**: HTTP/WebSocket interfaces support multiple concurrent clients
+4. **Backward Compatibility**: STDIO mode maintains compatibility with existing tools
+5. **Real-time Capability**: WebSocket enables live updates and notifications
+6. **Developer Experience**: Consistent MCP protocol across all interfaces
+
+The multi-interface system allows the Agent Coordinator to serve both local development workflows and remote/web applications while maintaining security and appropriate tool access levels.
--- a/docs/architecture-diagram.svg
+++ b/docs/architecture-diagram.svg
@@ -0,0 +1,305 @@
+<svg viewBox="0 0 1200 800" xmlns="http://www.w3.org/2000/svg">
+  <defs>
+    <style>
+      .agent-box {
+        fill: #e3f2fd;
+        stroke: #1976d2;
+        stroke-width: 2;
+      }
+      .coordinator-box {
+        fill: #f3e5f5;
+        stroke: #7b1fa2;
+        stroke-width: 3;
+      }
+      .component-box {
+        fill: #fff3e0;
+        stroke: #f57c00;
+        stroke-width: 2;
+      }
+      .mcp-server-box {
+        fill: #e8f5e8;
+        stroke: #388e3c;
+        stroke-width: 2;
+      }
+      .taskboard-box {
+        fill: #fff8e1;
+        stroke: #ffa000;
+        stroke-width: 2;
+      }
+      .text {
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+        font-size: 12px;
+      }
+      .title-text {
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+        font-size: 14px;
+        font-weight: bold;
+      }
+      .small-text {
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+        font-size: 10px;
+      }
+      .connection-line {
+        stroke: #666;
+        stroke-width: 2;
+        fill: none;
+      }
+      .mcp-line {
+        stroke: #1976d2;
+        stroke-width: 3;
+        fill: none;
+      }
+      .data-flow {
+        stroke: #4caf50;
+        stroke-width: 2;
+        fill: none;
+        stroke-dasharray: 5,5;
+      }
+      .text-bg {
+        fill: white;
+        fill-opacity: 0.9;
+        stroke: #333;
+        stroke-width: 1; rx: 4;
+      }
+      .overlay-text {
+        font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+        font-size: 12px;
+        font-weight: bold;
+      }
+    </style>
+
+    <!-- Arrow marker -->
+    <marker id="arrowhead" markerWidth="6" markerHeight="4"
+            refX="5" refY="2" orient="auto">
+      <polygon points="0 0, 6 2, 0 4" fill="none" stroke="#666" stroke-width="0.01" />
+    </marker>
+
+    <!-- MCP Arrow marker -->
+    <marker id="mcpArrow" markerWidth="6" markerHeight="4"
+            refX="5" refY="2" orient="auto">
+      <polygon points="0 0, 6 2, 0 4" fill="#1976d2" stroke="#1976d2" stroke-width="0.01" />
+    </marker>
+
+    <!-- Data flow arrow -->
+    <marker id="dataArrow" markerWidth="6" markerHeight="4"
+            refX="5" refY="2" orient="auto">
+      <polygon points="0 0, 6 2, 0 4" fill="#4caf50" stroke="#4caf50" stroke-width="1" />
+    </marker>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="800" fill="#fafafa03" />
+
+  <!-- Title -->
+  <text x="600" y="30" text-anchor="middle" class="title-text" font-size="18" fill="#333">
+    Agent Coordinator: MCP Proxy Server Architecture
+  </text>
+
+  <!-- AI Agents Section -->
+  <text x="600" y="55" text-anchor="middle" class="text" fill="#666">
+    Single MCP Interface → Multiple AI Agents → Unified Project Awareness
+  </text>
+
+  <!-- Agent 1 -->
+  <rect x="50" y="80" width="150" height="80" rx="8" class="agent-box" />
+  <text x="125" y="105" text-anchor="middle" class="title-text" fill="#1976d2">Agent 1</text>
+  <text x="125" y="120" text-anchor="middle" class="small-text" fill="#666">Purple Zebra</text>
+  <text x="125" y="135" text-anchor="middle" class="small-text" fill="#666">Capabilities:</text>
+  <text x="125" y="148" text-anchor="middle" class="small-text" fill="#666">coding, testing</text>
+
+  <!-- Agent 2 -->
+  <rect x="250" y="80" width="150" height="80" rx="8" class="agent-box" />
+  <text x="325" y="105" text-anchor="middle" class="title-text" fill="#1976d2">Agent 2</text>
+  <text x="325" y="120" text-anchor="middle" class="small-text" fill="#666">Yellow Elephant</text>
+  <text x="325" y="135" text-anchor="middle" class="small-text" fill="#666">Capabilities:</text>
+  <text x="325" y="148" text-anchor="middle" class="small-text" fill="#666">analysis, docs</text>
+
+  <!-- Agent N -->
+  <rect x="450" y="80" width="150" height="80" rx="8" class="agent-box" />
+  <text x="525" y="105" text-anchor="middle" class="title-text" fill="#1976d2">Agent N</text>
+  <text x="525" y="120" text-anchor="middle" class="small-text" fill="#666">More Agents...</text>
+  <text x="525" y="135" text-anchor="middle" class="small-text" fill="#666">Dynamic</text>
+  <text x="525" y="148" text-anchor="middle" class="small-text" fill="#666">Registration</text>
+
+  <!-- Lines from agents to coordinator (drawn first, behind text) -->
+  <line x1="125" y1="160" x2="130" y2="220" class="mcp-line" marker-end="url(#mcpArrow)" />
+  <line x1="325" y1="160" x2="330" y2="220" class="mcp-line" marker-end="url(#mcpArrow)" />
+  <line x1="525" y1="160" x2="525" y2="220" class="mcp-line" marker-end="url(#mcpArrow)" />
+
+  <!-- MCP Protocol text with background (drawn on top of lines) -->
+  <rect x="200" y="167" width="250" height="25" class="text-bg" />
+  <text x="325" y="185" text-anchor="middle" class="overlay-text">
+    MCP Protocol → Single Proxy Interface
+  </text>
+
+  <!-- Main Coordinator Box -->
+  <rect x="50" y="220" width="600" height="280" rx="12" class="coordinator-box" />
+  <text x="350" y="245" text-anchor="middle" class="title-text" font-size="16">
+    AGENT COORDINATOR (MCP Proxy Server)
+  </text>
+  <text x="350" y="255" text-anchor="middle" class="small-text" fill="#9c27b0">
+    ⚡ All tool calls proxy through here → Real-time agent tracking → Full project awareness
+  </text>
+
+  <!-- Core Components Row -->
+  <!-- Task Registry -->
+  <rect x="70" y="260" width="160" height="100" rx="6" class="component-box" />
+  <text x="150" y="280" text-anchor="middle" class="title-text" fill="#f57c00">Task Registry</text>
+  <text x="150" y="298" text-anchor="middle" class="small-text" fill="#666">• Task Queuing</text>
+  <text x="150" y="311" text-anchor="middle" class="small-text" fill="#666">• Agent Matching</text>
+  <text x="150" y="324" text-anchor="middle" class="small-text" fill="#666">• Auto-Tracking</text>
+  <text x="150" y="337" text-anchor="middle" class="small-text" fill="#666">• Progress Monitor</text>
+  <text x="150" y="350" text-anchor="middle" class="small-text" fill="#666">• Conflict Prevention</text>
+
+  <!-- Agent Manager -->
+  <rect x="250" y="260" width="160" height="100" rx="6" class="component-box" />
+  <text x="330" y="280" text-anchor="middle" class="title-text" fill="#f57c00">Agent Manager</text>
+  <text x="330" y="298" text-anchor="middle" class="small-text" fill="#666">• Registration</text>
+  <text x="330" y="311" text-anchor="middle" class="small-text" fill="#666">• Heartbeat Monitor</text>
+  <text x="330" y="324" text-anchor="middle" class="small-text" fill="#666">• Capabilities</text>
+  <text x="330" y="337" text-anchor="middle" class="small-text" fill="#666">• Status Tracking</text>
+  <text x="330" y="350" text-anchor="middle" class="small-text" fill="#666">• Load Balancing</text>
+
+  <!-- Codebase Registry -->
+  <rect x="430" y="260" width="160" height="100" rx="6" class="component-box" />
+  <text x="510" y="280" text-anchor="middle" class="title-text" fill="#f57c00">Codebase Registry</text>
+  <text x="510" y="298" text-anchor="middle" class="small-text" fill="#666">• Cross-Repo</text>
+  <text x="510" y="311" text-anchor="middle" class="small-text" fill="#666">• Dependencies</text>
+  <text x="510" y="324" text-anchor="middle" class="small-text" fill="#666">• Workspace Mgmt</text>
+  <text x="510" y="337" text-anchor="middle" class="small-text" fill="#666">• File Locking</text>
+  <text x="510" y="350" text-anchor="middle" class="small-text" fill="#666">• Version Control</text>
+
+  <!-- Unified Tool Registry -->
+  <rect x="70" y="380" width="520" height="100" rx="6" class="component-box" />
+  <text x="330" y="400" text-anchor="middle" class="title-text" fill="#f57c00">UNIFIED TOOL REGISTRY (Proxy Layer)</text>
+  <text x="330" y="415" text-anchor="middle" class="small-text" fill="#f57c00">Every tool call = Agent presence update + Task tracking + Project awareness</text>
+
+  <!-- Native Tools -->
+  <text x="90" y="435" class="small-text" fill="#666" font-weight="bold">Native Tools:</text>
+  <!-- <text x="90" y="434" class="small-text" fill="#666">register_agent, get_next_task, create_task_set,</text> -->
+  <!-- <text x="90" y="448" class="small-text" fill="#666">complete_task, heartbeat, get_task_board</text> -->
+  <text x="90" y="463" class="small-text" fill="#666" font-weight="bold">Proxied External Tools:</text>
+
+  <!-- External Tools -->
+  <text x="320" y="435" class="small-text" fill="#666">register_agent, get_next_task, create_task_set,</text>
+  <!-- <text x="320" y="420" class="small-text" fill="#666" font-weight="bold">External MCP Tools:</text> -->
+  <text x="320" y="449" class="small-text" fill="#666">complete_task, heartbeat, get_task_board</text>
+  <!-- <text x="320" y="434" class="small-text" fill="#666">read_file, write_file, search_memory,</text> -->
+  <text x="320" y="463" class="small-text" fill="#666">read_file, write_file, search_memory, get_docs</text>
+
+  <!-- VS Code Tools -->
+  <text x="90" y="477" class="small-text" fill="#666" font-weight="bold">VS Code Integration:</text>
+  <text x="320" y="477" class="small-text" fill="#666">get_active_editor, set_selection, install_extension</text>
+
+  <!-- Task Board (Right side) -->
+  <rect x="680" y="220" width="260" height="280" rx="8" class="coordinator-box"/>
+  <text x="810" y="245" text-anchor="middle" class="title-text">Real-Time Task Board</text>
+
+  <!-- Agent Queues -->
+  <rect x="700" y="260" width="100" height="80" rx="4"  class="component-box"/>
+  <text x="750" y="275" text-anchor="middle" class="small-text" fill="#666" font-weight="bold">Agent 1 Queue</text>
+  <text x="750" y="290" text-anchor="middle" class="small-text" fill="#4caf50">✓ Task 1</text>
+  <text x="750" y="303" text-anchor="middle" class="small-text" fill="#4caf50">✓ Task 2</text>
+  <text x="750" y="316" text-anchor="middle" class="small-text" fill="#ff9800">→ Task 3</text>
+  <text x="750" y="329" text-anchor="middle" class="small-text" fill="#666">… Task 4</text>
+
+  <rect x="820" y="260" width="100" height="80" rx="4"  class="component-box" />
+  <text x="870" y="275" text-anchor="middle" class="small-text" fill="#666" font-weight="bold">Agent 2 Queue</text>
+  <text x="870" y="290" text-anchor="middle" class="small-text" fill="#4caf50">✓ Task 1</text>
+  <text x="870" y="303" text-anchor="middle" class="small-text" fill="#ff9800">→ Task 2</text>
+  <text x="870" y="316" text-anchor="middle" class="small-text" fill="#666">… Task 3</text>
+  <text x="870" y="329" text-anchor="middle" class="small-text" fill="#666">… Task 4</text>
+
+
+
+  <!-- Agent Inboxes -->
+  <rect x="700" y="360" width="100" height="60" rx="4" fill="#e3f2fd" stroke="#1976d2" stroke-width="1" />
+  <text x="750" y="375" text-anchor="middle" class="small-text" fill="#1976d2" font-weight="bold">Agent 1 Inbox</text>
+  <text x="750" y="390" text-anchor="middle" class="small-text" fill="#666">current: task 3</text>
+  <text x="750" y="403" text-anchor="middle" class="small-text" fill="#666">[complete task]</text>
+  <!-- <rect x="700" y="360" width="100" height="60" rx="4" fill="#e3f2fd" stroke="#1976d2" stroke-width="1" />
+  <text x="750" y="375" text-anchor="middle" class="small-text" fill="#1976d2" font-weight="bold">Agent 1 Inbox</text>
+  <text x="750" y="390" text-anchor="middle" class="small-text" fill="#666">current: task 3</text>
+  <text x="750" y="403" text-anchor="middle" class="small-text" fill="#666">[complete task]</text> -->
+
+  <rect x="820" y="360" width="100" height="60" rx="4" fill="#e3f2fd" stroke="#1976d2" stroke-width="1" />
+  <text x="870" y="375" text-anchor="middle" class="small-text" fill="#1976d2" font-weight="bold">Agent 2 Inbox</text>
+  <text x="870" y="390" text-anchor="middle" class="small-text" fill="#666">current: task 2</text>
+  <text x="870" y="403" text-anchor="middle" class="small-text" fill="#666">[complete task]</text>
+
+  <!-- Connection lines from coordinator to external servers (drawn first, behind text) -->
+  <line x1="350" y1="500" x2="110" y2="550" class="connection-line" marker-end="url(#arrowhead)" />
+  <line x1="350" y1="500" x2="250" y2="550" class="connection-line" marker-end="url(#arrowhead)" />
+  <line x1="350" y1="500" x2="390" y2="550" class="connection-line" marker-end="url(#arrowhead)" />
+  <line x1="350" y1="500" x2="530" y2="550" class="connection-line" marker-end="url(#arrowhead)" />
+
+  <!-- Data flow line to task board (drawn first, behind text) -->
+  <line x1="650" y1="350" x2="680" y2="350" class="data-flow" marker-end="url(#dataArrow)" />
+
+  <!-- PROXY arrows showing reverse direction - tools flow UP through coordinator -->
+  <line x1="110" y1="550" x2="330" y2="500" class="mcp-line" marker-end="url(#mcpArrow)" stroke-dasharray="3,3" />
+  <line x1="250" y1="550" x2="340" y2="500" class="mcp-line" marker-end="url(#mcpArrow)" stroke-dasharray="3,3" />
+  <line x1="390" y1="550" x2="360" y2="500" class="mcp-line" marker-end="url(#mcpArrow)" stroke-dasharray="3,3" />
+  <line x1="530" y1="550" x2="370" y2="500" class="mcp-line" marker-end="url(#mcpArrow)" stroke-dasharray="3,3" />
+
+  <!-- External MCP Servers Section title with background -->
+  <rect x="210" y="520" width="280" height="25" class="text-bg" />
+  <text x="350" y="535" text-anchor="middle" class="overlay-text" fill="#388e3c">
+    External MCP Servers (Proxied via Coordinator)
+  </text>
+
+  <!-- Proxy flow label -->
+  <rect x="550" y="520" width="140" height="25" class="text-bg" />
+  <text x="620" y="535" text-anchor="middle" class="small-text" fill="#1976d2" font-weight="bold">
+    ⇅ Proxied Tool Calls
+  </text>
+
+  <!-- Data flow label with background -->
+  <rect x="630" y="340" width="80" height="20" class="text-bg" />
+  <text x="670" y="352" text-anchor="middle" class="small-text" fill="#4caf50" font-weight="bold">
+    Live Updates
+  </text>
+
+  <!-- MCP Server boxes -->
+  <rect x="50" y="550" width="120" height="80" rx="6" class="mcp-server-box" />
+  <text x="110" y="570" text-anchor="middle" class="title-text" fill="#388e3c">Filesystem</text>
+  <text x="110" y="585" text-anchor="middle" class="small-text" fill="#666">read_file</text>
+  <text x="110" y="598" text-anchor="middle" class="small-text" fill="#666">write_file</text>
+  <text x="110" y="611" text-anchor="middle" class="small-text" fill="#666">list_directory</text>
+
+  <rect x="190" y="550" width="120" height="80" rx="6" class="mcp-server-box" />
+  <text x="250" y="570" text-anchor="middle" class="title-text" fill="#388e3c">Memory</text>
+  <text x="250" y="585" text-anchor="middle" class="small-text" fill="#666">search_nodes</text>
+  <text x="250" y="598" text-anchor="middle" class="small-text" fill="#666">store_memory</text>
+  <text x="250" y="611" text-anchor="middle" class="small-text" fill="#666">recall_info</text>
+
+  <rect x="330" y="550" width="120" height="80" rx="6" class="mcp-server-box" />
+  <text x="390" y="570" text-anchor="middle" class="title-text" fill="#388e3c">Context7</text>
+  <text x="390" y="585" text-anchor="middle" class="small-text" fill="#666">get_docs</text>
+  <text x="390" y="598" text-anchor="middle" class="small-text" fill="#666">search_docs</text>
+  <text x="390" y="611" text-anchor="middle" class="small-text" fill="#666">get_library</text>
+
+  <rect x="470" y="550" width="120" height="80" rx="6" class="mcp-server-box" />
+  <text x="530" y="570" text-anchor="middle" class="title-text" fill="#388e3c">Sequential</text>
+  <text x="530" y="585" text-anchor="middle" class="small-text" fill="#666">thinking</text>
+  <text x="530" y="598" text-anchor="middle" class="small-text" fill="#666">analyze</text>
+  <text x="530" y="611" text-anchor="middle" class="small-text" fill="#666">problem</text>
+
+  <!-- Key Process Flow -->
+  <text x="350" y="670" text-anchor="middle" class="title-text" fill="#d5d5d5ff">
+    Key Proxy Flow: Agent → Coordinator → External Tools → Presence Tracking
+  </text>
+
+  <text x="50" y="690" class="small-text" fill="#d5d5d5ff">1. Agents connect via single MCP interface</text>
+  <text x="50" y="705" class="small-text" fill="#d5d5d5ff">2. ALL tool calls proxy through coordinator</text>
+  <text x="50" y="720" class="small-text" fill="#d5d5d5ff">3. Coordinator updates agent presence + tracks tasks</text>
+
+  <text x="450" y="690" class="small-text" fill="#d5d5d5ff">4. Agents gain full project awareness via proxy</text>
+  <text x="450" y="705" class="small-text" fill="#d5d5d5ff">5. Real-time coordination prevents conflicts</text>
+  <text x="450" y="720" class="small-text" fill="#d5d5d5ff">6. Single interface → Multiple backends</text>
+
+  <!-- Version info -->
+  <text x="1150" y="790" text-anchor="end" class="small-text" fill="#aaa">
+    Agent Coordinator v0.1.0
+  </text>
+</svg>