Fix prefix detection to only use first hyphen (bd-fasa)
- Changed ExtractIssuePrefix to use strings.Index (first hyphen) - IDs like 'vc-baseline-test' now correctly use prefix 'vc' - Fixes false prefix mismatch errors for hyphenated suffixes - Added comprehensive tests for multi-part ID handling
This commit is contained in:
Steve Yegge
611
integrations/beads-mcp/src/beads_mcp/mail.py
Normal file
611
integrations/beads-mcp/src/beads_mcp/mail.py
Normal file
@@ -0,0 +1,611 @@
|
||||
"""Agent Mail integration for beads MCP server.
|
||||
|
||||
Provides simple messaging functions that wrap Agent Mail HTTP API.
|
||||
Requires BEADS_AGENT_MAIL_URL and BEADS_AGENT_NAME environment variables.
|
||||
"""
|
||||
|
||||
import logging
|
||||
import os
|
||||
from typing import Any, Optional
|
||||
from urllib.parse import urljoin
|
||||
|
||||
import requests
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
# Timeout for Agent Mail HTTP requests (seconds)
|
||||
AGENT_MAIL_TIMEOUT = 5.0
|
||||
AGENT_MAIL_RETRIES = 2
|
||||
|
||||
|
||||
class MailError(Exception):
|
||||
"""Base exception for Agent Mail errors."""
|
||||
|
||||
def __init__(self, code: str, message: str, data: Optional[dict] = None):
|
||||
self.code = code
|
||||
self.message = message
|
||||
self.data = data or {}
|
||||
super().__init__(message)
|
||||
|
||||
|
||||
def _get_config() -> tuple[str, str, Optional[str]]:
|
||||
"""Get Agent Mail configuration from environment.
|
||||
|
||||
Returns:
|
||||
(base_url, agent_name, token)
|
||||
|
||||
Raises:
|
||||
MailError: If required configuration is missing
|
||||
"""
|
||||
base_url = os.environ.get("BEADS_AGENT_MAIL_URL")
|
||||
if not base_url:
|
||||
raise MailError(
|
||||
"NOT_CONFIGURED",
|
||||
"Agent Mail not configured. Set BEADS_AGENT_MAIL_URL environment variable.\n"
|
||||
"Example: export BEADS_AGENT_MAIL_URL=http://127.0.0.1:8765\n"
|
||||
"See docs/AGENT_MAIL_QUICKSTART.md for setup instructions.",
|
||||
)
|
||||
|
||||
agent_name = os.environ.get("BEADS_AGENT_NAME")
|
||||
if not agent_name:
|
||||
# Try to derive from user/repo
|
||||
import getpass
|
||||
|
||||
try:
|
||||
user = getpass.getuser()
|
||||
cwd = os.getcwd()
|
||||
repo_name = os.path.basename(cwd)
|
||||
agent_name = f"{user}-{repo_name}"
|
||||
logger.warning(
|
||||
f"BEADS_AGENT_NAME not set, using derived name: {agent_name}"
|
||||
)
|
||||
except Exception:
|
||||
raise MailError(
|
||||
"NOT_CONFIGURED",
|
||||
"Agent Mail not configured. Set BEADS_AGENT_NAME environment variable.\n"
|
||||
"Example: export BEADS_AGENT_NAME=my-agent",
|
||||
)
|
||||
|
||||
token = os.environ.get("BEADS_AGENT_MAIL_TOKEN")
|
||||
|
||||
return base_url, agent_name, token
|
||||
|
||||
|
||||
def _get_project_key() -> str:
|
||||
"""Get project key from environment or derive from Git/workspace.
|
||||
|
||||
Returns:
|
||||
Project key (absolute path to workspace root)
|
||||
"""
|
||||
# Check explicit project ID first
|
||||
project_id = os.environ.get("BEADS_PROJECT_ID")
|
||||
if project_id:
|
||||
return project_id
|
||||
|
||||
# Try to get from bd workspace detection
|
||||
# Import here to avoid circular dependency
|
||||
from .tools import _find_beads_db_in_tree
|
||||
|
||||
workspace = _find_beads_db_in_tree()
|
||||
if workspace:
|
||||
return os.path.abspath(workspace)
|
||||
|
||||
# Fallback to current directory
|
||||
return os.path.abspath(os.getcwd())
|
||||
|
||||
|
||||
def _call_agent_mail(
|
||||
method: str,
|
||||
endpoint: str,
|
||||
json_data: Optional[dict] = None,
|
||||
params: Optional[dict] = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Make HTTP request to Agent Mail server with retries.
|
||||
|
||||
Args:
|
||||
method: HTTP method (GET, POST, DELETE, etc.)
|
||||
endpoint: API endpoint path (e.g., "/api/messages")
|
||||
json_data: Request body as JSON
|
||||
params: URL query parameters
|
||||
|
||||
Returns:
|
||||
Response JSON
|
||||
|
||||
Raises:
|
||||
MailError: On request failure or server error
|
||||
"""
|
||||
base_url, _, token = _get_config()
|
||||
url = urljoin(base_url, endpoint)
|
||||
|
||||
headers = {}
|
||||
if token:
|
||||
headers["Authorization"] = f"Bearer {token}"
|
||||
|
||||
# Use idempotency key for write operations to avoid duplicates on retry
|
||||
if method in {"POST", "PUT"} and json_data:
|
||||
import uuid
|
||||
|
||||
headers["Idempotency-Key"] = str(uuid.uuid4())
|
||||
|
||||
last_error = None
|
||||
for attempt in range(AGENT_MAIL_RETRIES + 1):
|
||||
try:
|
||||
response = requests.request(
|
||||
method,
|
||||
url,
|
||||
json=json_data,
|
||||
params=params,
|
||||
headers=headers,
|
||||
timeout=AGENT_MAIL_TIMEOUT,
|
||||
)
|
||||
|
||||
# Success
|
||||
if response.status_code < 400:
|
||||
return response.json() if response.content else {}
|
||||
|
||||
# Client error - don't retry
|
||||
if 400 <= response.status_code < 500:
|
||||
error_data = {}
|
||||
try:
|
||||
error_data = response.json()
|
||||
except Exception:
|
||||
error_data = {"detail": response.text}
|
||||
|
||||
if response.status_code == 404:
|
||||
raise MailError(
|
||||
"NOT_FOUND",
|
||||
f"Resource not found: {endpoint}",
|
||||
error_data,
|
||||
)
|
||||
elif response.status_code == 409:
|
||||
raise MailError(
|
||||
"CONFLICT",
|
||||
error_data.get("detail", "Conflict"),
|
||||
error_data,
|
||||
)
|
||||
else:
|
||||
raise MailError(
|
||||
"INVALID_ARGUMENT",
|
||||
error_data.get("detail", f"HTTP {response.status_code}"),
|
||||
error_data,
|
||||
)
|
||||
|
||||
# Server error - retry
|
||||
last_error = MailError(
|
||||
"UNAVAILABLE",
|
||||
f"Agent Mail server error: HTTP {response.status_code}",
|
||||
{"status": response.status_code, "attempt": attempt + 1},
|
||||
)
|
||||
|
||||
except requests.exceptions.Timeout:
|
||||
last_error = MailError(
|
||||
"TIMEOUT",
|
||||
f"Agent Mail request timeout after {AGENT_MAIL_TIMEOUT}s",
|
||||
{"attempt": attempt + 1},
|
||||
)
|
||||
except requests.exceptions.ConnectionError as e:
|
||||
last_error = MailError(
|
||||
"UNAVAILABLE",
|
||||
f"Cannot connect to Agent Mail server at {base_url}",
|
||||
{"error": str(e), "attempt": attempt + 1},
|
||||
)
|
||||
except MailError:
|
||||
raise # Re-raise our own errors
|
||||
except Exception as e:
|
||||
last_error = MailError(
|
||||
"INTERNAL_ERROR",
|
||||
f"Unexpected error calling Agent Mail: {e}",
|
||||
{"error": str(e), "attempt": attempt + 1},
|
||||
)
|
||||
|
||||
# Exponential backoff between retries
|
||||
if attempt < AGENT_MAIL_RETRIES:
|
||||
import time
|
||||
|
||||
time.sleep(0.5 * (2**attempt))
|
||||
|
||||
# All retries exhausted
|
||||
raise last_error
|
||||
|
||||
|
||||
def mail_send(
|
||||
to: list[str],
|
||||
subject: str,
|
||||
body: str,
|
||||
urgent: bool = False,
|
||||
cc: Optional[list[str]] = None,
|
||||
project_key: Optional[str] = None,
|
||||
sender_name: Optional[str] = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Send a message to other agents.
|
||||
|
||||
Args:
|
||||
to: List of recipient agent names
|
||||
subject: Message subject
|
||||
body: Message body (Markdown)
|
||||
urgent: Mark as urgent (default: False)
|
||||
cc: Optional CC recipients
|
||||
project_key: Override project identifier (default: auto-detect)
|
||||
sender_name: Override sender name (default: BEADS_AGENT_NAME)
|
||||
|
||||
Returns:
|
||||
{
|
||||
"message_id": int,
|
||||
"thread_id": str,
|
||||
"sent_to": int # number of recipients
|
||||
}
|
||||
|
||||
Raises:
|
||||
MailError: On configuration or delivery error
|
||||
"""
|
||||
_, auto_agent_name, _ = _get_config()
|
||||
auto_project_key = _get_project_key()
|
||||
|
||||
sender = sender_name or auto_agent_name
|
||||
project = project_key or auto_project_key
|
||||
|
||||
importance = "urgent" if urgent else "normal"
|
||||
|
||||
# Call Agent Mail send_message tool via HTTP
|
||||
# Note: Agent Mail MCP tools use POST to /mcp/call endpoint
|
||||
result = _call_agent_mail(
|
||||
"POST",
|
||||
"/mcp/call",
|
||||
json_data={
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "send_message",
|
||||
"arguments": {
|
||||
"project_key": project,
|
||||
"sender_name": sender,
|
||||
"to": to,
|
||||
"subject": subject,
|
||||
"body_md": body,
|
||||
"cc": cc or [],
|
||||
"importance": importance,
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
# Extract message details from result
|
||||
# Agent Mail returns: {"deliveries": [...], "count": N}
|
||||
deliveries = result.get("deliveries", [])
|
||||
if not deliveries:
|
||||
raise MailError("INTERNAL_ERROR", "No deliveries returned from Agent Mail")
|
||||
|
||||
# Get message ID from first delivery
|
||||
first_delivery = deliveries[0]
|
||||
payload = first_delivery.get("payload", {})
|
||||
message_id = payload.get("id")
|
||||
thread_id = payload.get("thread_id")
|
||||
|
||||
return {
|
||||
"message_id": message_id,
|
||||
"thread_id": thread_id,
|
||||
"sent_to": len(deliveries),
|
||||
}
|
||||
|
||||
|
||||
def mail_inbox(
|
||||
limit: int = 20,
|
||||
urgent_only: bool = False,
|
||||
unread_only: bool = False,
|
||||
cursor: Optional[str] = None,
|
||||
agent_name: Optional[str] = None,
|
||||
project_key: Optional[str] = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Get messages from inbox.
|
||||
|
||||
Args:
|
||||
limit: Maximum messages to return (default: 20)
|
||||
urgent_only: Only return urgent messages
|
||||
unread_only: Only return unread messages
|
||||
cursor: Pagination cursor (for next page)
|
||||
agent_name: Override agent name (default: BEADS_AGENT_NAME)
|
||||
project_key: Override project (default: auto-detect)
|
||||
|
||||
Returns:
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"id": int,
|
||||
"thread_id": str,
|
||||
"from": str,
|
||||
"subject": str,
|
||||
"created_ts": str, # ISO-8601
|
||||
"unread": bool,
|
||||
"ack_required": bool,
|
||||
"urgent": bool,
|
||||
"preview": str # first 100 chars
|
||||
},
|
||||
...
|
||||
],
|
||||
"next_cursor": str | None
|
||||
}
|
||||
"""
|
||||
_, auto_agent_name, _ = _get_config()
|
||||
auto_project_key = _get_project_key()
|
||||
|
||||
agent = agent_name or auto_agent_name
|
||||
project = project_key or auto_project_key
|
||||
|
||||
# Call fetch_inbox via MCP
|
||||
result = _call_agent_mail(
|
||||
"POST",
|
||||
"/mcp/call",
|
||||
json_data={
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "fetch_inbox",
|
||||
"arguments": {
|
||||
"project_key": project,
|
||||
"agent_name": agent,
|
||||
"limit": limit,
|
||||
"urgent_only": urgent_only,
|
||||
"include_bodies": False, # Get preview only
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
# Agent Mail returns list of messages directly
|
||||
messages = result if isinstance(result, list) else []
|
||||
|
||||
# Transform to our format and filter unread if requested
|
||||
formatted_messages = []
|
||||
for msg in messages:
|
||||
# Skip read messages if unread_only
|
||||
if unread_only and msg.get("read_ts"):
|
||||
continue
|
||||
|
||||
formatted_messages.append(
|
||||
{
|
||||
"id": msg.get("id"),
|
||||
"thread_id": msg.get("thread_id"),
|
||||
"from": msg.get("from"),
|
||||
"subject": msg.get("subject"),
|
||||
"created_ts": msg.get("created_ts"),
|
||||
"unread": not bool(msg.get("read_ts")),
|
||||
"ack_required": msg.get("ack_required", False),
|
||||
"urgent": msg.get("importance") in {"high", "urgent"},
|
||||
"preview": msg.get("body_md", "")[:100] if msg.get("body_md") else "",
|
||||
}
|
||||
)
|
||||
|
||||
# Simple cursor pagination (use last message ID)
|
||||
next_cursor = None
|
||||
if formatted_messages and len(formatted_messages) >= limit:
|
||||
next_cursor = str(formatted_messages[-1]["id"])
|
||||
|
||||
return {"messages": formatted_messages, "next_cursor": next_cursor}
|
||||
|
||||
|
||||
def mail_read(
|
||||
message_id: int,
|
||||
mark_read: bool = True,
|
||||
agent_name: Optional[str] = None,
|
||||
project_key: Optional[str] = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Read full message with body.
|
||||
|
||||
Args:
|
||||
message_id: Message ID to read
|
||||
mark_read: Mark message as read (default: True)
|
||||
agent_name: Override agent name (default: BEADS_AGENT_NAME)
|
||||
project_key: Override project (default: auto-detect)
|
||||
|
||||
Returns:
|
||||
{
|
||||
"id": int,
|
||||
"thread_id": str,
|
||||
"from": str,
|
||||
"to": list[str],
|
||||
"subject": str,
|
||||
"body": str, # Full Markdown body
|
||||
"created_ts": str,
|
||||
"ack_required": bool,
|
||||
"ack_status": bool,
|
||||
"read_ts": str | None,
|
||||
"urgent": bool
|
||||
}
|
||||
"""
|
||||
_, auto_agent_name, _ = _get_config()
|
||||
auto_project_key = _get_project_key()
|
||||
|
||||
agent = agent_name or auto_agent_name
|
||||
project = project_key or auto_project_key
|
||||
|
||||
# Get message via resource
|
||||
result = _call_agent_mail(
|
||||
"GET", f"/mcp/resources/resource://message/{message_id}"
|
||||
)
|
||||
|
||||
# Mark as read if requested
|
||||
if mark_read:
|
||||
try:
|
||||
_call_agent_mail(
|
||||
"POST",
|
||||
"/mcp/call",
|
||||
json_data={
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "mark_message_read",
|
||||
"arguments": {
|
||||
"project_key": project,
|
||||
"agent_name": agent,
|
||||
"message_id": message_id,
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
except MailError as e:
|
||||
# Don't fail read if mark fails
|
||||
logger.warning(f"Failed to mark message {message_id} as read: {e}")
|
||||
|
||||
# Extract message from result
|
||||
# Resource returns: {"contents": [{...}]}
|
||||
contents = result.get("contents", [])
|
||||
if not contents:
|
||||
raise MailError("NOT_FOUND", f"Message {message_id} not found")
|
||||
|
||||
msg = contents[0]
|
||||
|
||||
return {
|
||||
"id": msg.get("id"),
|
||||
"thread_id": msg.get("thread_id"),
|
||||
"from": msg.get("from"),
|
||||
"to": msg.get("to", []),
|
||||
"subject": msg.get("subject"),
|
||||
"body": msg.get("body_md", ""),
|
||||
"created_ts": msg.get("created_ts"),
|
||||
"ack_required": msg.get("ack_required", False),
|
||||
"ack_status": bool(msg.get("ack_ts")),
|
||||
"read_ts": msg.get("read_ts"),
|
||||
"urgent": msg.get("importance") in {"high", "urgent"},
|
||||
}
|
||||
|
||||
|
||||
def mail_reply(
|
||||
message_id: int,
|
||||
body: str,
|
||||
subject: Optional[str] = None,
|
||||
agent_name: Optional[str] = None,
|
||||
project_key: Optional[str] = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Reply to a message (preserves thread).
|
||||
|
||||
Args:
|
||||
message_id: Message ID to reply to
|
||||
body: Reply body (Markdown)
|
||||
subject: Override subject (default: "Re: <original subject>")
|
||||
agent_name: Override sender name (default: BEADS_AGENT_NAME)
|
||||
project_key: Override project (default: auto-detect)
|
||||
|
||||
Returns:
|
||||
{
|
||||
"message_id": int,
|
||||
"thread_id": str
|
||||
}
|
||||
"""
|
||||
_, auto_agent_name, _ = _get_config()
|
||||
auto_project_key = _get_project_key()
|
||||
|
||||
sender = agent_name or auto_agent_name
|
||||
project = project_key or auto_project_key
|
||||
|
||||
# Call reply_message via MCP
|
||||
args = {
|
||||
"project_key": project,
|
||||
"message_id": message_id,
|
||||
"sender_name": sender,
|
||||
"body_md": body,
|
||||
}
|
||||
|
||||
if subject:
|
||||
args["subject_prefix"] = subject
|
||||
|
||||
result = _call_agent_mail(
|
||||
"POST",
|
||||
"/mcp/call",
|
||||
json_data={
|
||||
"method": "tools/call",
|
||||
"params": {"name": "reply_message", "arguments": args},
|
||||
},
|
||||
)
|
||||
|
||||
# Extract reply details
|
||||
reply = result.get("reply", {})
|
||||
return {
|
||||
"message_id": reply.get("id"),
|
||||
"thread_id": reply.get("thread_id"),
|
||||
}
|
||||
|
||||
|
||||
def mail_ack(
|
||||
message_id: int,
|
||||
agent_name: Optional[str] = None,
|
||||
project_key: Optional[str] = None,
|
||||
) -> dict[str, bool]:
|
||||
"""Acknowledge a message (for ack_required messages).
|
||||
|
||||
Args:
|
||||
message_id: Message ID to acknowledge
|
||||
agent_name: Override agent name (default: BEADS_AGENT_NAME)
|
||||
project_key: Override project (default: auto-detect)
|
||||
|
||||
Returns:
|
||||
{"acknowledged": True}
|
||||
"""
|
||||
_, auto_agent_name, _ = _get_config()
|
||||
auto_project_key = _get_project_key()
|
||||
|
||||
agent = agent_name or auto_agent_name
|
||||
project = project_key or auto_project_key
|
||||
|
||||
# Call acknowledge_message via MCP
|
||||
_call_agent_mail(
|
||||
"POST",
|
||||
"/mcp/call",
|
||||
json_data={
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "acknowledge_message",
|
||||
"arguments": {
|
||||
"project_key": project,
|
||||
"agent_name": agent,
|
||||
"message_id": message_id,
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
|
||||
return {"acknowledged": True}
|
||||
|
||||
|
||||
def mail_delete(
|
||||
message_id: int,
|
||||
agent_name: Optional[str] = None,
|
||||
project_key: Optional[str] = None,
|
||||
) -> dict[str, bool]:
|
||||
"""Delete (archive) a message from inbox.
|
||||
|
||||
Note: Agent Mail may archive rather than truly delete.
|
||||
|
||||
Args:
|
||||
message_id: Message ID to delete
|
||||
agent_name: Override agent name (default: BEADS_AGENT_NAME)
|
||||
project_key: Override project (default: auto-detect)
|
||||
|
||||
Returns:
|
||||
{"deleted": True} or {"archived": True}
|
||||
"""
|
||||
_, auto_agent_name, _ = _get_config()
|
||||
auto_project_key = _get_project_key()
|
||||
|
||||
agent = agent_name or auto_agent_name
|
||||
project = project_key or auto_project_key
|
||||
|
||||
# Agent Mail doesn't have explicit delete in MCP API
|
||||
# Best we can do is mark as read and acknowledged
|
||||
# (This prevents it from showing in urgent/unread views)
|
||||
try:
|
||||
_call_agent_mail(
|
||||
"POST",
|
||||
"/mcp/call",
|
||||
json_data={
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "mark_message_read",
|
||||
"arguments": {
|
||||
"project_key": project,
|
||||
"agent_name": agent,
|
||||
"message_id": message_id,
|
||||
},
|
||||
},
|
||||
},
|
||||
)
|
||||
return {"archived": True}
|
||||
except MailError:
|
||||
# Soft failure - message may not exist or already read
|
||||
return {"archived": True}
|
||||
Reference in New Issue
Block a user