Tri-Agent Coordination Protocol — AAO Wave 5

{
  "agent_id": "gemini-cli",
  "device": "mac1",
  "capabilities": ["long-context", "research", "creative"],
  "model": "gemini-3-pro-preview",
  "status": "available"
}

{
  "agent_id": "gemini-cli",
  "registered": true,
  "roster_size": 3,
  "last_seen": "2026-02-26T20:23:56.711904+00:00"
}

available ──[receive task]──> busy ──[task done]──> available
    │                           │
    │                           └──[task failed]──> available
    │
    └──[hit API quota]──> rate_limited ──[quota resets]──> available

{
  "agents": [
    {
      "agent_id": "claude-code",
      "device": "mac2",
      "capabilities": ["code", "research", "architecture"],
      "model": "opus-4",
      "status": "available",
      "last_heartbeat": "2026-02-26T20:23:54.765084+00:00",
      "tasks_completed": 12,
      "reputation_score": 0.85
    },
    {
      "agent_id": "gemini-cli",
      "device": "mac1",
      "capabilities": ["long-context", "research", "creative"],
      "model": "gemini-3-pro-preview",
      "status": "busy",
      "last_heartbeat": "2026-02-26T20:23:56.711904+00:00",
      "tasks_completed": 7,
      "reputation_score": 0.72
    },
    {
      "agent_id": "codex-cli",
      "device": "mac3",
      "capabilities": ["structured-output", "data-analysis", "math"],
      "model": "gpt-5.3-codex",
      "status": "available",
      "last_heartbeat": "2026-02-26T20:24:10.123456+00:00",
      "tasks_completed": 4,
      "reputation_score": 0.90
    }
  ],
  "total": 3,
  "as_of": "2026-02-26T20:24:15.000000+00:00"
}

{
  "agent_id": "codex-cli",
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "device": "mac3"
}

{
  "claimed": true,
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claimed_by": "codex-cli",
  "conflict": null
}

{
  "claimed": false,
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "claimed_by": "claude-code",
  "conflict": "claude-code"
}

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "history": [
    {
      "agent_id": "claude-code",
      "device": "mac2",
      "action": "claimed",
      "timestamp": "2026-02-26T20:24:02+00:00",
      "reason": null
    },
    {
      "agent_id": "gemini-cli",
      "device": "mac1",
      "action": "claimed",
      "timestamp": "2026-02-26T20:30:15+00:00",
      "reason": null
    }
  ],
  "current_owner": "gemini-cli",
  "context_summary": "Task has 6 triples: claimed_by, claimed_at, claimed_on_device, ..."
}

┌─────────────────────────────────────────────────────────────────┐
│                     AGENT LIFECYCLE                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. STARTUP                                                     │
│     POST /api/agent/heartbeat                                   │
│     {"agent_id":"YOUR_ID", "status":"available", ...}           │
│     Start 30s heartbeat timer                                   │
│                                                                 │
│  2. TASK ACQUISITION (from Supabase mac_tasks queue)            │
│     a) Poll mac_tasks WHERE status='pending'                    │
│        ORDER BY priority ASC, created_at ASC                    │
│     b) GET /api/agent/roster                                    │
│        Check if task is better suited for another agent         │
│     c) POST /api/agent/claim                                    │
│        {"agent_id":"YOUR_ID", "task_id":"...", "device":"..."}  │
│        ├─ claimed:true  → proceed to step 3                    │
│        └─ claimed:false → skip, go back to 2a for next task    │
│                                                                 │
│  3. EXECUTION                                                   │
│     a) POST /api/agent/heartbeat (status: "busy")               │
│     b) UPDATE mac_tasks SET status='running'                    │
│        WHERE id=task_id                                         │
│     c) Execute the task                                         │
│     d) Continue heartbeating every 30s (status: "busy")         │
│                                                                 │
│  4. COMPLETION                                                  │
│     a) UPDATE mac_tasks SET status='completed'                  │
│     b) POST /api/knowledge/attestation    ← existing W3 endpoint│
│        {"device":"YOUR_DEVICE",                                 │
│         "quality":"high|medium|low|failed",                     │
│         "task_id":"...", "task_type":"code"}                    │
│     c) POST /api/agent/heartbeat (status: "available")          │
│     d) Go back to step 2                                        │
│                                                                 │
│  5. RATE LIMIT HIT                                              │
│     a) POST /api/agent/heartbeat (status: "rate_limited")       │
│     b) SmartRouter will stop routing tasks to you               │
│     c) Wait for quota reset, then:                              │
│     d) POST /api/agent/heartbeat (status: "available")          │
│                                                                 │
│  6. SHUTDOWN                                                    │
│     Stop heartbeating → GK evicts you after 60s                 │
│     No explicit "disconnect" needed                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

