Add Agent Mail multi-workspace deployment guide and scripts
- docs/AGENT_MAIL_DEPLOYMENT.md: 10-step deployment plan for 13 workspaces - docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md: Architecture and configuration guide - scripts/setup-agent-mail-workspace.sh: Auto-configure .envrc per workspace - scripts/start-agent-mail-server.sh: Start Agent Mail server - scripts/stop-agent-mail-server.sh: Stop Agent Mail server - scripts/agent-mail-status.sh: Monitor server and all channels Supports 3-channel setup: beads.dev, vc.dev, wyvern.dev Ready for 0.23.0 deployment with Agent Mail integration Amp-Thread-ID: https://ampcode.com/threads/T-bc960efb-3ddc-4635-8c8e-a42a6e9e67d9 Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
643
docs/AGENT_MAIL_DEPLOYMENT.md
Normal file
643
docs/AGENT_MAIL_DEPLOYMENT.md
Normal file
@@ -0,0 +1,643 @@
|
|||||||
|
# Agent Mail Deployment - Last Mile Steps
|
||||||
|
|
||||||
|
Complete step-by-step guide to deploy Agent Mail across all 12 beads-enabled workspaces.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- ✅ MCP Agent Mail package installed at `~/src/mcp_agent_mail/`
|
||||||
|
- ✅ beads integration code completed (just finished)
|
||||||
|
- ✅ Helper scripts created in `scripts/`
|
||||||
|
- ✅ direnv installed (`brew install direnv`)
|
||||||
|
- ✅ direnv hook added to shell config
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
**One Server, Three Channels:**
|
||||||
|
- **Agent Mail Server**: Single instance on `http://127.0.0.1:8765`
|
||||||
|
- **beads.dev**: 5 beads workers communicate here
|
||||||
|
- **vc.dev**: 5 vc workers communicate here
|
||||||
|
- **wyvern.dev**: 3 wyvern workers communicate here
|
||||||
|
|
||||||
|
**Total: 13 workspaces** (12 repos + main beads for version bump)
|
||||||
|
|
||||||
|
## Step 1: Version Bump (5 minutes)
|
||||||
|
|
||||||
|
Since Agent Mail integration is brand new, bump beads version first.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
|
||||||
|
# Determine new version (check current first)
|
||||||
|
./bd --version
|
||||||
|
# Example output: bd version 0.16.0
|
||||||
|
|
||||||
|
# Bump to next version
|
||||||
|
./scripts/bump-version.sh 0.23.0 --commit
|
||||||
|
|
||||||
|
# Push to trigger release
|
||||||
|
git push origin main
|
||||||
|
git push origin v0.23.0
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rationale:** All workspaces should use the new version with Agent Mail support.
|
||||||
|
|
||||||
|
## Step 2: Start Agent Mail Server (2 minutes)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
|
||||||
|
# Start server in background
|
||||||
|
./scripts/start-agent-mail-server.sh
|
||||||
|
|
||||||
|
# Expected output:
|
||||||
|
# ✅ Agent Mail server started successfully!
|
||||||
|
# PID: 12345
|
||||||
|
# Health: http://127.0.0.1:8765/health
|
||||||
|
# Web UI: http://127.0.0.1:8765/mail
|
||||||
|
|
||||||
|
# Verify server health
|
||||||
|
curl http://127.0.0.1:8765/health
|
||||||
|
# Expected: {"status": "healthy"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Troubleshooting:**
|
||||||
|
- If port 8765 in use: `lsof -i :8765` then `kill <PID>`
|
||||||
|
- If server fails: Check `~/agent-mail.log` for errors
|
||||||
|
- If venv missing: See installation steps in `docs/AGENT_MAIL_QUICKSTART.md`
|
||||||
|
|
||||||
|
## Step 3: Configure All Workspaces (10 minutes)
|
||||||
|
|
||||||
|
Run setup script in each workspace to create `.envrc` files.
|
||||||
|
|
||||||
|
### 3a. Configure 5 beads repos
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Main beads repo
|
||||||
|
cd ~/src/beads
|
||||||
|
../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# cino/beads fork
|
||||||
|
cd ~/src/cino/beads
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# dave/beads fork
|
||||||
|
cd ~/src/dave/beads
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# emma/beads fork
|
||||||
|
cd ~/src/emma/beads
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# fred/beads fork (current repo)
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
./scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected .envrc content:**
|
||||||
|
```bash
|
||||||
|
# Agent Mail Configuration
|
||||||
|
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||||
|
export BEADS_AGENT_NAME=fred-beads-macbook # (varies by workspace/hostname)
|
||||||
|
export BEADS_PROJECT_ID=beads.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3b. Configure 5 vc repos
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Main vc repo (if standalone exists)
|
||||||
|
cd ~/src/vc
|
||||||
|
../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# cino/vc
|
||||||
|
cd ~/src/cino/vc
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# dave/vc
|
||||||
|
cd ~/src/dave/vc
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# fred/vc
|
||||||
|
cd ~/src/fred/vc
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# (One more standalone vc if it exists - adjust path as needed)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected PROJECT_ID:** `vc.dev`
|
||||||
|
|
||||||
|
### 3c. Configure 3 wyvern repos
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Main wyvern repo
|
||||||
|
cd ~/src/wyvern
|
||||||
|
../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# cino/wyvern
|
||||||
|
cd ~/src/cino/wyvern
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# fred/wyvern
|
||||||
|
cd ~/src/fred/wyvern
|
||||||
|
../../fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
direnv allow
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected PROJECT_ID:** `wyvern.dev`
|
||||||
|
|
||||||
|
## Step 4: Upgrade beads Binary Everywhere (5 minutes)
|
||||||
|
|
||||||
|
After version bump in Step 1, upgrade all workspaces to new version.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Wait for GitHub release to build (check https://github.com/steveyegge/beads/releases)
|
||||||
|
# Or build locally if impatient
|
||||||
|
|
||||||
|
# Option 1: Install from release (when ready)
|
||||||
|
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
|
||||||
|
|
||||||
|
# Option 2: Build locally and copy to all repos
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
go build -o bd ./cmd/bd
|
||||||
|
|
||||||
|
# Copy to other repos (example for beads repos)
|
||||||
|
cp bd ~/src/beads/bd
|
||||||
|
cp bd ~/src/cino/beads/bd
|
||||||
|
cp bd ~/src/dave/beads/bd
|
||||||
|
cp bd ~/src/emma/beads/bd
|
||||||
|
|
||||||
|
# Verify new version includes Agent Mail support
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
./bd --version
|
||||||
|
# Expected: bd version 0.23.0 (or whatever you bumped to)
|
||||||
|
|
||||||
|
./bd info --json | grep -i agent
|
||||||
|
# Expected: JSON output showing agent_mail config
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 5: Document Configuration (2 minutes)
|
||||||
|
|
||||||
|
Add Agent Mail config to each workspace's AGENTS.md (if applicable). Agents need these instructions before testing.
|
||||||
|
|
||||||
|
Example for vc repos:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/vc
|
||||||
|
|
||||||
|
# Add to AGENTS.md (or create if missing)
|
||||||
|
cat >> AGENTS.md <<'EOF'
|
||||||
|
|
||||||
|
## Agent Mail Configuration
|
||||||
|
|
||||||
|
This workspace participates in multi-agent coordination via MCP Agent Mail.
|
||||||
|
|
||||||
|
**Channel**: vc.dev (shared with all vc workers)
|
||||||
|
**Server**: http://127.0.0.1:8765
|
||||||
|
**Agent Name**: fred-vc-<hostname>
|
||||||
|
|
||||||
|
**Configuration**: Loaded automatically via `.envrc` (direnv)
|
||||||
|
|
||||||
|
**Tightly coupled workers**:
|
||||||
|
- ~/src/vc
|
||||||
|
- ~/src/cino/vc
|
||||||
|
- ~/src/dave/vc
|
||||||
|
- ~/src/fred/vc
|
||||||
|
- (one more standalone)
|
||||||
|
|
||||||
|
All vc workers coordinate issue reservations in real-time (<100ms latency).
|
||||||
|
|
||||||
|
**Cross-project coordination**: vc → beads bugs filed via git/PRs (not Agent Mail messaging)
|
||||||
|
|
||||||
|
See `docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md` for details.
|
||||||
|
EOF
|
||||||
|
```
|
||||||
|
|
||||||
|
Repeat for beads and wyvern workspaces with appropriate channel names.
|
||||||
|
|
||||||
|
## Step 6: Test Same-Channel Coordination (5 minutes)
|
||||||
|
|
||||||
|
Verify agents in same channel can see each other's reservations.
|
||||||
|
|
||||||
|
### 6a. Test vc.dev channel (2 vc repos)
|
||||||
|
|
||||||
|
**Terminal 1 - fred/vc:**
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/vc
|
||||||
|
|
||||||
|
# Verify env vars
|
||||||
|
echo $BEADS_PROJECT_ID # Expected: vc.dev
|
||||||
|
echo $BEADS_AGENT_NAME # Expected: fred-vc-<hostname>
|
||||||
|
|
||||||
|
# Create test issue and reserve it
|
||||||
|
bd create "Test Agent Mail coordination" -p 2 -t task
|
||||||
|
# Example output: bd-test42
|
||||||
|
|
||||||
|
bd update bd-test42 --status in_progress
|
||||||
|
# Expected: ✅ Reserved bd-test42 for fred-vc-macbook
|
||||||
|
```
|
||||||
|
|
||||||
|
**Terminal 2 - cino/vc:**
|
||||||
|
```bash
|
||||||
|
cd ~/src/cino/vc
|
||||||
|
|
||||||
|
# Verify env vars
|
||||||
|
echo $BEADS_PROJECT_ID # Expected: vc.dev
|
||||||
|
echo $BEADS_AGENT_NAME # Expected: cino-vc-<hostname>
|
||||||
|
|
||||||
|
# Try to claim same issue
|
||||||
|
bd update bd-test42 --status in_progress
|
||||||
|
# Expected: ❌ Error - bd-test42 already reserved by fred-vc-macbook
|
||||||
|
```
|
||||||
|
|
||||||
|
**Success!** Collision prevented across different repos in same channel.
|
||||||
|
|
||||||
|
**Terminal 1 - Cleanup:**
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/vc
|
||||||
|
bd close bd-test42 "Test complete"
|
||||||
|
# Expected: ✅ Reservation released
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6b. Test channel isolation
|
||||||
|
|
||||||
|
Verify agents in different channels DON'T interfere.
|
||||||
|
|
||||||
|
**Terminal 1 - fred/beads (beads.dev):**
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
bd create "Test channel isolation" -p 2
|
||||||
|
# Example: Created bd-test1
|
||||||
|
|
||||||
|
bd update bd-test1 --status in_progress
|
||||||
|
# Expected: Success
|
||||||
|
```
|
||||||
|
|
||||||
|
**Terminal 2 - fred/vc (vc.dev):**
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/vc
|
||||||
|
bd create "Test channel isolation" -p 2
|
||||||
|
# Example: Created bd-test2
|
||||||
|
|
||||||
|
bd update bd-test2 --status in_progress
|
||||||
|
# Expected: Success (no conflict - different channel!)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Both reservations succeed** because they're in different channels.
|
||||||
|
|
||||||
|
## Step 7: Monitor All Channels (2 minutes)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
|
||||||
|
# Check overall status
|
||||||
|
./scripts/agent-mail-status.sh
|
||||||
|
|
||||||
|
# Expected output:
|
||||||
|
# === Agent Mail Status ===
|
||||||
|
# Server Process: ✅ Running (PID: 12345)
|
||||||
|
# Server Health: ✅ OK
|
||||||
|
# Active Projects:
|
||||||
|
# • beads.dev
|
||||||
|
# • vc.dev
|
||||||
|
# • wyvern.dev
|
||||||
|
# Active File Reservations:
|
||||||
|
# (list of current reservations across all channels)
|
||||||
|
|
||||||
|
# Open Web UI for visual monitoring
|
||||||
|
open http://127.0.0.1:8765/mail
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 8: Make Server Auto-Start on Reboot (Optional, 5 minutes)
|
||||||
|
|
||||||
|
Use macOS launchd for automatic server startup.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create launchd plist
|
||||||
|
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>com.user.mcp-agent-mail</string>
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
|
||||||
|
<string>-m</string>
|
||||||
|
<string>mcp_agent_mail.cli</string>
|
||||||
|
<string>serve-http</string>
|
||||||
|
<string>--host</string>
|
||||||
|
<string>127.0.0.1</string>
|
||||||
|
<string>--port</string>
|
||||||
|
<string>8765</string>
|
||||||
|
</array>
|
||||||
|
<key>WorkingDirectory</key>
|
||||||
|
<string>/Users/stevey/src/mcp_agent_mail</string>
|
||||||
|
<key>StandardOutPath</key>
|
||||||
|
<string>/Users/stevey/agent-mail.log</string>
|
||||||
|
<key>StandardErrorPath</key>
|
||||||
|
<string>/Users/stevey/agent-mail-error.log</string>
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
<key>KeepAlive</key>
|
||||||
|
<true/>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Load service
|
||||||
|
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||||
|
|
||||||
|
# Verify loaded
|
||||||
|
launchctl list | grep mcp-agent-mail
|
||||||
|
# Expected: Shows PID and status
|
||||||
|
|
||||||
|
# Test restart
|
||||||
|
sudo reboot # (or just log out/in)
|
||||||
|
# After reboot, verify server auto-started:
|
||||||
|
curl http://127.0.0.1:8765/health
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 9: Auto-Start on Reboot (Optional, 5 minutes)
|
||||||
|
|
||||||
|
Use macOS launchd for automatic server startup.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create launchd plist
|
||||||
|
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>com.user.mcp-agent-mail</string>
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
|
||||||
|
<string>-m</string>
|
||||||
|
<string>mcp_agent_mail.cli</string>
|
||||||
|
<string>serve-http</string>
|
||||||
|
<string>--host</string>
|
||||||
|
<string>127.0.0.1</string>
|
||||||
|
<string>--port</string>
|
||||||
|
<string>8765</string>
|
||||||
|
</array>
|
||||||
|
<key>WorkingDirectory</key>
|
||||||
|
<string>/Users/stevey/src/mcp_agent_mail</string>
|
||||||
|
<key>StandardOutPath</key>
|
||||||
|
<string>/Users/stevey/agent-mail.log</string>
|
||||||
|
<key>StandardErrorPath</key>
|
||||||
|
<string>/Users/stevey/agent-mail-error.log</string>
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
<key>KeepAlive</key>
|
||||||
|
<true/>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Load service
|
||||||
|
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||||
|
|
||||||
|
# Verify loaded
|
||||||
|
launchctl list | grep mcp-agent-mail
|
||||||
|
# Expected: Shows PID and status
|
||||||
|
|
||||||
|
# Test restart
|
||||||
|
sudo reboot # (or just log out/in)
|
||||||
|
# After reboot, verify server auto-started:
|
||||||
|
curl http://127.0.0.1:8765/health
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 10: Verification Checklist
|
||||||
|
|
||||||
|
Run through this checklist to confirm deployment success.
|
||||||
|
|
||||||
|
### ✅ Server Health
|
||||||
|
- [ ] `curl http://127.0.0.1:8765/health` returns `{"status": "healthy"}`
|
||||||
|
- [ ] PID file exists: `cat ~/agent-mail.pid`
|
||||||
|
- [ ] Process running: `ps -p $(cat ~/agent-mail.pid)`
|
||||||
|
- [ ] Logs clean: `tail ~/agent-mail.log` (no errors)
|
||||||
|
|
||||||
|
### ✅ Workspace Configuration
|
||||||
|
- [ ] All 13 workspaces have `.envrc` files
|
||||||
|
- [ ] All `.envrc` files have correct `BEADS_PROJECT_ID`:
|
||||||
|
- 5 beads repos → `beads.dev`
|
||||||
|
- 5 vc repos → `vc.dev`
|
||||||
|
- 3 wyvern repos → `wyvern.dev`
|
||||||
|
- [ ] All workspaces allowed: `direnv allow` in each
|
||||||
|
- [ ] Env vars load automatically when `cd`-ing into workspace
|
||||||
|
|
||||||
|
### ✅ beads Binary
|
||||||
|
- [ ] All workspaces using new version with Agent Mail support
|
||||||
|
- [ ] `bd --version` shows 0.23.0+ everywhere
|
||||||
|
- [ ] `bd info --json | grep agent_mail` shows config
|
||||||
|
|
||||||
|
### ✅ Multi-Agent Coordination
|
||||||
|
- [ ] Same channel: Reservation conflict works (tested in Step 6a)
|
||||||
|
- [ ] Different channels: No interference (tested in Step 6b)
|
||||||
|
- [ ] Web UI shows all 3 channels: http://127.0.0.1:8765/mail
|
||||||
|
- [ ] Status script works: `./scripts/agent-mail-status.sh`
|
||||||
|
|
||||||
|
### ✅ Persistence
|
||||||
|
- [ ] Server survives reboot (if launchd configured in Step 8)
|
||||||
|
- [ ] Reservations cleared on server restart (expected behavior)
|
||||||
|
- [ ] Agents re-register automatically after server restart
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
### Issue: direnv not loading .envrc
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
echo $BEADS_PROJECT_ID
|
||||||
|
# (empty output)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
```bash
|
||||||
|
# Check direnv hook installed
|
||||||
|
grep direnv ~/.zshrc
|
||||||
|
# Should see: eval "$(direnv hook zsh)"
|
||||||
|
|
||||||
|
# If missing, add it
|
||||||
|
echo 'eval "$(direnv hook zsh)"' >> ~/.zshrc
|
||||||
|
source ~/.zshrc
|
||||||
|
|
||||||
|
# Allow .envrc
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
direnv allow
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: Agent names collide
|
||||||
|
|
||||||
|
**Symptoms:** Two workspaces use same `BEADS_AGENT_NAME`
|
||||||
|
|
||||||
|
**Fix:** Edit `.envrc` to make agent names unique:
|
||||||
|
```bash
|
||||||
|
# Bad (collision!)
|
||||||
|
export BEADS_AGENT_NAME=fred-beads-macbook # Same in fred/beads and fred/vc
|
||||||
|
|
||||||
|
# Good (unique)
|
||||||
|
export BEADS_AGENT_NAME=fred-beads-macbook # In fred/beads
|
||||||
|
export BEADS_AGENT_NAME=fred-vc-macbook # In fred/vc
|
||||||
|
```
|
||||||
|
|
||||||
|
The `setup-agent-mail-workspace.sh` script already handles this by including workspace name.
|
||||||
|
|
||||||
|
### Issue: Server not accessible
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
```bash
|
||||||
|
bd update bd-42 --status in_progress
|
||||||
|
# WARN Agent Mail unavailable, falling back to git-only mode
|
||||||
|
```
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
```bash
|
||||||
|
# Check server health
|
||||||
|
curl http://127.0.0.1:8765/health
|
||||||
|
# If unreachable, restart server:
|
||||||
|
./scripts/stop-agent-mail-server.sh
|
||||||
|
./scripts/start-agent-mail-server.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue: Old reservations stuck
|
||||||
|
|
||||||
|
**Symptoms:** Agent crashed but reservation persists
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
```bash
|
||||||
|
# Option 1: Release via API
|
||||||
|
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-stuck
|
||||||
|
|
||||||
|
# Option 2: Restart server (clears all)
|
||||||
|
./scripts/stop-agent-mail-server.sh
|
||||||
|
./scripts/start-agent-mail-server.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
## Maintenance
|
||||||
|
|
||||||
|
### Daily Operations
|
||||||
|
|
||||||
|
**Start/stop server manually:**
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
./scripts/start-agent-mail-server.sh
|
||||||
|
./scripts/stop-agent-mail-server.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
**Check status:**
|
||||||
|
```bash
|
||||||
|
./scripts/agent-mail-status.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
**View logs:**
|
||||||
|
```bash
|
||||||
|
tail -f ~/agent-mail.log
|
||||||
|
```
|
||||||
|
|
||||||
|
**Monitor Web UI:**
|
||||||
|
```bash
|
||||||
|
open http://127.0.0.1:8765/mail
|
||||||
|
```
|
||||||
|
|
||||||
|
### Upgrading beads
|
||||||
|
|
||||||
|
When you bump beads version in the future:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd ~/src/fred/beads
|
||||||
|
|
||||||
|
# Bump version
|
||||||
|
./scripts/bump-version.sh 0.24.0 --commit
|
||||||
|
git push origin main
|
||||||
|
git push origin v0.24.0
|
||||||
|
|
||||||
|
# Wait for release, then upgrade all workspaces
|
||||||
|
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
|
||||||
|
|
||||||
|
# Or rebuild locally and distribute
|
||||||
|
go build -o bd ./cmd/bd
|
||||||
|
# ... copy to other repos
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding New Workspaces
|
||||||
|
|
||||||
|
To add a new workspace to Agent Mail coordination:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Example: Adding ~/src/gina/beads
|
||||||
|
cd ~/src/gina/beads
|
||||||
|
|
||||||
|
# Run setup script
|
||||||
|
~/src/fred/beads/scripts/setup-agent-mail-workspace.sh .
|
||||||
|
|
||||||
|
# Allow direnv
|
||||||
|
direnv allow
|
||||||
|
|
||||||
|
# Verify configuration
|
||||||
|
echo $BEADS_PROJECT_ID
|
||||||
|
# Expected: beads.dev (or vc.dev/wyvern.dev)
|
||||||
|
|
||||||
|
# Test reservation
|
||||||
|
bd ready | head -1 | xargs -I {} bd update {} --status in_progress
|
||||||
|
# Should work immediately
|
||||||
|
```
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
You've successfully deployed Agent Mail when:
|
||||||
|
|
||||||
|
1. ✅ **Server running**: `curl http://127.0.0.1:8765/health` returns healthy
|
||||||
|
2. ✅ **All workspaces configured**: 13 `.envrc` files created and allowed
|
||||||
|
3. ✅ **Three channels active**: beads.dev, vc.dev, wyvern.dev visible in Web UI
|
||||||
|
4. ✅ **Coordination works**: Reservation conflict test passes (Step 6a)
|
||||||
|
5. ✅ **Isolation works**: Different channels don't interfere (Step 6b)
|
||||||
|
6. ✅ **Monitoring works**: Status script shows all active projects
|
||||||
|
7. ✅ **Auto-start works**: Server survives reboot (if Step 8 completed)
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
After successful deployment:
|
||||||
|
|
||||||
|
1. **Start using bd normally** - Agent Mail coordination happens automatically
|
||||||
|
2. **Monitor reservations** via Web UI during concurrent work
|
||||||
|
3. **File issues** for any coordination bugs (rare with hash-based IDs)
|
||||||
|
4. **Consider MCP integration** for Claude Desktop (see `docs/AGENT_MAIL_QUICKSTART.md`)
|
||||||
|
5. **Wait for cross-project messaging** (planned in Agent Mail roadmap)
|
||||||
|
|
||||||
|
## Reference
|
||||||
|
|
||||||
|
- **Main Guide**: [AGENT_MAIL_MULTI_WORKSPACE_SETUP.md](AGENT_MAIL_MULTI_WORKSPACE_SETUP.md)
|
||||||
|
- **Quick Start**: [AGENT_MAIL_QUICKSTART.md](AGENT_MAIL_QUICKSTART.md)
|
||||||
|
- **Architecture**: [AGENT_MAIL.md](AGENT_MAIL.md)
|
||||||
|
- **ADR**: [adr/002-agent-mail-integration.md](../adr/002-agent-mail-integration.md)
|
||||||
|
|
||||||
|
## Timeline Estimate
|
||||||
|
|
||||||
|
- **Step 1** (Version bump): 5 minutes
|
||||||
|
- **Step 2** (Start server): 2 minutes
|
||||||
|
- **Step 3** (Configure 13 workspaces): 10 minutes
|
||||||
|
- **Step 4** (Upgrade binaries): 5 minutes
|
||||||
|
- **Step 5** (Document): 2 minutes
|
||||||
|
- **Step 6** (Same-channel test): 5 minutes
|
||||||
|
- **Step 7** (Channel isolation test): 5 minutes
|
||||||
|
- **Step 8** (Monitor): 2 minutes
|
||||||
|
- **Step 9** (Auto-start, optional): 5 minutes
|
||||||
|
- **Step 10** (Verify checklist): 5 minutes
|
||||||
|
|
||||||
|
**Total: ~46 minutes** (or ~41 minutes if skipping auto-start)
|
||||||
|
|
||||||
|
You're ready to deploy! 🚀
|
||||||
345
docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md
Normal file
345
docs/AGENT_MAIL_MULTI_WORKSPACE_SETUP.md
Normal file
@@ -0,0 +1,345 @@
|
|||||||
|
# Multi-Workspace Agent Mail Setup
|
||||||
|
|
||||||
|
Guide for running Agent Mail across multiple beads repositories.
|
||||||
|
|
||||||
|
## Service Management
|
||||||
|
|
||||||
|
### Start Agent Mail Server (One Instance for All Projects)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Start in background with nohup
|
||||||
|
cd ~/src/mcp_agent_mail
|
||||||
|
source .venv/bin/activate
|
||||||
|
nohup python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765 > ~/agent-mail.log 2>&1 &
|
||||||
|
echo $! > ~/agent-mail.pid
|
||||||
|
```
|
||||||
|
|
||||||
|
### Check Server Status
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Health check
|
||||||
|
curl http://127.0.0.1:8765/health
|
||||||
|
|
||||||
|
# View logs
|
||||||
|
tail -f ~/agent-mail.log
|
||||||
|
|
||||||
|
# Check process
|
||||||
|
ps aux | grep mcp_agent_mail
|
||||||
|
# Or use saved PID
|
||||||
|
ps -p $(cat ~/agent-mail.pid) || echo "Server not running"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Restart Server
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Kill old server
|
||||||
|
kill $(cat ~/agent-mail.pid) 2>/dev/null || pkill -f mcp_agent_mail
|
||||||
|
|
||||||
|
# Start fresh
|
||||||
|
cd ~/src/mcp_agent_mail
|
||||||
|
source .venv/bin/activate
|
||||||
|
nohup python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765 > ~/agent-mail.log 2>&1 &
|
||||||
|
echo $! > ~/agent-mail.pid
|
||||||
|
```
|
||||||
|
|
||||||
|
### Auto-Start on Reboot (macOS launchd)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||||
|
cat > ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist <<'EOF'
|
||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||||
|
<plist version="1.0">
|
||||||
|
<dict>
|
||||||
|
<key>Label</key>
|
||||||
|
<string>com.user.mcp-agent-mail</string>
|
||||||
|
<key>ProgramArguments</key>
|
||||||
|
<array>
|
||||||
|
<string>/Users/stevey/src/mcp_agent_mail/.venv/bin/python</string>
|
||||||
|
<string>-m</string>
|
||||||
|
<string>mcp_agent_mail.cli</string>
|
||||||
|
<string>serve-http</string>
|
||||||
|
<string>--host</string>
|
||||||
|
<string>127.0.0.1</string>
|
||||||
|
<string>--port</string>
|
||||||
|
<string>8765</string>
|
||||||
|
</array>
|
||||||
|
<key>WorkingDirectory</key>
|
||||||
|
<string>/Users/stevey/src/mcp_agent_mail</string>
|
||||||
|
<key>StandardOutPath</key>
|
||||||
|
<string>/Users/stevey/agent-mail.log</string>
|
||||||
|
<key>StandardErrorPath</key>
|
||||||
|
<string>/Users/stevey/agent-mail-error.log</string>
|
||||||
|
<key>RunAtLoad</key>
|
||||||
|
<true/>
|
||||||
|
<key>KeepAlive</key>
|
||||||
|
<true/>
|
||||||
|
</dict>
|
||||||
|
</plist>
|
||||||
|
EOF
|
||||||
|
|
||||||
|
# Load service
|
||||||
|
launchctl load ~/Library/LaunchAgents/com.user.mcp-agent-mail.plist
|
||||||
|
|
||||||
|
# Check status
|
||||||
|
launchctl list | grep mcp-agent-mail
|
||||||
|
```
|
||||||
|
|
||||||
|
## Project Configuration Strategy
|
||||||
|
|
||||||
|
**Three team channels** for tightly-coupled workers:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
beads.dev → All beads workers (5 repos)
|
||||||
|
vc.dev → All vc workers (5 repos)
|
||||||
|
wyvern.dev → All wyvern workers (3 repos)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Why this design:**
|
||||||
|
- Each team's workers are tightly coupled and need frequent coordination
|
||||||
|
- Simple namespace strings (no filesystem paths required)
|
||||||
|
- Usenet-style naming for clarity
|
||||||
|
- Cross-project filing handled via git/PRs for now (until Agent Mail adds cross-project messaging)
|
||||||
|
|
||||||
|
### Configuration by Workspace
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# All beads repos use same project
|
||||||
|
~/src/beads → BEADS_PROJECT_ID=beads.dev
|
||||||
|
~/src/cino/beads → BEADS_PROJECT_ID=beads.dev
|
||||||
|
~/src/dave/beads → BEADS_PROJECT_ID=beads.dev
|
||||||
|
~/src/emma/beads → BEADS_PROJECT_ID=beads.dev
|
||||||
|
~/src/fred/beads → BEADS_PROJECT_ID=beads.dev
|
||||||
|
|
||||||
|
# All vc repos use same project
|
||||||
|
~/src/cino/vc → BEADS_PROJECT_ID=vc.dev
|
||||||
|
~/src/dave/vc → BEADS_PROJECT_ID=vc.dev
|
||||||
|
~/src/fred/vc → BEADS_PROJECT_ID=vc.dev
|
||||||
|
~/src/vc → BEADS_PROJECT_ID=vc.dev
|
||||||
|
(standalone at ~/src/vc if exists)
|
||||||
|
|
||||||
|
# All wyvern repos use same project
|
||||||
|
~/src/cino/wyvern → BEADS_PROJECT_ID=wyvern.dev
|
||||||
|
~/src/fred/wyvern → BEADS_PROJECT_ID=wyvern.dev
|
||||||
|
~/src/wyvern → BEADS_PROJECT_ID=wyvern.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
## Per-Directory Configuration
|
||||||
|
|
||||||
|
Create `.envrc` or `.env` file in each workspace:
|
||||||
|
|
||||||
|
### Example: ~/src/fred/vc/.envrc
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Agent Mail Configuration for fred's vc
|
||||||
|
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||||
|
export BEADS_AGENT_NAME=fred-vc-$(hostname)
|
||||||
|
export BEADS_PROJECT_ID=vc.dev
|
||||||
|
|
||||||
|
# Load with direnv
|
||||||
|
# Install direnv: brew install direnv
|
||||||
|
# Then: direnv allow
|
||||||
|
```
|
||||||
|
|
||||||
|
### Example: ~/src/cino/beads/.envrc
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Agent Mail Configuration for cino's beads fork
|
||||||
|
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||||
|
export BEADS_AGENT_NAME=cino-beads-$(hostname)
|
||||||
|
export BEADS_PROJECT_ID=beads.dev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quick Setup Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# setup-agent-mail.sh - Run in each workspace
|
||||||
|
|
||||||
|
WORKSPACE=$(pwd)
|
||||||
|
WORKSPACE_NAME=$(basename $WORKSPACE)
|
||||||
|
PARENT=$(basename $(dirname $WORKSPACE))
|
||||||
|
|
||||||
|
# Determine project ID based on coupling
|
||||||
|
case "$WORKSPACE_NAME" in
|
||||||
|
vc|wyvern)
|
||||||
|
# Tightly coupled - use parent coordination project
|
||||||
|
PROJECT_ID="/Users/stevey/src/${PARENT}/coordination"
|
||||||
|
;;
|
||||||
|
beads)
|
||||||
|
# Loosely coupled - use workspace as project
|
||||||
|
PROJECT_ID="$WORKSPACE"
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
# Default - use workspace
|
||||||
|
PROJECT_ID="$WORKSPACE"
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
|
||||||
|
cat > .envrc <<EOF
|
||||||
|
# Agent Mail Configuration
|
||||||
|
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||||
|
export BEADS_AGENT_NAME=${PARENT}-${WORKSPACE_NAME}-\$(hostname)
|
||||||
|
export BEADS_PROJECT_ID=$PROJECT_ID
|
||||||
|
EOF
|
||||||
|
|
||||||
|
echo "Created .envrc with PROJECT_ID=$PROJECT_ID"
|
||||||
|
echo "Run: direnv allow"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Project Relationship Matrix
|
||||||
|
|
||||||
|
| Workspace | Project Channel | Agent Name | Can Message |
|
||||||
|
|-----------|----------------|------------|-------------|
|
||||||
|
| ~/src/beads | beads.dev | main-beads-* | All beads workers ✅ |
|
||||||
|
| ~/src/cino/beads | beads.dev | cino-beads-* | All beads workers ✅ |
|
||||||
|
| ~/src/dave/beads | beads.dev | dave-beads-* | All beads workers ✅ |
|
||||||
|
| ~/src/emma/beads | beads.dev | emma-beads-* | All beads workers ✅ |
|
||||||
|
| ~/src/fred/beads | beads.dev | fred-beads-* | All beads workers ✅ |
|
||||||
|
| ~/src/cino/vc | vc.dev | cino-vc-* | All vc workers ✅ |
|
||||||
|
| ~/src/dave/vc | vc.dev | dave-vc-* | All vc workers ✅ |
|
||||||
|
| ~/src/fred/vc | vc.dev | fred-vc-* | All vc workers ✅ |
|
||||||
|
| ~/src/vc | vc.dev | main-vc-* | All vc workers ✅ |
|
||||||
|
| ~/src/cino/wyvern | wyvern.dev | cino-wyvern-* | All wyvern workers ✅ |
|
||||||
|
| ~/src/fred/wyvern | wyvern.dev | fred-wyvern-* | All wyvern workers ✅ |
|
||||||
|
| ~/src/wyvern | wyvern.dev | main-wyvern-* | All wyvern workers ✅ |
|
||||||
|
|
||||||
|
## Monitoring Multiple Projects
|
||||||
|
|
||||||
|
### Web UI
|
||||||
|
|
||||||
|
View all projects and agents:
|
||||||
|
```bash
|
||||||
|
open http://127.0.0.1:8765/mail
|
||||||
|
```
|
||||||
|
|
||||||
|
### API Queries
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# List all projects
|
||||||
|
curl http://127.0.0.1:8765/api/projects | jq
|
||||||
|
|
||||||
|
# View agents in specific project
|
||||||
|
curl "http://127.0.0.1:8765/api/projects/$(urlencode /Users/stevey/src/fred/coordination)/agents" | jq
|
||||||
|
|
||||||
|
# Check file reservations across all projects
|
||||||
|
curl http://127.0.0.1:8765/api/file_reservations | jq
|
||||||
|
```
|
||||||
|
|
||||||
|
### Unified Dashboard Script
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
# agent-mail-status.sh - View all active agents and reservations
|
||||||
|
|
||||||
|
echo "=== Agent Mail Status ==="
|
||||||
|
echo
|
||||||
|
|
||||||
|
echo "Server Health:"
|
||||||
|
curl -s http://127.0.0.1:8765/health | jq -r '.status // "UNREACHABLE"'
|
||||||
|
echo
|
||||||
|
|
||||||
|
echo "Active Projects:"
|
||||||
|
curl -s http://127.0.0.1:8765/api/projects | jq -r '.[] | "\(.slug) - \(.human_key)"'
|
||||||
|
echo
|
||||||
|
|
||||||
|
echo "Active Reservations:"
|
||||||
|
curl -s http://127.0.0.1:8765/api/file_reservations | jq -r '.[] | "\(.agent_name) → \(.resource_id) (\(.project_id))"'
|
||||||
|
```
|
||||||
|
|
||||||
|
## Future: Cross-Project Messaging
|
||||||
|
|
||||||
|
When Agent Mail adds cross-project support (planned), you'll be able to:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Send message from fred/vc to cino/vc
|
||||||
|
bd agent-mail send \
|
||||||
|
--from fred-vc \
|
||||||
|
--to cino-vc \
|
||||||
|
--to-project /Users/stevey/src/cino/coordination \
|
||||||
|
--subject "API changes in shared library"
|
||||||
|
```
|
||||||
|
|
||||||
|
For now, use git commits/PRs for cross-project coordination.
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Problem: Different agents step on each other
|
||||||
|
|
||||||
|
**Symptom:** Two agents in same project both claim same issue
|
||||||
|
|
||||||
|
**Cause:** Agents using different `BEADS_AGENT_NAME` but same project
|
||||||
|
|
||||||
|
**Fix:** Ensure unique agent names per workspace:
|
||||||
|
```bash
|
||||||
|
export BEADS_AGENT_NAME=$(whoami)-$(basename $PWD)-$(hostname)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Problem: Agents can't see each other
|
||||||
|
|
||||||
|
**Symptom:** Agent sends message but recipient doesn't receive it
|
||||||
|
|
||||||
|
**Cause:** Agents in different `BEADS_PROJECT_ID`
|
||||||
|
|
||||||
|
**Fix:** Verify both agents use same project ID:
|
||||||
|
```bash
|
||||||
|
# In each workspace
|
||||||
|
echo $BEADS_PROJECT_ID
|
||||||
|
```
|
||||||
|
|
||||||
|
### Problem: Reservation persists after crash
|
||||||
|
|
||||||
|
**Symptom:** Issue stays reserved after agent died
|
||||||
|
|
||||||
|
**Fix:**
|
||||||
|
```bash
|
||||||
|
# Release via API
|
||||||
|
curl -X DELETE http://127.0.0.1:8765/api/reservations/bd-stuck-issue
|
||||||
|
|
||||||
|
# Or restart server (clears all)
|
||||||
|
kill $(cat ~/agent-mail.pid)
|
||||||
|
cd ~/src/mcp_agent_mail
|
||||||
|
source .venv/bin/activate
|
||||||
|
nohup python -m mcp_agent_mail.cli serve-http --host 127.0.0.1 --port 8765 > ~/agent-mail.log 2>&1 &
|
||||||
|
echo $! > ~/agent-mail.pid
|
||||||
|
```
|
||||||
|
|
||||||
|
## Best Practices
|
||||||
|
|
||||||
|
1. **Use direnv for automatic env loading**
|
||||||
|
```bash
|
||||||
|
brew install direnv
|
||||||
|
# Add to ~/.zshrc: eval "$(direnv hook zsh)"
|
||||||
|
# Then create .envrc in each workspace
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Descriptive agent names**
|
||||||
|
```bash
|
||||||
|
# Bad: export BEADS_AGENT_NAME=agent1
|
||||||
|
# Good: export BEADS_AGENT_NAME=fred-vc-macbook
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Monitor server logs**
|
||||||
|
```bash
|
||||||
|
tail -f ~/agent-mail.log
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Health check in scripts**
|
||||||
|
```bash
|
||||||
|
if ! curl -sf http://127.0.0.1:8765/health > /dev/null; then
|
||||||
|
echo "WARNING: Agent Mail unavailable (falling back to git-only)"
|
||||||
|
fi
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Document project relationships**
|
||||||
|
- Keep this file updated when adding workspaces
|
||||||
|
- Add comments in .envrc explaining project coupling
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
- **One server** handles all projects (lightweight HTTP API)
|
||||||
|
- **Project ID = namespace** for agent isolation
|
||||||
|
- **Tight coupling** → shared project (vc + wyvern)
|
||||||
|
- **Loose coupling** → separate projects (beads forks)
|
||||||
|
- **Auto-restart** via launchd recommended
|
||||||
|
- **Per-directory .envrc** for automatic config loading
|
||||||
70
scripts/agent-mail-status.sh
Executable file
70
scripts/agent-mail-status.sh
Executable file
@@ -0,0 +1,70 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# View Agent Mail server status and active projects
|
||||||
|
# Usage: ./agent-mail-status.sh
|
||||||
|
|
||||||
|
PORT="${AGENT_MAIL_PORT:-8765}"
|
||||||
|
URL="http://127.0.0.1:$PORT"
|
||||||
|
PID_FILE="${AGENT_MAIL_PID:-$HOME/agent-mail.pid}"
|
||||||
|
|
||||||
|
echo "=== Agent Mail Status ==="
|
||||||
|
echo ""
|
||||||
|
|
||||||
|
# Check PID file
|
||||||
|
if [[ -f "$PID_FILE" ]]; then
|
||||||
|
PID=$(cat "$PID_FILE")
|
||||||
|
if ps -p "$PID" > /dev/null 2>&1; then
|
||||||
|
echo "Server Process: ✅ Running (PID: $PID)"
|
||||||
|
else
|
||||||
|
echo "Server Process: ⚠️ Stale PID file (process $PID not found)"
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo "Server Process: ⚠️ No PID file found"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check health endpoint
|
||||||
|
echo ""
|
||||||
|
echo "Server Health:"
|
||||||
|
if HEALTH=$(curl -sf "$URL/health" 2>/dev/null); then
|
||||||
|
echo " ✅ $(echo $HEALTH | jq -r '.status // "OK"')"
|
||||||
|
echo " URL: $URL"
|
||||||
|
else
|
||||||
|
echo " ❌ UNREACHABLE at $URL"
|
||||||
|
echo ""
|
||||||
|
echo "Start server with:"
|
||||||
|
echo " ./scripts/start-agent-mail-server.sh"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# List projects
|
||||||
|
echo ""
|
||||||
|
echo "Active Projects:"
|
||||||
|
if PROJECTS=$(curl -sf "$URL/api/projects" 2>/dev/null); then
|
||||||
|
if [[ $(echo "$PROJECTS" | jq -r '. | length') -eq 0 ]]; then
|
||||||
|
echo " (none yet)"
|
||||||
|
else
|
||||||
|
echo "$PROJECTS" | jq -r '.[] | " • \(.slug)\n Path: \(.human_key)"'
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo " (failed to fetch)"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# List reservations
|
||||||
|
echo ""
|
||||||
|
echo "Active File Reservations:"
|
||||||
|
if RESERVATIONS=$(curl -sf "$URL/api/file_reservations" 2>/dev/null); then
|
||||||
|
if [[ $(echo "$RESERVATIONS" | jq -r '. | length') -eq 0 ]]; then
|
||||||
|
echo " (none)"
|
||||||
|
else
|
||||||
|
echo "$RESERVATIONS" | jq -r '.[] | " • \(.agent_name) → \(.resource_id)\n Project: \(.project_id)\n Expires: \(.expires_at)"'
|
||||||
|
fi
|
||||||
|
else
|
||||||
|
echo " (failed to fetch)"
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo ""
|
||||||
|
echo "Web UI: $URL/mail"
|
||||||
|
echo ""
|
||||||
|
echo "Commands:"
|
||||||
|
echo " Start: ./scripts/start-agent-mail-server.sh"
|
||||||
|
echo " Stop: ./scripts/stop-agent-mail-server.sh"
|
||||||
|
echo " Logs: tail -f $HOME/agent-mail.log"
|
||||||
67
scripts/setup-agent-mail-workspace.sh
Executable file
67
scripts/setup-agent-mail-workspace.sh
Executable file
@@ -0,0 +1,67 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Setup Agent Mail configuration for a beads workspace
|
||||||
|
# Usage: ./setup-agent-mail-workspace.sh [workspace-path]
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
WORKSPACE="${1:-$(pwd)}"
|
||||||
|
cd "$WORKSPACE"
|
||||||
|
|
||||||
|
WORKSPACE_NAME=$(basename "$WORKSPACE")
|
||||||
|
PARENT=$(basename $(dirname "$WORKSPACE"))
|
||||||
|
HOSTNAME=$(hostname -s)
|
||||||
|
|
||||||
|
# Determine project ID based on workspace type
|
||||||
|
determine_project_id() {
|
||||||
|
local ws_name="$1"
|
||||||
|
|
||||||
|
case "$ws_name" in
|
||||||
|
beads)
|
||||||
|
echo "beads.dev"
|
||||||
|
;;
|
||||||
|
vc)
|
||||||
|
echo "vc.dev"
|
||||||
|
;;
|
||||||
|
wyvern)
|
||||||
|
echo "wyvern.dev"
|
||||||
|
;;
|
||||||
|
*)
|
||||||
|
echo "unknown.dev"
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
}
|
||||||
|
|
||||||
|
PROJECT_ID=$(determine_project_id "$WORKSPACE_NAME")
|
||||||
|
AGENT_NAME="${PARENT}-${WORKSPACE_NAME}-${HOSTNAME}"
|
||||||
|
|
||||||
|
# Create .envrc for direnv
|
||||||
|
cat > .envrc <<EOF
|
||||||
|
# Agent Mail Configuration
|
||||||
|
# Generated: $(date)
|
||||||
|
# Workspace: $WORKSPACE
|
||||||
|
# Coupling: $(basename "$PROJECT_ID")
|
||||||
|
|
||||||
|
export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765
|
||||||
|
export BEADS_AGENT_NAME=$AGENT_NAME
|
||||||
|
export BEADS_PROJECT_ID=$PROJECT_ID
|
||||||
|
|
||||||
|
# Optional: Uncomment for debugging
|
||||||
|
# export BEADS_AGENT_MAIL_DEBUG=1
|
||||||
|
EOF
|
||||||
|
|
||||||
|
echo "✅ Created .envrc in $WORKSPACE"
|
||||||
|
echo ""
|
||||||
|
echo "Configuration:"
|
||||||
|
echo " BEADS_AGENT_MAIL_URL: http://127.0.0.1:8765"
|
||||||
|
echo " BEADS_AGENT_NAME: $AGENT_NAME"
|
||||||
|
echo " BEADS_PROJECT_ID: $PROJECT_ID"
|
||||||
|
echo ""
|
||||||
|
echo "Next steps:"
|
||||||
|
echo " 1. Review .envrc and adjust if needed"
|
||||||
|
echo " 2. Run: direnv allow"
|
||||||
|
echo " 3. Test: bd info | grep -i agent"
|
||||||
|
echo ""
|
||||||
|
echo "To install direnv:"
|
||||||
|
echo " brew install direnv"
|
||||||
|
echo " echo 'eval \"\$(direnv hook zsh)\"' >> ~/.zshrc"
|
||||||
|
echo " source ~/.zshrc"
|
||||||
86
scripts/start-agent-mail-server.sh
Executable file
86
scripts/start-agent-mail-server.sh
Executable file
@@ -0,0 +1,86 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Start Agent Mail server in background
|
||||||
|
# Usage: ./start-agent-mail-server.sh
|
||||||
|
|
||||||
|
set -e
|
||||||
|
|
||||||
|
AGENT_MAIL_DIR="${AGENT_MAIL_DIR:-$HOME/src/mcp_agent_mail}"
|
||||||
|
LOG_FILE="${AGENT_MAIL_LOG:-$HOME/agent-mail.log}"
|
||||||
|
PID_FILE="${AGENT_MAIL_PID:-$HOME/agent-mail.pid}"
|
||||||
|
PORT="${AGENT_MAIL_PORT:-8765}"
|
||||||
|
|
||||||
|
# Check if server already running
|
||||||
|
if [[ -f "$PID_FILE" ]]; then
|
||||||
|
PID=$(cat "$PID_FILE")
|
||||||
|
if ps -p "$PID" > /dev/null 2>&1; then
|
||||||
|
echo "⚠️ Agent Mail server already running (PID: $PID)"
|
||||||
|
echo " Stop it first: kill $PID"
|
||||||
|
exit 1
|
||||||
|
else
|
||||||
|
echo "🗑️ Removing stale PID file"
|
||||||
|
rm -f "$PID_FILE"
|
||||||
|
fi
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check if directory exists
|
||||||
|
if [[ ! -d "$AGENT_MAIL_DIR" ]]; then
|
||||||
|
echo "❌ Agent Mail directory not found: $AGENT_MAIL_DIR"
|
||||||
|
echo ""
|
||||||
|
echo "Install with:"
|
||||||
|
echo " git clone https://github.com/Dicklesworthstone/mcp_agent_mail.git $AGENT_MAIL_DIR"
|
||||||
|
echo " cd $AGENT_MAIL_DIR"
|
||||||
|
echo " python3 -m venv .venv"
|
||||||
|
echo " source .venv/bin/activate"
|
||||||
|
echo " pip install -e ."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Check if venv exists
|
||||||
|
if [[ ! -d "$AGENT_MAIL_DIR/.venv" ]]; then
|
||||||
|
echo "❌ Virtual environment not found in $AGENT_MAIL_DIR/.venv"
|
||||||
|
echo ""
|
||||||
|
echo "Create with:"
|
||||||
|
echo " cd $AGENT_MAIL_DIR"
|
||||||
|
echo " python3 -m venv .venv"
|
||||||
|
echo " source .venv/bin/activate"
|
||||||
|
echo " pip install -e ."
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Start server
|
||||||
|
echo "🚀 Starting Agent Mail server..."
|
||||||
|
echo " Directory: $AGENT_MAIL_DIR"
|
||||||
|
echo " Log file: $LOG_FILE"
|
||||||
|
echo " Port: $PORT"
|
||||||
|
|
||||||
|
cd "$AGENT_MAIL_DIR"
|
||||||
|
source .venv/bin/activate
|
||||||
|
|
||||||
|
nohup python -m mcp_agent_mail.cli serve-http \
|
||||||
|
--host 127.0.0.1 \
|
||||||
|
--port "$PORT" \
|
||||||
|
> "$LOG_FILE" 2>&1 &
|
||||||
|
|
||||||
|
echo $! > "$PID_FILE"
|
||||||
|
|
||||||
|
# Wait a moment for server to start
|
||||||
|
sleep 2
|
||||||
|
|
||||||
|
# Check if server is healthy
|
||||||
|
if curl -sf http://127.0.0.1:$PORT/health > /dev/null; then
|
||||||
|
echo "✅ Agent Mail server started successfully!"
|
||||||
|
echo " PID: $(cat $PID_FILE)"
|
||||||
|
echo " Health: http://127.0.0.1:$PORT/health"
|
||||||
|
echo " Web UI: http://127.0.0.1:$PORT/mail"
|
||||||
|
echo ""
|
||||||
|
echo "View logs:"
|
||||||
|
echo " tail -f $LOG_FILE"
|
||||||
|
echo ""
|
||||||
|
echo "Stop server:"
|
||||||
|
echo " kill $(cat $PID_FILE)"
|
||||||
|
else
|
||||||
|
echo "❌ Server failed to start"
|
||||||
|
echo " Check logs: tail -f $LOG_FILE"
|
||||||
|
rm -f "$PID_FILE"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
53
scripts/stop-agent-mail-server.sh
Executable file
53
scripts/stop-agent-mail-server.sh
Executable file
@@ -0,0 +1,53 @@
|
|||||||
|
#!/bin/bash
|
||||||
|
# Stop Agent Mail server
|
||||||
|
# Usage: ./stop-agent-mail-server.sh
|
||||||
|
|
||||||
|
PID_FILE="${AGENT_MAIL_PID:-$HOME/agent-mail.pid}"
|
||||||
|
|
||||||
|
if [[ ! -f "$PID_FILE" ]]; then
|
||||||
|
echo "⚠️ No PID file found: $PID_FILE"
|
||||||
|
echo " Attempting to kill by process name..."
|
||||||
|
|
||||||
|
if pkill -f "mcp_agent_mail.cli serve-http"; then
|
||||||
|
echo "✅ Killed Agent Mail server by process name"
|
||||||
|
else
|
||||||
|
echo "ℹ️ No Agent Mail server process found"
|
||||||
|
fi
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
PID=$(cat "$PID_FILE")
|
||||||
|
|
||||||
|
if ! ps -p "$PID" > /dev/null 2>&1; then
|
||||||
|
echo "⚠️ Process $PID not running (stale PID file)"
|
||||||
|
rm -f "$PID_FILE"
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
|
||||||
|
echo "🛑 Stopping Agent Mail server (PID: $PID)..."
|
||||||
|
kill "$PID"
|
||||||
|
|
||||||
|
# Wait for graceful shutdown
|
||||||
|
for i in {1..5}; do
|
||||||
|
if ! ps -p "$PID" > /dev/null 2>&1; then
|
||||||
|
echo "✅ Server stopped gracefully"
|
||||||
|
rm -f "$PID_FILE"
|
||||||
|
exit 0
|
||||||
|
fi
|
||||||
|
sleep 1
|
||||||
|
done
|
||||||
|
|
||||||
|
# Force kill if needed
|
||||||
|
if ps -p "$PID" > /dev/null 2>&1; then
|
||||||
|
echo "⚠️ Server didn't stop gracefully, forcing..."
|
||||||
|
kill -9 "$PID"
|
||||||
|
sleep 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
if ! ps -p "$PID" > /dev/null 2>&1; then
|
||||||
|
echo "✅ Server stopped (forced)"
|
||||||
|
rm -f "$PID_FILE"
|
||||||
|
else
|
||||||
|
echo "❌ Failed to stop server"
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
Reference in New Issue
Block a user