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