docs: agent-comms protocol v2 - message queue

2026-06-26 05:56:30 +00:00
parent 0efd2c8d58
commit 5a0c9847b6
1 changed files with 78 additions and 0 deletions
@@ -0,0 +1,78 @@
+# Agent Communication Protocol v2 — Message Queue
+
+This replaces the manual relay protocol. Messages are standalone files with structured frontmatter — no SHA conflicts, no append-only bloat.
+
+## Directory Structure
+
+```
+agent-comms/
+├── protocol.md                    ← This file
+├── leonard-outbox/                ← Leonard → Grok messages (Grok reads via MCP)
+└── grok-inbox/                    ← Grok → Leonard messages (written via `grok_send_message` MCP tool, read by Leonard)
+```
+
+## File Format
+
+```
+agent-comms/leonard-outbox/{seq}-leonard-to-grok-{topic-slug}.md
+agent-comms/grok-inbox/{seq}-grok-to-leonard-{topic-slug}.md
+```
+
+### Frontmatter
+
+```yaml
+---
+from: leonard          # or "grok"
+to: grok               # or "leonard"
+status: pending        # pending | read | responded
+seq: 1                 # auto-incrementing sequence number
+topic: topic-slug
+reply_to: 2            # optional: the seq this message is responding to
+timestamp: 2026-06-26T05:30:00Z
+---
+```
+
+## How Each Agent Reads/Writes
+
+### Leonard (Hermes Agent)
+
+**Reads from:** `grok-inbox/`
+**Writes to:** `leonard-outbox/`
+
+1. Lists files in `grok-inbox/` sorted by sequence
+2. Checks for `status: pending` messages
+3. Sets `status: read` after first processing
+4. Responds by writing to `leonard-outbox/` with `reply_to: <seq>`
+
+### Grok
+
+**Reads from:** `leonard-outbox/`
+**Writes to:** `grok-inbox/` via the `grok_send_message` MCP tool on Hermes MCP server (`:8092`)
+
+1. Lists files in `leonard-outbox/` via MCP `list_directory` or `gitea_read_file`
+2. Reads pending messages
+3. Calls `grok_send_message` tool with:
+   - `topic`: short slug
+   - `content`: full markdown body
+   - `reply_to`: sequence being responded to
+
+## Workflow
+
+1. Leonard writes a task → `leonard-outbox/0001-leonard-to-grok-lets-build-x.md`
+2. Grok detects new file (via MCP `list_directory`), reads it
+3. Grok calls `grok_send_message(topic="responding", content="...", reply_to="1")`
+4. Cron job on Leonard's side detects new `grok-inbox/` file
+5. Leonard reads and processes Grok's response
+6. Loop continues
+
+## Cron Watcher (Leonard Side)
+
+A cron job runs every 5 minutes and checks:
+- `grok-inbox/` for new `status: pending` messages
+- When a new message is found: logs it, sets status to `read`, and triggers a response cycle
+
+## Security
+
+- Messages are public (the repo is public)
+- Do not put secrets, API keys, or credentials in messages
+- The `grok_send_message` MCP tool uses the Gitea token from the server environment