# A2A Protocol Specification v0.1

## 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 shared message queue. 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
Each agent has a VFS mailbox at `/agents/<agent_id>/inbox.json` and publishes to `/agents/<agent_id>/outbox.json`. The orchestrator monitors inboxes via periodic polling (500ms interval).

## 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.

## Lifecycle
1. Orchestrator broadcasts AGENT_REQUEST
2. Workers respond with capability claim
3. Orchestrator issues LEASE with TTL
4. Worker executes, sends RESPONSE
5. Orchestrator ACKs, LEASE expires
6. Worker returns to available pool