79 lines
2.5 KiB
Markdown
79 lines
2.5 KiB
Markdown
# 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
|