# Autonomous Agent Coordination Architecture (2025-12-23) ## Problem Agents need to work autonomously without human intervention. Orchestrator should coordinate workers and reviewers through WebSocket messaging. ## Solution: Periodic Ping + State Query **Key Decision:** No event queue. Rails is not reactive. Orchestrator queries state when pinged. ## Architecture ``` PingJob (every 30s) → Is Orchestrator idle for 2+ minutes? → YES: Send ping → NO: Wait, check again Orchestrator receives ping → STEP 1: Check available agents - list_members(role: "worker", status: "idle") - list_members(role: "reviewer", status: "idle") → If NONE available → return (everyone busy) → STEP 2: Check work needing done - pending_audit tickets - todo tickets with assignee (failed reviews) - todo tickets without assignee → STEP 3: Match work to agents - pending_audit + idle reviewer → Broadcast "Review ticket #X" - failed ticket → Broadcast "Work on ticket #X" to assigned worker - unassigned ticket + idle worker → assign_ticket() + Broadcast "Work on ticket #X" ``` ## Agent States | Status | Meaning | Changed By | |--------|---------|------------| | `idle` | Available for work | Agent calls mark_idle (MCP) | | `busy` | Actively working | Agent calls mark_busy (MCP) | **No `offline` status** - WebSocket connects are transient. AgentChannel only logs, doesn't update status. ## Message Format - `"Work on ticket #58"` → Worker - `"Review ticket #58"` → Reviewer ## Key Principles 1. **Agents don't claim tickets** - Orchestrator assigns, Workers execute 2. **Workers mark idle AFTER review submission** - can work on other tickets while review pending 3. **Failed reviews stay with same worker** - Orchestrator broadcasts "Work on ticket #X" again 4. **Orchestrator can be busy too** - PingJob only sends if idle for 2+ minutes 5. **All broadcasts go through AgentChannel** - agent_worker, agent_reviewer, agent_orchestrator streams ## Tickets Created **Epic #62:** Autonomous Agent Coordination via WebSocket - #63: Add agent status tracking (status, status_updated_at) - #64: Add mark_busy/mark_idle MCP tools - #65: Create OrchestratorPingJob - #66: Update AgentChannel to only log ## Dependencies - #59 (WebSocket Bridge) - already implemented, tested with curl - AgentChannel already exists - agent-bridge.go already connects to WebSocket