1 files changed, 45 insertions, 0 deletions
diff --git a/A2A_protocol_spec.md b/A2A_protocol_spec.md
new file mode 100644
index 0000000..e73b0e9
--- /dev/null
+++ b/A2A_protocol_spec.md
@@ -0,0 +1,45 @@
+# 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
+\ No newline at end of file