# A2A Protocol Specification v0.2

## Overview
Agent-to-Agent (A2A) is a decentralized message protocol for agent negotiation within newOS4. Agents discover each other via VFS registrations and communicate through a VFS mailbox system. No central broker.

## Message Format
All messages are JSON with this envelope:

```json
{
  "a2a_version": "0.1",
  "msg_id": "<uuid>",
  "type": "request" | "response" | "broadcast" | "lease" | "heartbeat",
  "from": "<agent_id>",
  "to": "<agent_id>" | "*",
  "timestamp": "<ISO 8601>",
  "ttl_seconds": 30,
  "contract": {
    "capabilities": ["list_files", "read_file", "web_search"],
    "constraints": {
      "max_tool_turns": 8,
      "max_duration_seconds": 60
    }
  },
  "payload": { }
}
```

## Transport Layer (VFS Mailbox)
Each agent has a VFS mailbox:
- **Inbox** — `/agents/<agent_id>/inbox.json` — receives incoming A2A messages
- **Outbox** — `/agents/<agent_id>/outbox.json` — agent writes results here after execution

The orchestrator polls all agent inboxes every **500ms** via `_pollAgentMailboxes()`. When a new A2A message appears, it:
1. Reads the message envelope
2. Routes by type:
   - `request` — task delegation, checks outbox for completion
   - `response` — task result from agent
   - `broadcast` — capability advertisement
   - `heartbeat` — updates agent's lastHeartbeat timestamp
3. Marks messages as `_processed` to avoid re-routing

## Message Types
- **request**: Point-to-point task delegation. From=orchestrator, To=worker.
- **response**: Task result. From=worker, To=orchestrator.
- **broadcast**: Discovery / capability advertisement. To="*".
- **lease**: Time-bound contract granting a worker exclusive task rights.
- **heartbeat**: Alive signal. Every 5 seconds. Missing 3 consecutive = presumed dead.

## Commands
- `a2a-send <agent-id> <json-message>` — Send an A2A message to an agent's inbox
- `a2a-list` — Show all A2A messages across agents with status

## Lifecycle
1. Orchestrator sends `request` to agent's inbox via `a2a-send`
2. AI module receives delegated task, executes it
3. Result written to agent's outbox
4. Polling loop detects outbox completion, sends `response` message
5. Orchestrator marks lease as complete, agent returns to idle pool

## Implementation Status
- ✅ Message format (v0.1 envelope)
- ✅ VFS mailbox transport (inbox.json / outbox.json)
- ✅ 500ms polling loop in orchestrator
- ✅ Type routing (request, response, broadcast, heartbeat)
- ✅ a2a-send / a2a-list CLI commands
- ⬜ Heartbeat sending from worker agents
- ⬜ Full broadcast discovery flow
- ⬜ Lease revocation via A2A message (currently uses separate LeaseModule)