# A2A Protocol Specification v0.3

## Overview
Agent-to-Agent (A2A) is a decentralized message protocol for agent negotiation within newOS4. Agents communicate through a **shared VFS scratchpad** (`/_agents/scratchpad.json`). No central broker — discovery is via VFS registrations.

## Scratchpad Data Structure

All messages live in a single JSON file at `/_agents/scratchpad.json`:

```json
{
  "messages": [
    {
      "id": "msg_001",
      "from": "user",
      "to": "researcher",
      "type": "request",
      "capability": "code.search",
      "payload": { "query": "test" },
      "ttl": 300000,
      "status": "pending",
      "ts": 1234567890,
      "reply_to": null
    }
  ],
  "seq": 1,
  "agents": {
    "researcher": {
      "last_poll": 1234567890,
      "capabilities": ["coder", "reader", "writer"]
    }
  }
}
```

### Message Statuses
| Status | Meaning |
|---|---|
| `pending` | Not yet delivered |
| `delivered` | Read by recipient via poll |
| `completed` | Acknowledged with result |
| `failed` | Rejected with error |

## Commands

| Command | Description |
|---|---|
| `a2a-post <to> <type> <capability> <payload...>` | Post a message to an agent |
| `a2a-poll [agentId]` | Poll for pending messages (default: current agent or "user") |
| `a2a-ack <msgId> <result...>` | Mark message completed with result |
| `a2a-reject <msgId> <error...>` | Mark message failed with error |
| `a2a-status` | Show scratchpad stats per agent |
| `a2a-prune` | Clean up expired and old completed messages |

## Lifecycle

1. **Register** — `agent-register <name> <capabilities>` creates agent dir + auto-registers in scratchpad
2. **Post** — `a2a-post <to> <type> <capability> <payload>` writes to scratchpad with `status: pending`
3. **Poll** — `a2a-poll <agentId>` returns pending messages, marks them `delivered`
4. **Ack/Reject** — Recipient acknowledges with result or rejects with error
5. **Unregister** — `agent-unregister <id>` removes agent from scratchpad + deletes VFS dir
6. **Auto-prune** — Every 60 seconds, expired messages (past TTL) and completed messages older than 1 hour are removed

## Integration Points

- **Orchestrator** — auto-calls `a2aRegister` on agent spawn, `a2aUnregister` on kill
- **Lease system** — posts A2A messages on lease create and lease revoke
- **Garbage collection** — `_a2aCleanup()` removes orphaned agent entries when agent dirs are deleted

## Implementation Status
- ✅ Scratchpad data structure (/_agents/scratchpad.json)
- ✅ a2a-post / a2a-poll / a2a-ack / a2a-reject / a2a-status / a2a-prune CLI commands
- ✅ Auto-register on agent spawn
- ✅ Auto-unregister on agent kill
- ✅ A2A messages on lease create/revoke
- ✅ Auto-prune timer (60s interval)
- ✅ Garbage collection for orphaned agent entries
- ✅ Security whitelist (all A2A commands whitelisted, not destructive)