feat(agent-mail): Add Python adapter library for Agent Mail integration

- Created lib/beads_mail_adapter.py with AgentMailAdapter class - Automatic health check on initialization - Graceful degradation when server unavailable - Methods: reserve_issue(), release_issue(), notify(), check_inbox() - Environment-based configuration (AGENT_MAIL_URL, AGENT_MAIL_TOKEN) - Comprehensive unit tests (15 tests, 100% passing) - Full documentation in lib/README.md Closes bd-m9th Amp-Thread-ID: https://ampcode.com/threads/T-caa26228-0d18-4b35-b98a-9f95f6a099fe Co-authored-by: Amp <amp@ampcode.com>
2025-11-08 00:15:07 -08:00
parent 716424e52a
commit 9351044539
10 changed files with 1233 additions and 15 deletions
--- a/lib/README.md
+++ b/lib/README.md
@@ -0,0 +1,173 @@
+# Beads Agent Mail Adapter
+
+Lightweight Python library for integrating [MCP Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) with Beads issue tracking.
+
+## Features
+
+- **Collision Prevention**: Reserve issues to prevent duplicate work across agents
+- **Real-Time Coordination**: <100ms latency vs 2-5s with git-only sync
+- **Graceful Degradation**: Automatically falls back to git-only mode when server unavailable
+- **Zero Configuration**: Works without Agent Mail (optional enhancement)
+
+## Installation
+
+No installation required - just copy `beads_mail_adapter.py` to your project:
+
+```bash
+cp lib/beads_mail_adapter.py /path/to/your/agent/
+```
+
+## Quick Start
+
+```python
+from beads_mail_adapter import AgentMailAdapter
+
+# Initialize adapter (automatically detects server availability)
+adapter = AgentMailAdapter()
+
+if adapter.enabled:
+    print("✅ Agent Mail coordination enabled")
+else:
+    print("⚠️  Agent Mail unavailable, using git-only mode")
+
+# Reserve issue before claiming
+if adapter.reserve_issue("bd-123"):
+    # Claim issue in Beads
+    subprocess.run(["bd", "update", "bd-123", "--status", "in_progress"])
+    
+    # Do work...
+    
+    # Notify other agents
+    adapter.notify("status_changed", {"issue_id": "bd-123", "status": "completed"})
+    
+    # Release reservation
+    adapter.release_issue("bd-123")
+else:
+    print("❌ Issue bd-123 already reserved by another agent")
+```
+
+## Configuration
+
+Configure via environment variables:
+
+```bash
+# Agent Mail server URL (default: http://127.0.0.1:8765)
+export AGENT_MAIL_URL=http://localhost:8765
+
+# Authentication token (optional)
+export AGENT_MAIL_TOKEN=your-bearer-token
+
+# Agent identifier (default: hostname)
+export BEADS_AGENT_NAME=assistant-alpha
+
+# Request timeout in seconds (default: 5)
+export AGENT_MAIL_TIMEOUT=5
+```
+
+Or pass directly to constructor:
+
+```python
+adapter = AgentMailAdapter(
+    url="http://localhost:8765",
+    token="your-token",
+    agent_name="assistant-alpha",
+    timeout=5
+)
+```
+
+## API Reference
+
+### `AgentMailAdapter(url=None, token=None, agent_name=None, timeout=5)`
+
+Initialize adapter with optional configuration overrides.
+
+**Attributes:**
+- `enabled` (bool): True if server is available, False otherwise
+
+### `reserve_issue(issue_id: str, ttl: int = 3600) -> bool`
+
+Reserve an issue to prevent other agents from claiming it.
+
+**Args:**
+- `issue_id`: Issue ID (e.g., "bd-123")
+- `ttl`: Reservation time-to-live in seconds (default: 1 hour)
+
+**Returns:** True if reservation successful, False if already reserved
+
+### `release_issue(issue_id: str) -> bool`
+
+Release a previously reserved issue.
+
+**Returns:** True on success
+
+### `notify(event_type: str, data: Dict[str, Any]) -> bool`
+
+Send notification to other agents.
+
+**Args:**
+- `event_type`: Event type (e.g., "status_changed", "issue_completed")
+- `data`: Event payload
+
+**Returns:** True on success
+
+### `check_inbox() -> List[Dict[str, Any]]`
+
+Check for incoming notifications from other agents.
+
+**Returns:** List of notification messages (empty if none or server unavailable)
+
+### `get_reservations() -> List[Dict[str, Any]]`
+
+Get all active reservations.
+
+**Returns:** List of active reservations
+
+## Testing
+
+Run the test suite:
+
+```bash
+cd lib
+python3 test_beads_mail_adapter.py -v
+```
+
+Coverage includes:
+- Server available/unavailable scenarios
+- Graceful degradation
+- Reservation conflicts
+- Environment variable configuration
+
+## Integration Examples
+
+See [examples/python-agent/agent.py](../examples/python-agent/agent.py) for a complete agent implementation.
+
+## Graceful Degradation
+
+The adapter is designed to **never block or fail** your agent:
+
+- If server is unavailable on init → `enabled = False`, all operations no-op
+- If server dies mid-operation → methods return success (graceful degradation)
+- If network timeout → operations continue (no blocking)
+- If 409 conflict on reservation → returns `False` (expected behavior)
+
+This ensures your agent works identically with or without Agent Mail.
+
+## When to Use Agent Mail
+
+**Use Agent Mail when:**
+- Running multiple AI agents concurrently
+- Need real-time collision prevention
+- Want to reduce git commit noise
+- Need <100ms coordination latency
+
+**Stick with git-only when:**
+- Single agent workflow
+- No concurrent work
+- Simplicity over speed
+- No server infrastructure available
+
+## Resources
+
+- [ADR 002: Agent Mail Integration](../docs/adr/002-agent-mail-integration.md)
+- [MCP Agent Mail Repository](https://github.com/Dicklesworthstone/mcp_agent_mail)
+- [Latency Benchmark Results](../latency_results.md)