-- Relevant columns for agent coordination:
mac_tasks.id                  -- UUID, use as task_id in claims
mac_tasks.status              -- 'pending', 'running', 'completed', 'failed'
mac_tasks.priority            -- 0=CRITICAL, 1=HIGH, 2=MEDIUM, 3=LOW
mac_tasks.description         -- Task content
mac_tasks.metadata            -- JSONB with task_type, project_path, etc.
mac_tasks.relay_from          -- Device that relayed the task
mac_tasks.relay_to            -- Target device (null = any)
mac_tasks.relay_reason        -- 'timeout', 'manual', 'capability'
mac_tasks.pickup_instructions -- JSONB context for receiving agent
mac_tasks.timeout_at          -- Auto-reclaim deadline
mac_tasks.admissibility_token -- HMAC from GK (W1)
mac_tasks.context_policy_ref  -- Policy scope: 'code', 'research', 'general'

SELECT * FROM mac_tasks
WHERE status = 'pending'
  AND (relay_to IS NULL OR relay_to = 'YOUR_DEVICE')
ORDER BY priority ASC, created_at ASC
LIMIT 5;

POST /api/knowledge/attestation
{
  "device": "mac1",
  "quality": "high",
  "task_id": "a1b2c3d4-...",
  "task_type": "research",
  "duration_ms": 45000,
  "output_length": 3200,
  "had_errors": false
}

POST /api/task_ticket
{
  "task_id": "a1b2c3d4-...",
  "device": "mac1",
  "policy_id": "research",
  "ttl_seconds": 3600
}

// In spawn() method, after process starts:
async spawn(task, model) {
  // ... existing spawn logic ...

  // NEW: Claim task through GK before execution
  const claimResp = await fetch('http://localhost:8001/api/agent/claim', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent_id: 'gemini-cli',
      task_id: task.id,
      device: process.env.DEVICE_ID || 'mac1'
    })
  }).then(r => r.json());

  if (!claimResp.claimed) {
    console.log(`Task ${task.id} already claimed by ${claimResp.conflict}, skipping`);
    return null; // Don't spawn
  }

  // ... proceed with Gemini spawn ...
}

// In daemon_v3.js main loop or GeminiSpawner constructor:
setInterval(async () => {
  const activeCount = geminiSpawner.activeAgents.size;
  await fetch('http://localhost:8001/api/agent/heartbeat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agent_id: 'gemini-cli',
      device: process.env.DEVICE_ID || 'mac1',
      capabilities: ['long-context', 'research', 'creative'],
      model: 'gemini-3-pro-preview',
      status: activeCount > 0 ? 'busy' : 'available'
    })
  }).catch(() => {}); // Best-effort, don't crash on GK downtime
}, 30_000);

## Agent Coordination Protocol

Before executing any task from the Supabase queue:
1. Heartbeat: `curl -X POST localhost:8001/api/agent/heartbeat -H "Content-Type: application/json" -d '{"agent_id":"codex-cli","device":"mac3","capabilities":["structured-output","data-analysis","math"],"model":"gpt-5.3-codex","status":"available"}'`
2. Claim: `curl -X POST localhost:8001/api/agent/claim -H "Content-Type: application/json" -d '{"agent_id":"codex-cli","task_id":"TASK_UUID","device":"mac3"}'`
3. If `claimed:false` → skip the task, another agent has it.
4. After completion: post attestation to `/api/knowledge/attestation`
5. If rate-limited: heartbeat with `"status":"rate_limited"`

# In [home-path] after validation:
curl -s -X POST localhost:8001/api/agent/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"codex-cli","device":"'"$(hostname -s)"'","capabilities":["structured-output","data-analysis","math"],"model":"gpt-5.3-codex","status":"available"}' \
  > /dev/null 2>&1 || true

# All triples about claude-code
curl "localhost:8001/api/knowledge?subject=agent:claude-code"

# All triples about a specific task
curl "localhost:8001/api/knowledge?subject=task:a1b2c3d4-..."

# All claims (across all tasks)
curl "localhost:8001/api/knowledge?predicate=claimed_by"

# All status updates
curl "localhost:8001/api/knowledge?predicate=has_status"

# 1. Health check
curl -s localhost:8001/health | python3 -m json.tool

# 2. Register all three agents
curl -s -X POST localhost:8001/api/agent/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"claude-code","device":"mac2","capabilities":["code","research","architecture"],"model":"opus-4","status":"available"}'

curl -s -X POST localhost:8001/api/agent/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"gemini-cli","device":"mac1","capabilities":["long-context","research","creative"],"model":"gemini-3-pro-preview","status":"available"}'

curl -s -X POST localhost:8001/api/agent/heartbeat \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"codex-cli","device":"mac3","capabilities":["structured-output","data-analysis","math"],"model":"gpt-5.3-codex","status":"available"}'

# 3. Verify roster shows all 3
curl -s localhost:8001/api/agent/roster | python3 -m json.tool

# 4. Claim a task (should succeed)
curl -s -X POST localhost:8001/api/agent/claim \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"claude-code","task_id":"test-verify","device":"mac2"}'

# 5. Conflict test (should fail with conflict)
curl -s -X POST localhost:8001/api/agent/claim \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"gemini-cli","task_id":"test-verify","device":"mac1"}'

# 6. Handoff history
curl -s localhost:8001/api/agent/handoff/test-verify | python3 -m json.tool