Replace gastown-specific references with generic alternatives throughout the codebase: - Rename --gastown flag to --orchestrator in bd doctor - Rename gastownMode/gastownThreshold params to orchestratorMode/orchestratorThreshold - Rename isGasTownTownRoot() to isOrchestratorRoot() - Replace "gastown" in CLI examples with generic rig names (my-project, other-project) - Update comments replacing "Gas Town" with "orchestrator" or "multi-agent workspace" - Update active docs (DOLT.md, CONFIG.md, ADVANCED.md, etc.) - Update test data to use generic names instead of "gastown" - Update role templates (deacon, witness, refinery) to use generic language Preserved as historical (not changed): - CHANGELOG.md entries (historical record) - ARTICLES.md (links to real published articles) - info.go version notes (historical release notes) - gastown/ file path references in dolt-concurrency.md (point to actual repo)
117 lines
3.1 KiB
Markdown
117 lines
3.1 KiB
Markdown
# Messaging in Beads
|
|
|
|
Beads supports messaging as a first-class issue type, enabling inter-agent and human-agent communication within the same system used for issue tracking.
|
|
|
|
## Architecture
|
|
|
|
Mail commands (`bd mail`) delegate to an external mail provider (typically `gt mail` in an orchestrator). Beads stores messages as issues with `type: message`, threading via `replies_to` dependencies, and ephemeral lifecycle via the `ephemeral` flag.
|
|
|
|
This design separates concerns:
|
|
- **Beads** = data plane (stores messages as issues)
|
|
- **Orchestrator** = control plane (routing, delivery, notifications)
|
|
|
|
## Setup
|
|
|
|
Configure the mail delegate (one-time):
|
|
|
|
```bash
|
|
# Environment variable (recommended for agents)
|
|
export BEADS_MAIL_DELEGATE="gt mail"
|
|
|
|
# Or per-project config
|
|
bd config set mail.delegate "gt mail"
|
|
```
|
|
|
|
## Sending and Receiving
|
|
|
|
```bash
|
|
# Send mail (delegates to gt mail)
|
|
bd mail send worker/ -s "Review needed" -m "Please review bd-abc"
|
|
|
|
# Check inbox
|
|
bd mail inbox
|
|
|
|
# Read a message
|
|
bd mail read msg-123
|
|
|
|
# Reply to a thread
|
|
bd mail reply msg-123 -m "Reviewed and approved"
|
|
```
|
|
|
|
## Message Issue Type
|
|
|
|
Messages are issues with `type: message`:
|
|
|
|
| Field | Purpose |
|
|
|-------|---------|
|
|
| `type` | `message` |
|
|
| `sender` | Who sent the message |
|
|
| `assignee` | Recipient |
|
|
| `title` | Subject line |
|
|
| `description` | Message body |
|
|
| `status` | `open` (unread) / `closed` (read) |
|
|
| `ephemeral` | If true, eligible for bulk cleanup |
|
|
|
|
## Threading
|
|
|
|
Messages form threads via `replies_to` dependencies. View a full thread:
|
|
|
|
```bash
|
|
bd show msg-123 --thread
|
|
```
|
|
|
|
This traces the `replies_to` chain to find the root message, then collects all replies via BFS, displaying the conversation with proper indentation.
|
|
|
|
Thread display shows:
|
|
- Sender and recipient
|
|
- Timestamp
|
|
- Subject and body
|
|
- Reply depth (indented)
|
|
|
|
## Ephemeral Messages
|
|
|
|
Messages marked `ephemeral: true` are transient - they can be bulk-deleted after a swarm completes:
|
|
|
|
```bash
|
|
# Clean up closed ephemeral messages
|
|
bd cleanup --ephemeral --force
|
|
|
|
# Preview what would be deleted
|
|
bd cleanup --ephemeral --dry-run
|
|
|
|
# Only delete ephemeral messages older than 7 days
|
|
bd cleanup --ephemeral --older-than 7 --force
|
|
```
|
|
|
|
Ephemeral messages are:
|
|
- Excluded from `bd ready` by default
|
|
- Not synced to remotes (transient)
|
|
- Eligible for bulk deletion when closed
|
|
|
|
## Identity
|
|
|
|
The actor identity (used for `sender` on messages) is resolved in order:
|
|
|
|
1. `--actor` flag on the command
|
|
2. `BEADS_ACTOR` environment variable
|
|
3. `BD_ACTOR` environment variable (deprecated alias)
|
|
4. `git config user.name`
|
|
5. `$USER` environment variable
|
|
6. `"unknown"`
|
|
|
|
## Beads Event Hooks
|
|
|
|
Scripts in `.beads/hooks/` run after certain events:
|
|
|
|
| Hook | Trigger |
|
|
|------|---------|
|
|
| `on_create` | After `bd create` |
|
|
| `on_update` | After `bd update` |
|
|
| `on_close` | After `bd close` |
|
|
|
|
Hooks receive event data as JSON on stdin. This enables orchestrator integration (e.g., notifying services of new messages) without beads knowing about the orchestrator.
|
|
|
|
## See Also
|
|
|
|
- [Graph Links](graph-links.md) - relates_to, duplicates, supersedes, replies_to
|
|
- [CLI Reference](CLI_REFERENCE.md) - All commands
|