docs: add mail protocol reference (gt-k294l)
Document inter-agent mail types: - POLECAT_DONE, MERGE_READY, MERGED - WITNESS_PING, HELP, HANDOFF 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
263
docs/mail-protocol.md
Normal file
263
docs/mail-protocol.md
Normal file
@@ -0,0 +1,263 @@
|
|||||||
|
# Gas Town Mail Protocol
|
||||||
|
|
||||||
|
> Reference for inter-agent mail communication in Gas Town
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Gas Town agents coordinate via mail messages routed through the beads system.
|
||||||
|
Mail uses `type=message` beads with routing handled by `gt mail`.
|
||||||
|
|
||||||
|
## Message Types
|
||||||
|
|
||||||
|
### POLECAT_DONE
|
||||||
|
|
||||||
|
**Route**: Polecat → Witness
|
||||||
|
|
||||||
|
**Purpose**: Signal work completion, trigger cleanup flow.
|
||||||
|
|
||||||
|
**Subject format**: `POLECAT_DONE <polecat-name>`
|
||||||
|
|
||||||
|
**Body format**:
|
||||||
|
```
|
||||||
|
Exit: MERGED|ESCALATED|DEFERRED
|
||||||
|
Issue: <issue-id>
|
||||||
|
MR: <mr-id> # if exit=MERGED
|
||||||
|
Branch: <branch>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Trigger**: `gt polecat done` command generates this automatically.
|
||||||
|
|
||||||
|
**Handler**: Witness creates a cleanup wisp for the polecat.
|
||||||
|
|
||||||
|
### MERGE_READY
|
||||||
|
|
||||||
|
**Route**: Witness → Refinery
|
||||||
|
|
||||||
|
**Purpose**: Signal a branch is ready for merge queue processing.
|
||||||
|
|
||||||
|
**Subject format**: `MERGE_READY <polecat-name>`
|
||||||
|
|
||||||
|
**Body format**:
|
||||||
|
```
|
||||||
|
Branch: <branch>
|
||||||
|
Issue: <issue-id>
|
||||||
|
Polecat: <polecat-name>
|
||||||
|
Verified: clean git state, issue closed
|
||||||
|
```
|
||||||
|
|
||||||
|
**Trigger**: Witness sends after verifying polecat work is complete.
|
||||||
|
|
||||||
|
**Handler**: Refinery adds to merge queue, processes when ready.
|
||||||
|
|
||||||
|
### MERGED
|
||||||
|
|
||||||
|
**Route**: Refinery → Witness
|
||||||
|
|
||||||
|
**Purpose**: Confirm branch was merged successfully, safe to nuke polecat.
|
||||||
|
|
||||||
|
**Subject format**: `MERGED <polecat-name>`
|
||||||
|
|
||||||
|
**Body format**:
|
||||||
|
```
|
||||||
|
Branch: <branch>
|
||||||
|
Issue: <issue-id>
|
||||||
|
Merged-At: <timestamp>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Trigger**: Refinery sends after successful merge to main.
|
||||||
|
|
||||||
|
**Handler**: Witness completes cleanup wisp, nukes polecat worktree.
|
||||||
|
|
||||||
|
### WITNESS_PING
|
||||||
|
|
||||||
|
**Route**: Witness → Deacon (all witnesses send)
|
||||||
|
|
||||||
|
**Purpose**: Second-order monitoring - ensure Deacon is alive.
|
||||||
|
|
||||||
|
**Subject format**: `WITNESS_PING <rig>`
|
||||||
|
|
||||||
|
**Body format**:
|
||||||
|
```
|
||||||
|
Rig: <rig>
|
||||||
|
Timestamp: <timestamp>
|
||||||
|
Patrol: <cycle-number>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Trigger**: Each witness sends periodically (every N patrol cycles).
|
||||||
|
|
||||||
|
**Handler**: Deacon acknowledges. If no ack, witnesses escalate to Mayor.
|
||||||
|
|
||||||
|
### HELP
|
||||||
|
|
||||||
|
**Route**: Any → escalation target (usually Mayor)
|
||||||
|
|
||||||
|
**Purpose**: Request intervention for stuck/blocked work.
|
||||||
|
|
||||||
|
**Subject format**: `HELP: <brief-description>`
|
||||||
|
|
||||||
|
**Body format**:
|
||||||
|
```
|
||||||
|
Agent: <agent-id>
|
||||||
|
Issue: <issue-id> # if applicable
|
||||||
|
Problem: <description>
|
||||||
|
Tried: <what was attempted>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Trigger**: Agent unable to proceed, needs external help.
|
||||||
|
|
||||||
|
**Handler**: Escalation target assesses and intervenes.
|
||||||
|
|
||||||
|
### HANDOFF
|
||||||
|
|
||||||
|
**Route**: Agent → self (or successor)
|
||||||
|
|
||||||
|
**Purpose**: Session continuity across context limits/restarts.
|
||||||
|
|
||||||
|
**Subject format**: `🤝 HANDOFF: <brief-context>`
|
||||||
|
|
||||||
|
**Body format**:
|
||||||
|
```
|
||||||
|
attached_molecule: <molecule-id> # if work in progress
|
||||||
|
attached_at: <timestamp>
|
||||||
|
|
||||||
|
## Context
|
||||||
|
<freeform notes for successor>
|
||||||
|
|
||||||
|
## Status
|
||||||
|
<where things stand>
|
||||||
|
|
||||||
|
## Next
|
||||||
|
<what successor should do>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Trigger**: `gt handoff` command, or manual send before session end.
|
||||||
|
|
||||||
|
**Handler**: Next session reads handoff, continues from context.
|
||||||
|
|
||||||
|
## Format Conventions
|
||||||
|
|
||||||
|
### Subject Line
|
||||||
|
|
||||||
|
- **Type prefix**: Uppercase, identifies message type
|
||||||
|
- **Colon separator**: After type for structured info
|
||||||
|
- **Brief context**: Human-readable summary
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
POLECAT_DONE nux
|
||||||
|
MERGE_READY gastown/nux
|
||||||
|
HELP: Polecat stuck on test failures
|
||||||
|
🤝 HANDOFF: Schema work in progress
|
||||||
|
```
|
||||||
|
|
||||||
|
### Body Structure
|
||||||
|
|
||||||
|
- **Key-value pairs**: For structured data (one per line)
|
||||||
|
- **Blank line**: Separates structured data from freeform content
|
||||||
|
- **Markdown sections**: For freeform content (##, lists, code blocks)
|
||||||
|
|
||||||
|
### Addresses
|
||||||
|
|
||||||
|
Format: `<rig>/<role>` or `<rig>/<type>/<name>`
|
||||||
|
|
||||||
|
Examples:
|
||||||
|
```
|
||||||
|
gastown/witness # Witness for gastown rig
|
||||||
|
beads/refinery # Refinery for beads rig
|
||||||
|
gastown/polecats/nux # Specific polecat
|
||||||
|
mayor/ # Town-level Mayor
|
||||||
|
deacon/ # Town-level Deacon
|
||||||
|
```
|
||||||
|
|
||||||
|
## Protocol Flows
|
||||||
|
|
||||||
|
### Polecat Completion Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
Polecat Witness Refinery
|
||||||
|
│ │ │
|
||||||
|
│ POLECAT_DONE │ │
|
||||||
|
│─────────────────────────>│ │
|
||||||
|
│ │ │
|
||||||
|
│ (verify clean) │
|
||||||
|
│ │ │
|
||||||
|
│ │ MERGE_READY │
|
||||||
|
│ │─────────────────────────>│
|
||||||
|
│ │ │
|
||||||
|
│ │ (merge to main)
|
||||||
|
│ │ │
|
||||||
|
│ │ MERGED │
|
||||||
|
│ │<─────────────────────────│
|
||||||
|
│ │ │
|
||||||
|
│ (nuke polecat) │
|
||||||
|
│ │ │
|
||||||
|
```
|
||||||
|
|
||||||
|
### Second-Order Monitoring
|
||||||
|
|
||||||
|
```
|
||||||
|
Witness-1 ──┐
|
||||||
|
│ WITNESS_PING
|
||||||
|
Witness-2 ──┼────────────────> Deacon
|
||||||
|
│
|
||||||
|
Witness-N ──┘
|
||||||
|
│
|
||||||
|
(if no response)
|
||||||
|
│
|
||||||
|
<────────────────────┘
|
||||||
|
Escalate to Mayor
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implementation
|
||||||
|
|
||||||
|
### Sending Mail
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic send
|
||||||
|
gt mail send <addr> -s "Subject" -m "Body"
|
||||||
|
|
||||||
|
# With structured body
|
||||||
|
gt mail send gastown/witness -s "MERGE_READY nux" -m "Branch: feature-xyz
|
||||||
|
Issue: gt-abc
|
||||||
|
Polecat: nux
|
||||||
|
Verified: clean"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Receiving Mail
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check inbox
|
||||||
|
gt mail inbox
|
||||||
|
|
||||||
|
# Read specific message
|
||||||
|
gt mail read <msg-id>
|
||||||
|
|
||||||
|
# Mark as read
|
||||||
|
gt mail ack <msg-id>
|
||||||
|
```
|
||||||
|
|
||||||
|
### In Patrol Formulas
|
||||||
|
|
||||||
|
Formulas should:
|
||||||
|
1. Check inbox at start of each cycle
|
||||||
|
2. Parse subject prefix to route handling
|
||||||
|
3. Extract structured data from body
|
||||||
|
4. Take appropriate action
|
||||||
|
5. Mark mail as read after processing
|
||||||
|
|
||||||
|
## Extensibility
|
||||||
|
|
||||||
|
New message types follow the pattern:
|
||||||
|
1. Define subject prefix (TYPE: or TYPE_SUBTYPE)
|
||||||
|
2. Document body format (key-value pairs + freeform)
|
||||||
|
3. Specify route (sender → receiver)
|
||||||
|
4. Implement handlers in relevant patrol formulas
|
||||||
|
|
||||||
|
The protocol is intentionally simple - structured enough for parsing,
|
||||||
|
flexible enough for human debugging.
|
||||||
|
|
||||||
|
## Related Documents
|
||||||
|
|
||||||
|
- `docs/agent-as-bead.md` - Agent identity and slots
|
||||||
|
- `.beads/formulas/mol-witness-patrol.formula.toml` - Witness handling
|
||||||
|
- `internal/mail/` - Mail routing implementation
|
||||||
Reference in New Issue
Block a user