1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
# 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)
|
