Agent Mail

# SQLite databases
*.db
*.db?*
*.db-journal
*.db-wal
*.db-shm

# Daemon runtime files
daemon.lock
daemon.log
daemon.pid
bd.sock
sync-state.json
last-touched

# Local version tracking (prevents upgrade notification spam after git ops)
.local_version

# Legacy database files
db.sqlite
bd.db

# Worktree redirect file (contains relative path to main repo's .beads/)
# Must not be committed as paths would be wrong in other clones
redirect

# Merge artifacts (temporary files from 3-way merge)
beads.base.jsonl
beads.base.meta.json
beads.left.jsonl
beads.left.meta.json
beads.right.jsonl
beads.right.meta.json

# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
# They would override fork protection in .git/info/exclude, allowing
# contributors to accidentally commit upstream issue databases.
# The JSONL files (issues.jsonl, interactions.jsonl) and config files
# are tracked by git by default since no pattern above ignores them.

# Local history backups
.br_history/

# bv (beads viewer) lock file
.bv.lock

{"id": "bd-1", "title": "Testing Infrastructure Foundation", "description": "Set up comprehensive testing infrastructure with detailed logging, fixtures, and helpers for real component testing (no mocks). This is the foundation for all other test tasks.\n\n## Deliverables\n- Enhanced conftest.py with rich logging fixtures\n- Test helper utilities for common operations\n- Standardized assertion helpers with detailed output\n- Test database seeding utilities\n- Git archive test fixtures", "status": "open", "priority": 1, "blocked_by": [], "labels": ["testing", "infrastructure", "foundation"]}
{"id": "bd-2", "title": "Unit Tests: models.py", "description": "Complete unit test coverage for models.py (currently 99% - maintain and extend).\n\n## Test Areas\n- All SQLModel field validations\n- Default factory functions (_utcnow_naive)\n- Unique constraints behavior\n- Foreign key relationships\n- JSON field serialization (Message.attachments)\n\n## Notes\n- Use real SQLite database, no mocks\n- Test edge cases for all field types", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "models"]}
{"id": "bd-3", "title": "Unit Tests: config.py", "description": "Complete unit test coverage for config.py (currently 77%).\n\n## Test Areas\n- Settings class initialization\n- Environment variable loading via python-decouple\n- Default value fallbacks\n- Settings caching and clear_settings_cache()\n- All configuration options validation\n- Edge cases: missing env vars, invalid values\n\n## Missing Coverage (lines 20-22, 179-285, 340-342)\n- JWT/JWKS configuration\n- Redis configuration\n- HTTP configuration options", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "config"]}
{"id": "bd-4", "title": "Unit Tests: db.py - Session Management", "description": "Unit tests for database session management (currently 26%).\n\n## Test Areas\n- get_session() context manager behavior\n- ensure_schema() idempotency\n- reset_database_state() cleanup\n- Async session lifecycle\n- Connection pooling behavior\n- Transaction commit/rollback scenarios\n\n## Missing Coverage (lines 44-290)\n- Engine creation with various DATABASE_URL formats\n- Session scoping for concurrent access\n- Migration helpers", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "database"]}
{"id": "bd-5", "title": "Unit Tests: db.py - Migrations", "description": "Unit tests for database migration functionality.\n\n## Test Areas\n- Schema creation from scratch\n- Schema updates (adding columns)\n- Index creation\n- Constraint validation\n- Backward compatibility checks\n\n## Notes\n- Test with real SQLite database\n- Verify all tables created correctly", "status": "open", "priority": 3, "blocked_by": ["bd-4"], "labels": ["testing", "unit", "database", "migrations"]}
{"id": "bd-10", "title": "Unit Tests: app.py - Core Helpers", "description": "Unit tests for app.py core helper functions (currently 4% overall).\n\n## Test Areas\n- _naive_utc() datetime conversion\n- _ensure_utc() timezone handling\n- _iso() ISO format conversion\n- _max_datetime() comparisons\n- _safe_component() path sanitization\n- _canonical_project_pair() ordering\n- validate_agent_name_format() validation\n\n## Notes\n- Test edge cases: None values, timezone-aware vs naive\n- Test invalid inputs and error handling", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "app", "helpers"]}
{"id": "bd-11", "title": "Unit Tests: app.py - Project Operations", "description": "Unit tests for project-related operations in app.py.\n\n## Test Areas\n- _get_project_by_identifier() lookup\n- _ensure_project() creation and idempotency\n- Project slug generation\n- Human key normalization\n- Project sibling suggestions\n- _evaluate_project_siblings()\n- update_project_sibling_status()\n\n## Notes\n- Test with real database\n- Verify Git archive creation", "status": "open", "priority": 2, "blocked_by": ["bd-10", "bd-4"], "labels": ["testing", "unit", "app", "projects"]}
{"id": "bd-12", "title": "Unit Tests: app.py - Agent Operations", "description": "Unit tests for agent-related operations in app.py.\n\n## Test Areas\n- _get_or_create_agent() creation and update\n- _get_agent() lookup with suggestions\n- _find_similar_agents() fuzzy matching\n- _detect_agent_name_mistake() validation\n- Agent name validation (adjective+noun format)\n- last_active_ts updates\n- attachments_policy handling\n- contact_policy handling\n\n## Notes\n- Test case-insensitive matching\n- Test placeholder detection", "status": "open", "priority": 2, "blocked_by": ["bd-11"], "labels": ["testing", "unit", "app", "agents"]}
{"id": "bd-13", "title": "Unit Tests: app.py - Messaging", "description": "Unit tests for messaging operations in app.py.\n\n## Test Areas\n- _create_message() with all parameters\n- _deliver_message() routing logic\n- MessageRecipient creation (to/cc/bcc)\n- Thread ID handling\n- Importance levels\n- ack_required flag\n- Attachment handling\n- _update_recipient_timestamp() for read/ack\n\n## Notes\n- Test message delivery to multiple recipients\n- Test self-messages\n- Verify inbox/outbox artifacts created", "status": "open", "priority": 2, "blocked_by": ["bd-12"], "labels": ["testing", "unit", "app", "messaging"]}
{"id": "bd-14", "title": "Unit Tests: app.py - File Reservations", "description": "Unit tests for file reservation operations in app.py.\n\n## Test Areas\n- _create_file_reservation() with TTL\n- _expire_stale_file_reservations() cleanup\n- _file_reservations_conflict() detection\n- _collect_file_reservation_statuses() activity heuristics\n- Glob pattern matching\n- Exclusive vs shared reservations\n- Stale detection (agent activity, mail, filesystem, git)\n\n## Notes\n- Test pattern overlap detection\n- Test TTL expiration\n- Test force release", "status": "open", "priority": 2, "blocked_by": ["bd-12"], "labels": ["testing", "unit", "app", "file-reservations"]}
{"id": "bd-15", "title": "Unit Tests: app.py - Contact Management", "description": "Unit tests for contact/AgentLink operations in app.py.\n\n## Test Areas\n- request_contact() link creation\n- respond_contact() approval/denial\n- list_contacts() retrieval\n- set_contact_policy() updates\n- Contact policy enforcement (open/auto/contacts_only/block_all)\n- Cross-project contacts\n- TTL expiration\n\n## Notes\n- Test bidirectional links\n- Test auto-approval scenarios", "status": "open", "priority": 2, "blocked_by": ["bd-12"], "labels": ["testing", "unit", "app", "contacts"]}
{"id": "bd-16", "title": "Unit Tests: app.py - Macros", "description": "Unit tests for macro operations in app.py.\n\n## Test Areas\n- macro_start_session() full flow\n- macro_prepare_thread() context gathering\n- macro_file_reservation_cycle() lease management\n- macro_contact_handshake() approval flow\n\n## Notes\n- Macros combine multiple operations\n- Test error handling when sub-operations fail\n- Test with real database and Git", "status": "open", "priority": 2, "blocked_by": ["bd-13", "bd-14", "bd-15"], "labels": ["testing", "unit", "app", "macros"]}
{"id": "bd-17", "title": "Unit Tests: app.py - MCP Resources", "description": "Unit tests for MCP resource handlers in app.py.\n\n## Test Areas\n- resource://project/{slug}\n- resource://agents/{project}\n- resource://inbox/{agent}\n- resource://outbox/{agent}\n- resource://thread/{id}\n- resource://identity/{path} (worktree mode)\n- resource://product/{key}\n\n## Notes\n- Test query parameters (limit, include_bodies)\n- Test error responses for missing resources", "status": "open", "priority": 2, "blocked_by": ["bd-13"], "labels": ["testing", "unit", "app", "resources"]}
{"id": "bd-18", "title": "Unit Tests: app.py - MCP Tools", "description": "Unit tests for all MCP tool handlers in app.py.\n\n## Test Areas\n- health_check\n- ensure_project\n- register_agent / create_agent_identity\n- whois\n- send_message / reply_message\n- fetch_inbox\n- mark_message_read / acknowledge_message\n- search_messages\n- summarize_thread\n- file_reservation_paths / release / renew / force_release\n- request_contact / respond_contact / list_contacts / set_contact_policy\n- All macro tools\n- Build slot tools (when enabled)\n- Product bus tools\n\n## Notes\n- Test via FastMCP Client for realistic MCP protocol\n- Test error responses (ToolError)\n- Test input validation", "status": "open", "priority": 1, "blocked_by": ["bd-16", "bd-17"], "labels": ["testing", "unit", "app", "tools"]}
{"id": "bd-20", "title": "Unit Tests: storage.py - Archive Operations", "description": "Unit tests for Git archive operations in storage.py (currently 9%).\n\n## Test Areas\n- ensure_archive() initialization\n- ProjectArchive class operations\n- write_agent_profile() persistence\n- write_message_artifacts() inbox/outbox\n- write_file_reservation_records()\n- Git commit operations\n- _archive_write_lock() concurrency\n\n## Notes\n- Test with real Git repos\n- Test concurrent access patterns\n- Verify file structure matches spec", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "storage", "git"]}
{"id": "bd-21", "title": "Unit Tests: storage.py - Inbox/Outbox", "description": "Unit tests for mailbox operations in storage.py.\n\n## Test Areas\n- Inbox file structure (agents/{name}/inbox/YYYY/MM/*.md)\n- Outbox file structure (agents/{name}/outbox/YYYY/MM/*.md)\n- Message file naming conventions\n- Markdown content generation\n- Attachment embedding\n- Thread ID tracking\n\n## Notes\n- Verify Git commits have correct author/message\n- Test file path sanitization", "status": "open", "priority": 2, "blocked_by": ["bd-20"], "labels": ["testing", "unit", "storage", "mailbox"]}
{"id": "bd-22", "title": "Unit Tests: storage.py - Repo Cache", "description": "Unit tests for Git repo caching in storage.py.\n\n## Test Areas\n- clear_repo_cache() cleanup\n- Repo instance reuse\n- File handle management\n- Concurrent repo access\n\n## Notes\n- Test resource cleanup\n- Prevent ResourceWarning leaks", "status": "open", "priority": 3, "blocked_by": ["bd-20"], "labels": ["testing", "unit", "storage", "cache"]}
{"id": "bd-30", "title": "Unit Tests: cli.py - Core Commands", "description": "Unit tests for CLI core commands (currently 8%).\n\n## Test Areas\n- mail status command\n- mail inbox command\n- mail send command\n- mail ack command\n- mail search command\n\n## Notes\n- Use typer.testing.CliRunner\n- Test JSON output format\n- Test rich console output", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "cli"]}
{"id": "bd-31", "title": "Unit Tests: cli.py - Guard Commands", "description": "Unit tests for CLI guard commands.\n\n## Test Areas\n- guard status command\n- guard install command\n- guard uninstall command\n- Pre-commit hook behavior\n- Pre-push hook behavior\n\n## Notes\n- Test hook chain composition\n- Test bypass modes", "status": "open", "priority": 2, "blocked_by": ["bd-30"], "labels": ["testing", "unit", "cli", "guards"]}
{"id": "bd-32", "title": "Unit Tests: cli.py - Archive Commands", "description": "Unit tests for CLI archive commands.\n\n## Test Areas\n- archive save command\n- archive list command\n- archive restore command\n- archive export command\n\n## Notes\n- Test ZIP file creation/extraction\n- Test database backup/restore", "status": "open", "priority": 2, "blocked_by": ["bd-30"], "labels": ["testing", "unit", "cli", "archive"]}
{"id": "bd-33", "title": "Unit Tests: cli.py - Project Commands", "description": "Unit tests for CLI project commands.\n\n## Test Areas\n- projects list command\n- projects mark-identity command\n- projects discovery-init command\n- projects link command\n\n## Notes\n- Test Git marker file creation\n- Test YAML configuration", "status": "open", "priority": 3, "blocked_by": ["bd-30"], "labels": ["testing", "unit", "cli", "projects"]}
{"id": "bd-34", "title": "Unit Tests: cli.py - Product Commands", "description": "Unit tests for CLI product bus commands.\n\n## Test Areas\n- products ensure command\n- products link command\n- products status command\n- products search command\n- products inbox command\n- products summarize-thread command\n\n## Notes\n- Test cross-project operations\n- Test product-wide search", "status": "open", "priority": 3, "blocked_by": ["bd-30"], "labels": ["testing", "unit", "cli", "products"]}
{"id": "bd-40", "title": "Unit Tests: http.py - Server Setup", "description": "Unit tests for HTTP server setup in http.py (currently 4%).\n\n## Test Areas\n- create_http_app() initialization\n- Uvicorn worker configuration\n- CORS setup\n- SSE transport setup\n- Health endpoint\n\n## Notes\n- Test with real HTTP client (httpx)\n- No mocked responses", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "http"]}
{"id": "bd-41", "title": "Unit Tests: http.py - Authentication", "description": "Unit tests for HTTP authentication in http.py.\n\n## Test Areas\n- Static bearer token auth\n- JWT validation\n- JWKS key fetching\n- Token expiration\n- Invalid token handling\n\n## Notes\n- Test both auth modes\n- Test error responses", "status": "open", "priority": 2, "blocked_by": ["bd-40"], "labels": ["testing", "unit", "http", "auth"]}
{"id": "bd-42", "title": "Unit Tests: http.py - Rate Limiting", "description": "Unit tests for HTTP rate limiting in http.py.\n\n## Test Areas\n- In-memory rate limiter\n- Redis-backed rate limiter\n- Rate limit headers\n- 429 responses\n- Per-client tracking\n\n## Notes\n- Test burst handling\n- Test rate limit recovery", "status": "open", "priority": 3, "blocked_by": ["bd-40"], "labels": ["testing", "unit", "http", "rate-limit"]}
{"id": "bd-50", "title": "Unit Tests: guard.py - Pre-commit", "description": "Unit tests for pre-commit guard logic in guard.py (currently 8%).\n\n## Test Areas\n- Staged file detection\n- File reservation conflict checking\n- Agent identification\n- Bypass mode (AGENT_MAIL_BYPASS)\n- Warning mode (AGENT_MAIL_GUARD_MODE=warn)\n\n## Notes\n- Test with real Git repos\n- Test rename detection (-M flag)", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "guards"]}
{"id": "bd-51", "title": "Unit Tests: guard.py - Pre-push", "description": "Unit tests for pre-push guard logic in guard.py.\n\n## Test Areas\n- Commit enumeration (git rev-list)\n- Tree diff detection (git diff-tree)\n- Remote branch tracking\n- Conflict resolution\n\n## Notes\n- Test with multiple commits\n- Test force push scenarios", "status": "open", "priority": 2, "blocked_by": ["bd-50"], "labels": ["testing", "unit", "guards"]}
{"id": "bd-52", "title": "Unit Tests: guard.py - Hook Installation", "description": "Unit tests for hook installation in guard.py.\n\n## Test Areas\n- Hook chain runner generation\n- hooks.d directory structure\n- Existing hook preservation (.orig)\n- Husky compatibility\n- core.hooksPath respect\n\n## Notes\n- Test Windows shim generation\n- Test uninstall cleanup", "status": "open", "priority": 3, "blocked_by": ["bd-50"], "labels": ["testing", "unit", "guards", "hooks"]}
{"id": "bd-60", "title": "Unit Tests: share.py - Archive Save", "description": "Unit tests for archive save functionality in share.py (currently 12%).\n\n## Test Areas\n- ZIP archive creation\n- Database backup inclusion\n- Storage root backup\n- Label/metadata handling\n- Incremental vs full backup\n\n## Notes\n- Test large archive handling\n- Verify ZIP structure", "status": "open", "priority": 2, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "share"]}
{"id": "bd-61", "title": "Unit Tests: share.py - Archive Restore", "description": "Unit tests for archive restore functionality in share.py.\n\n## Test Areas\n- ZIP extraction\n- Database restoration\n- Storage root restoration\n- Conflict handling (--force)\n- Integrity validation\n\n## Notes\n- Test corrupted archive handling\n- Test partial restore scenarios", "status": "open", "priority": 2, "blocked_by": ["bd-60"], "labels": ["testing", "unit", "share"]}
{"id": "bd-62", "title": "Unit Tests: share.py - Export", "description": "Unit tests for export functionality in share.py.\n\n## Test Areas\n- HTML export generation\n- Thread export\n- Attachment handling\n- XSS sanitization\n- CSS styling\n\n## Notes\n- Verify HTML output is valid\n- Test with various message content", "status": "open", "priority": 3, "blocked_by": ["bd-60"], "labels": ["testing", "unit", "share", "export"]}
{"id": "bd-70", "title": "Unit Tests: llm.py - Provider Integration", "description": "Unit tests for LLM provider integration in llm.py (currently 17%).\n\n## Test Areas\n- LiteLLM initialization\n- Model selection\n- Token counting (tiktoken)\n- Response parsing\n- Error handling (rate limits, timeouts)\n\n## Notes\n- May need real API calls or recorded responses\n- Test fallback behavior", "status": "open", "priority": 3, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "llm"]}
{"id": "bd-71", "title": "Unit Tests: llm.py - Thread Summarization", "description": "Unit tests for LLM-based thread summarization.\n\n## Test Areas\n- summarize_thread() with LLM mode\n- Key points extraction\n- Action items extraction\n- Participant identification\n\n## Notes\n- Test with various thread lengths\n- Test fallback to non-LLM mode", "status": "open", "priority": 3, "blocked_by": ["bd-70"], "labels": ["testing", "unit", "llm", "summarization"]}
{"id": "bd-80", "title": "Unit Tests: rich_logger.py", "description": "Unit tests for rich logging infrastructure (currently 15%).\n\n## Test Areas\n- Console output formatting\n- Panel rendering\n- JSON output mode\n- Log level filtering\n- Structured logging\n\n## Notes\n- Test with captured console output\n- Verify color/style application", "status": "open", "priority": 3, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "logging"]}
{"id": "bd-90", "title": "Unit Tests: utils.py", "description": "Unit tests for utility functions in utils.py (currently 40%).\n\n## Test Areas\n- All utility functions\n- Edge cases and error handling\n\n## Notes\n- Verify all helper functions work correctly", "status": "open", "priority": 3, "blocked_by": ["bd-1"], "labels": ["testing", "unit", "utils"]}
{"id": "bd-100", "title": "Integration Tests: Full Messaging Flow", "description": "End-to-end integration test for complete messaging workflow.\n\n## Test Scenario\n1. Create project\n2. Register two agents\n3. Agent A sends message to Agent B\n4. Agent B fetches inbox, sees message\n5. Agent B marks as read\n6. Agent B acknowledges\n7. Verify all state in database and Git archive\n\n## Logging\n- Rich console output at each step\n- Timing information\n- Database state dumps", "status": "open", "priority": 1, "blocked_by": ["bd-18"], "labels": ["testing", "integration", "e2e", "messaging"]}
{"id": "bd-101", "title": "Integration Tests: File Reservation Conflicts", "description": "End-to-end integration test for file reservation conflict handling.\n\n## Test Scenario\n1. Agent A reserves src/**/*.py exclusively\n2. Agent B attempts to reserve src/main.py\n3. Verify conflict returned\n4. Agent A releases reservation\n5. Agent B successfully reserves\n6. Test stale detection and force release\n\n## Logging\n- Detailed conflict information\n- Timing of TTL expiration", "status": "open", "priority": 1, "blocked_by": ["bd-18"], "labels": ["testing", "integration", "e2e", "file-reservations"]}
{"id": "bd-102", "title": "Integration Tests: Contact Management Flow", "description": "End-to-end integration test for contact request/approval flow.\n\n## Test Scenario\n1. Agent A requests contact with Agent B\n2. Agent B fetches inbox, sees contact request\n3. Agent B approves contact\n4. Agent A can now message Agent B\n5. Test cross-project contacts\n6. Test contact policy enforcement\n\n## Logging\n- Contact link state transitions\n- Policy evaluation details", "status": "open", "priority": 2, "blocked_by": ["bd-18"], "labels": ["testing", "integration", "e2e", "contacts"]}
{"id": "bd-103", "title": "Integration Tests: Thread Conversations", "description": "End-to-end integration test for threaded conversations.\n\n## Test Scenario\n1. Agent A starts thread with subject [bd-123]\n2. Agent B replies in thread\n3. Agent A replies back\n4. Fetch thread, verify all messages\n5. Summarize thread\n6. Search within thread\n\n## Logging\n- Thread ID tracking\n- Message ordering", "status": "open", "priority": 2, "blocked_by": ["bd-100"], "labels": ["testing", "integration", "e2e", "threads"]}
{"id": "bd-104", "title": "Integration Tests: Guard Pre-commit", "description": "End-to-end integration test for pre-commit guard.\n\n## Test Scenario\n1. Set up Git repo with guard installed\n2. Agent A reserves file.py\n3. Agent B (different identity) modifies file.py\n4. Agent B attempts commit\n5. Verify guard blocks commit\n6. Test warning mode\n7. Test bypass mode\n\n## Logging\n- Guard execution trace\n- Conflict details", "status": "open", "priority": 2, "blocked_by": ["bd-51"], "labels": ["testing", "integration", "e2e", "guards"]}
{"id": "bd-105", "title": "Integration Tests: Archive Save/Restore", "description": "End-to-end integration test for disaster recovery.\n\n## Test Scenario\n1. Create project with messages, agents, reservations\n2. Save archive with label\n3. Delete database and storage\n4. Restore from archive\n5. Verify all data recovered\n6. Verify message timestamps preserved\n\n## Logging\n- Archive contents listing\n- Restoration progress", "status": "open", "priority": 2, "blocked_by": ["bd-32"], "labels": ["testing", "integration", "e2e", "archive"]}
{"id": "bd-106", "title": "Integration Tests: HTTP Transport", "description": "End-to-end integration test for HTTP/SSE transport.\n\n## Test Scenario\n1. Start HTTP server\n2. Connect via SSE\n3. Call tools through HTTP\n4. Verify responses\n5. Test authentication\n6. Test rate limiting\n\n## Logging\n- Request/response traces\n- SSE event stream", "status": "open", "priority": 2, "blocked_by": ["bd-42"], "labels": ["testing", "integration", "e2e", "http"]}
{"id": "bd-107", "title": "Integration Tests: Product Bus", "description": "End-to-end integration test for product bus functionality.\n\n## Test Scenario\n1. Create product\n2. Link two projects to product\n3. Send messages in both projects\n4. Search across product\n5. Fetch product-wide inbox\n6. Summarize cross-project thread\n\n## Logging\n- Product-project linkage\n- Cross-project query results", "status": "open", "priority": 3, "blocked_by": ["bd-34"], "labels": ["testing", "integration", "e2e", "products"]}
{"id": "bd-108", "title": "Integration Tests: Concurrent Access", "description": "End-to-end integration test for concurrent operations.\n\n## Test Scenario\n1. Multiple agents operating simultaneously\n2. Concurrent message sends\n3. Concurrent file reservations\n4. Concurrent inbox fetches\n5. Verify no data corruption\n6. Verify proper locking\n\n## Logging\n- Timing of concurrent operations\n- Lock acquisition/release", "status": "open", "priority": 2, "blocked_by": ["bd-100", "bd-101"], "labels": ["testing", "integration", "e2e", "concurrency"]}
{"id": "bd-110", "title": "E2E Test Script: Multi-Agent Workflow", "description": "Comprehensive E2E test script simulating realistic multi-agent workflow.\n\n## Scenario\nSimulate a development team with 3 agents working on a codebase:\n1. BlueLake: Backend developer\n2. GreenMountain: Frontend developer  \n3. RedStone: Code reviewer\n\n## Workflow\n1. BlueLake announces work on API endpoint\n2. BlueLake reserves backend/**\n3. GreenMountain announces work on UI\n4. GreenMountain reserves frontend/**\n5. BlueLake sends PR notification\n6. RedStone reviews and comments\n7. Back-and-forth discussion in thread\n8. BlueLake releases reservation\n9. Full audit trail verification\n\n## Logging Requirements\n- Rich console panels for each step\n- Timing breakdown\n- State snapshots\n- Git archive diff at each stage", "status": "open", "priority": 1, "blocked_by": ["bd-100", "bd-101", "bd-103"], "labels": ["testing", "e2e", "script", "multi-agent"]}
{"id": "bd-111", "title": "E2E Test Script: Disaster Recovery", "description": "Comprehensive E2E test script for disaster recovery scenarios.\n\n## Scenario\nTest full backup/restore cycle with data verification:\n1. Create complex state (multiple projects, agents, messages, threads)\n2. Save labeled archive\n3. Corrupt/delete state\n4. Restore from archive\n5. Verify byte-perfect restoration\n6. Continue operations post-restore\n\n## Logging Requirements\n- Pre/post state comparison\n- Archive manifest\n- Restoration progress bar\n- Data integrity checksums", "status": "open", "priority": 2, "blocked_by": ["bd-105"], "labels": ["testing", "e2e", "script", "disaster-recovery"]}
{"id": "bd-112", "title": "E2E Test Script: Guard Enforcement", "description": "Comprehensive E2E test script for guard enforcement scenarios.\n\n## Scenario\nTest pre-commit and pre-push guards in realistic Git workflow:\n1. Set up repo with guards installed\n2. Multiple agents claim different files\n3. Simulate commits that should be blocked\n4. Simulate commits that should pass\n5. Test push with remote conflicts\n6. Test bypass and warning modes\n\n## Logging Requirements\n- Git command output\n- Guard decision tree\n- Conflict resolution suggestions", "status": "open", "priority": 2, "blocked_by": ["bd-104"], "labels": ["testing", "e2e", "script", "guards"]}
{"id": "bd-113", "title": "E2E Test Script: Performance Under Load", "description": "Comprehensive E2E test script for performance benchmarking.\n\n## Scenario\nTest system behavior under load:\n1. Create 100 agents\n2. Send 1000 messages\n3. Create 500 file reservations\n4. Concurrent operations (10 parallel)\n5. Measure latencies\n6. Verify no degradation\n\n## Logging Requirements\n- Latency histograms\n- Throughput metrics\n- Memory usage\n- Database query timing", "status": "open", "priority": 3, "blocked_by": ["bd-108"], "labels": ["testing", "e2e", "script", "performance"]}
{"id": "bd-120", "title": "Test Coverage: Achieve 50% Overall", "description": "Milestone: Achieve 50% overall test coverage.\n\n## Current State\n- Overall: 9%\n- app.py: 4%\n- cli.py: 8%\n- http.py: 4%\n\n## Target\n- Overall: 50%\n- All modules: minimum 30%\n\n## Verification\nRun: pytest --cov=src/mcp_agent_mail --cov-fail-under=50", "status": "open", "priority": 1, "blocked_by": ["bd-18", "bd-30", "bd-40", "bd-50", "bd-60"], "labels": ["testing", "milestone", "coverage"]}
{"id": "bd-121", "title": "Test Coverage: Achieve 80% Overall", "description": "Milestone: Achieve 80% overall test coverage.\n\n## Target\n- Overall: 80%\n- All modules: minimum 70%\n- Critical paths: 95%+\n\n## Verification\nRun: pytest --cov=src/mcp_agent_mail --cov-fail-under=80", "status": "open", "priority": 2, "blocked_by": ["bd-120"], "labels": ["testing", "milestone", "coverage"]}
{"id": "bd-122", "title": "Test Coverage: Achieve 95% Overall", "description": "Milestone: Achieve 95% overall test coverage.\n\n## Target\n- Overall: 95%\n- All modules: minimum 90%\n- No untested critical paths\n\n## Verification\nRun: pytest --cov=src/mcp_agent_mail --cov-fail-under=95", "status": "open", "priority": 3, "blocked_by": ["bd-121"], "labels": ["testing", "milestone", "coverage"]}
{"id": "bd-130", "title": "Test Documentation: Testing Guide", "description": "Create comprehensive testing documentation.\n\n## Contents\n- Test architecture overview\n- How to run tests\n- How to write new tests\n- Fixture usage guide\n- Logging conventions\n- Coverage requirements\n\n## Location\ntests/README.md", "status": "open", "priority": 3, "blocked_by": ["bd-1"], "labels": ["testing", "documentation"]}
{"id": "bd-131", "title": "CI Integration: Test Pipeline", "description": "Set up CI pipeline for automated testing.\n\n## Requirements\n- Run all tests on PR\n- Coverage reporting\n- Failure notifications\n- Performance regression detection\n\n## Notes\n- GitHub Actions or similar\n- Cache dependencies", "status": "open", "priority": 3, "blocked_by": ["bd-120"], "labels": ["testing", "ci", "automation"]}

issue_prefix: bd

{
  "database": "beads.db",
  "jsonl_export": "issues.jsonl"
}

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "cd '/home/ubuntu/mcp_agent_mail' && uv run python -m mcp_agent_mail.cli file_reservations active '/home/ubuntu/mcp_agent_mail'"
          },
          {
            "type": "command",
            "command": "cd '/home/ubuntu/mcp_agent_mail' && uv run python -m mcp_agent_mail.cli acks pending '/home/ubuntu/mcp_agent_mail' 'RedPond' --limit 20"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd '/home/ubuntu/mcp_agent_mail' && uv run python -m mcp_agent_mail.cli file_reservations soon '/home/ubuntu/mcp_agent_mail' --minutes 10"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "AGENT_MAIL_PROJECT='/home/ubuntu/mcp_agent_mail' AGENT_MAIL_AGENT='RedPond' AGENT_MAIL_URL='http://127.0.0.1:8765/api/' AGENT_MAIL_TOKEN='dc5029ac32a9f350508a565af683205cf99f25c896b07c07bc53a9517877ce8c' AGENT_MAIL_INTERVAL='120' '/home/ubuntu/mcp_agent_mail/.claude/hooks/check_inbox.sh'"
          }
        ]
      }
    ]
  }
}

{
  "_SETUP_INSTRUCTIONS": [
    "Copy this file to settings.json and replace placeholders:",
    "  YOUR_PROJECT_PATH -> Absolute path to your project",
    "  YOUR_AGENT_NAME   -> Your agent name (e.g., 'BlueMountain')",
    "  YOUR_BEARER_TOKEN -> Token for HTTP auth (or 'dev-token' for local dev)",
    "Then delete this _SETUP_INSTRUCTIONS block."
  ],
  "mcpServers": {
    "mcp-agent-mail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp/",
      "headers": { "Authorization": "Bearer YOUR_BEARER_TOKEN" }
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "uv run python -m mcp_agent_mail.cli file_reservations active YOUR_PROJECT_PATH" },
          { "type": "command", "command": "uv run python -m mcp_agent_mail.cli acks pending YOUR_PROJECT_PATH YOUR_AGENT_NAME --limit 20" }
        ]
      }
    ],
    "PreToolUse": [
      { "matcher": "Edit", "hooks": [ { "type": "command", "command": "uv run python -m mcp_agent_mail.cli file_reservations soon YOUR_PROJECT_PATH --minutes 10" } ] }
    ],
    "PostToolUse": [
      { "matcher": "mcp__mcp-agent-mail__send_message", "hooks": [ { "type": "command", "command": "uv run python -m mcp_agent_mail.cli list-acks --project YOUR_PROJECT_PATH --agent YOUR_AGENT_NAME --limit 10" } ] },
      { "matcher": "mcp__mcp-agent-mail__file_reservation_paths", "hooks": [ { "type": "command", "command": "uv run python -m mcp_agent_mail.cli file_reservations list YOUR_PROJECT_PATH" } ] }
    ]
  }
}

# Project-local Codex configuration
# NOTE: Top-level keys must appear BEFORE any [section] headers in TOML

# Notify hook for agent inbox reminders (fires on agent-turn-complete)
notify = ["/data/projects/mcp_agent_mail/.codex/hooks/notify_wrapper.sh"]

# MCP servers configuration
[mcp_servers.mcp_agent_mail]
url = "http://127.0.0.1:8765/api/"
# headers can be added if needed; localhost allowed without Authorization

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
.venv/
venv/
ENV/
env/

# Testing
.pytest_cache/
.pytest_out/
.coverage
htmlcov/
.tox/
*.cover

# Development
.git/
.github/
.vscode/
.idea/
.ruff_cache/
*.swp
*.swo
*~

# Database
*.db
*.db-shm
*.db-wal
*.sqlite
*.sqlite3

# Logs
*.log

# Environment
.env
.env.*
!.env.example

# Backups
backup_config_files/

# Documentation (keep only essential docs)
docs/
screenshots/
*.md
!README.md
!AGENTS.md
!project_idea_and_guide.md
!third_party_docs/*.md

# Docker
docker-compose.yml
Dockerfile

# Misc
.DS_Store
*.bak

OPENAI_API_KEY=sk-proj-...
GEMINI_API_KEY=AIza...
ANTHROPIC_API_KEY=sk-ant-...
DEEPSEEK_API_KEY=sk-a...
OPENROUTER_API_KEY=sk-or-v1-3...
GROK_API_KEY=xai-US...
LLM_CACHE_BACKEND=redis
LLM_CACHE_REDIS_URL=redis://hostname:6379/0
WORKTREES_ENABLED=0

# HTTP transport
HTTP_HOST=127.0.0.1
HTTP_PORT=8765
HTTP_PATH=/api/
HTTP_BEARER_TOKEN=
HTTP_RATE_LIMIT_ENABLED=false
HTTP_RATE_LIMIT_PER_MINUTE=60
HTTP_REQUEST_LOG_ENABLED=false
TOOLS_LOG_ENABLED=false
HTTP_OTEL_ENABLED=false
OTEL_SERVICE_NAME=mcp-agent-mail
OTEL_EXPORTER_OTLP_ENDPOINT=

# Database
DATABASE_URL=sqlite+aiosqlite:///./storage.sqlite3
DATABASE_ECHO=false

# Storage / Git authoring
STORAGE_ROOT=~/.mcp_agent_mail_git_mailbox_repo
GIT_AUTHOR_NAME=mcp-agent
GIT_AUTHOR_EMAIL=mcp-agent@example.com

# Attachments / images
INLINE_IMAGE_MAX_BYTES=65536
CONVERT_IMAGES=true
KEEP_ORIGINAL_IMAGES=false
ALLOW_ABSOLUTE_ATTACHMENT_PATHS=false

# CORS (HTTP app)
HTTP_CORS_ENABLED=false
HTTP_CORS_ORIGINS=
HTTP_CORS_ALLOW_CREDENTIALS=false
HTTP_CORS_ALLOW_METHODS=*
HTTP_CORS_ALLOW_HEADERS=*

# Background maintenance (file reservations cleanup)
FILE_RESERVATIONS_CLEANUP_ENABLED=false
FILE_RESERVATIONS_CLEANUP_INTERVAL_SECONDS=60

# Message Quotas
QUOTA_ENABLED=true
QUOTA_ATTACHMENTS_LIMIT_BYTES=500000000
QUOTA_INBOX_LIMIT_COUNT=10000
RETENTION_REPORT_ENABLED=true

CONTACT_AUTO_RETRY_ENABLED=true

source .venv/bin/activate

# Use bd merge for beads JSONL files
.beads/issues.jsonl merge=beads

#!/usr/bin/env bash
# Pre-commit guard against accidental secret commits.
#
# Activate per-clone with:
#     git config core.hooksPath .githooks
#
# Why this exists: signing-77c6e768.key was committed in a feature commit
# despite .gitignore having signing-*.key — someone used `git add -f`. This
# hook is a second layer that refuses the commit at the index level so even
# `git add -f` can't sneak a private key in.

set -euo pipefail

red()  { printf '\033[31m%s\033[0m\n' "$*" >&2; }
yel()  { printf '\033[33m%s\033[0m\n' "$*" >&2; }

# Resolve the actual gitdir. In a regular checkout this is `<repo>/.git`,
# but in a `git worktree`, `.git` is a *file* containing
# "gitdir: <path>" — a literal `[[ -f .git/MERGE_HEAD ]]` would always
# fail there because `.git/MERGE_HEAD` doesn't exist as a path under a
# file. `git rev-parse --git-dir` resolves both forms.
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null || echo .git)

# Skip merge commits and rebases — these don't represent "did the user
# mean to add this" decisions; the index is being assembled by git itself.
if [[ -f "$GIT_DIR/MERGE_HEAD" || -d "$GIT_DIR/rebase-merge" || -d "$GIT_DIR/rebase-apply" ]]; then
    exit 0
fi

# Files staged for this commit (added/modified/copied/renamed; excludes deletions)
mapfile -t staged < <(git diff --cached --name-only --diff-filter=ACMR)

if [[ ${#staged[@]} -eq 0 ]]; then
    exit 0
fi

violations=()

# 1. Filename-based blocklist — common private-key/secret naming conventions.
#    The patterns below are intentionally conservative: any tracked .pub file
#    is fine, but a .key (or .priv, or signing-XYZ without an explicit .pub
#    suffix) is rejected at commit time.
for path in "${staged[@]}"; do
    base=$(basename -- "$path")
    case "$base" in
        # Private key file extensions
        *.key|*.priv|*.pem|*.pfx|*.p12)
            # Allow .pub.key (some tools name pubs with .pub.key)
            if [[ "$base" != *.pub.key ]]; then
                violations+=("$path  (matches private-key filename pattern)")
            fi
            ;;
        # SSH private keys (no extension)
        id_rsa|id_dsa|id_ecdsa|id_ed25519)
            violations+=("$path  (matches SSH private-key filename)")
            ;;
        # Project-specific signing keys — Ed25519 seeds named signing-<hex>
        # Allow paired .pub files and revoked-signing-*.pub historical markers.
        signing-*|revoked-signing-*)
            if [[ "$base" != *.pub ]]; then
                violations+=("$path  (matches signing-* private-key naming convention)")
            fi
            ;;
        # Common secret bundles
        secrets.*|*-secret|*-secret.*|*.secret|*.secret.*)
            violations+=("$path  (matches secret-bundle filename pattern)")
            ;;
    esac
done

# 2. Content-based heuristics on small staged files (<=64 KB).
#    Catches tokens that don't have suspicious filenames.
#    Both the size check and the blob read use the *index* state so we're
#    inspecting exactly what would be committed, not whatever the working
#    tree happens to contain (those can diverge after `git add`).
for path in "${staged[@]}"; do
    size=$(git cat-file -s ":$path" 2>/dev/null || echo 0)
    [[ "$size" -gt 0 && "$size" -le 65536 ]] || continue

    blob=$(git show ":$path" 2>/dev/null || true)
    [[ -n "$blob" ]] || continue

    # Common provider token shapes (kept conservative to avoid noise)
    if grep -E -q '\b(sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{30,}|gho_[A-Za-z0-9]{30,}|ghs_[A-Za-z0-9]{30,}|AKIA[0-9A-Z]{16}|xox[abprs]-[A-Za-z0-9-]{20,})\b' <<<"$blob"; then
        violations+=("$path  (contains provider-token-shaped string)")
    fi

    # PEM private-key headers
    if grep -E -q -- '-----BEGIN (RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED |)PRIVATE KEY' <<<"$blob"; then
        violations+=("$path  (contains PEM private key header)")
    fi
done

if [[ ${#violations[@]} -gt 0 ]]; then
    red "✗ Pre-commit blocked: likely secret file(s) staged."
    for v in "${violations[@]}"; do
        red "    - $v"
    done
    yel "If a finding is a false positive, run:"
    yel "    git commit --no-verify"
    yel "But review the file first — the last leak was a real Ed25519 key."
    exit 1
fi

exit 0

name: Notify ACFS checksum monitor

on:
  push:
    branches: [main, master]
    paths:
      - 'install.sh'
      - 'scripts/install.sh'
  release:
    types: [published]
  workflow_dispatch:

jobs:
  dispatch:
    runs-on: ubuntu-latest
    steps:
      - name: Check if dispatch token is available
        id: check-token
        env:
          TOKEN: ${{ secrets.ACFS_REPO_DISPATCH_TOKEN }}
        run: |
          if [ -z "$TOKEN" ]; then
            echo "::notice::ACFS_REPO_DISPATCH_TOKEN not configured. Skipping dispatch."
            echo "has_token=false" >> $GITHUB_OUTPUT
          else
            echo "has_token=true" >> $GITHUB_OUTPUT
          fi

      - name: Dispatch to ACFS
        if: steps.check-token.outputs.has_token == 'true'
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.ACFS_REPO_DISPATCH_TOKEN }}
          repository: Dicklesworthstone/agentic_coding_flywheel_setup
          event-type: upstream-changed
          client-payload: |
            {"repo":"${{ github.repository }}","ref":"${{ github.ref }}","sha":"${{ github.sha }}","event":"${{ github.event_name }}"}

name: CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build-and-test:
    name: Lint, Type Check, Test (${{ matrix.os }})
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, macos-latest]

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python 3.14
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          allow-prereleases: true

      - name: Install uv
        shell: bash
        run: |
          curl -LsSf https://astral.sh/uv/install.sh | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH
          uv --version

      - name: Cache uv dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/uv
            .venv
          key: ci-uv-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
          restore-keys: |
            ci-uv-${{ runner.os }}-

      - name: Sync dependencies
        shell: bash
        run: |
          uv sync --dev

      - name: Lint (ruff)
        shell: bash
        run: |
          uv run ruff check

      - name: Type check
        shell: bash
        run: |
          uvx ty check

      - name: Run tests
        shell: bash
        env:
          PYTHONUTF8: "1"
        run: |
          uv run -m pytest -q

      - name: Smoke test am-run (Ubuntu only)
        if: matrix.os == 'ubuntu-latest'
        shell: bash
        run: |
          uv run python -m mcp_agent_mail.cli am-run ci-slot -- echo "ok"

      - name: Run performance benchmarks (Ubuntu only)
        if: matrix.os == 'ubuntu-latest'
        shell: bash
        env:
          PYTHONUTF8: "1"
          RUN_BENCHMARKS: "1"
          INSTRUMENTATION_ENABLED: "true"
        run: |
          uv run -m pytest tests/benchmarks/ -v -m benchmark --tb=short || true

      - name: CI Performance Regression Check (Ubuntu only)
        if: matrix.os == 'ubuntu-latest'
        shell: bash
        env:
          PYTHONUTF8: "1"
        run: |
          uv run -m pytest tests/benchmarks/test_ci_regression.py -v -m ci_regression --tb=short

      - name: Upload regression report artifact
        if: matrix.os == 'ubuntu-latest' && always()
        uses: actions/upload-artifact@v4
        with:
          name: regression-reports
          path: tests/benchmarks/regression_reports/
          if-no-files-found: ignore
          retention-days: 30

      - name: Upload benchmark results artifact
        if: matrix.os == 'ubuntu-latest' && always()
        uses: actions/upload-artifact@v4
        with:
          name: benchmark-results
          path: tests/benchmarks/results/
          if-no-files-found: ignore
          retention-days: 30

name: Nightly Maintenance

on:
  schedule:
    - cron: '17 3 * * *' # 03:17 UTC daily
  workflow_dispatch: {}

jobs:
  nightly:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          allow-prereleases: true
      - name: Install uv
        run: curl -Ls https://astral.sh/uv/install.sh | sh
      - name: Add uv to PATH
        run: echo "$HOME/.local/bin" >> $GITHUB_PATH
      - name: Cache uv
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/uv
            .venv
          key: nightly-uv-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
          restore-keys: |
            nightly-uv-${{ runner.os }}-
      - name: Sync dependencies (dev)
        run: uv sync --dev
      - name: Run migrations
        run: uv run python -m mcp_agent_mail.cli migrate
      - name: List projects
        run: uv run python -m mcp_agent_mail.cli list-projects --include-agents

# installer-notify.yml
# Copy this to .github/workflows/ in your project
# Notifies ACFS when install.sh changes
#
# Setup:
# 1. Create a GitHub PAT with `repo` scope
# 2. Add it as ACFS_DISPATCH_TOKEN secret in your repo
# 3. Copy this file to .github/workflows/

name: Notify ACFS of Installer Change

on:
  push:
    branches: [main, master]
    paths:
      - 'install.sh'
      - 'scripts/install.sh'
      - '**/install.sh'
  pull_request:
    branches: [main, master]
    paths:
      - 'install.sh'
      - 'scripts/install.sh'
      - '**/install.sh'

concurrency:
  group: installer-notify-${{ github.ref }}
  cancel-in-progress: true

jobs:
  notify-acfs:
    # Only notify on push to main, not PRs
    if: github.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Compute installer SHA256
        id: checksum
        run: |
          # Find the installer file
          if [ -f install.sh ]; then
            INSTALLER_PATH="install.sh"
          elif [ -f scripts/install.sh ]; then
            INSTALLER_PATH="scripts/install.sh"
          else
            echo "No installer found"
            exit 1
          fi

          SHA256=$(sha256sum "$INSTALLER_PATH" | cut -d' ' -f1)
          echo "sha256=$SHA256" >> $GITHUB_OUTPUT
          echo "Computed SHA256: $SHA256"

      - name: Notify ACFS
        uses: peter-evans/repository-dispatch@v3
        with:
          token: ${{ secrets.ACFS_DISPATCH_TOKEN }}
          repository: Dicklesworthstone/agentic_coding_flywheel_setup
          event-type: installer-updated
          client-payload: |
            {
              "tool": "${{ github.event.repository.name }}",
              "repo": "${{ github.repository }}",
              "commit": "${{ github.sha }}",
              "new_sha256": "${{ steps.checksum.outputs.sha256 }}",
              "ref": "${{ github.ref }}",
              "actor": "${{ github.actor }}"
            }

      - name: Log notification
        run: |
          echo "::notice::Notified ACFS about installer change"
          echo "Repository: ${{ github.repository }}"
          echo "Commit: ${{ github.sha }}"
          echo "SHA256: ${{ steps.checksum.outputs.sha256 }}"

  # Validate installer syntax on PRs
  validate-installer:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install shellcheck
        run: sudo apt-get update && sudo apt-get install -y shellcheck

      - name: Shellcheck installer
        run: |
          EXIT_CODE=0
          for script in install.sh scripts/install.sh; do
            if [ -f "$script" ]; then
              echo "Checking $script..."
              shellcheck "$script" || EXIT_CODE=1
            fi
          done
          exit $EXIT_CODE

name: Release

on:
  push:
    tags:
      - 'v*.*.*'

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      packages: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'
          allow-prereleases: true

      - name: Install uv
        run: curl -Ls https://astral.sh/uv/install.sh | sh

      - name: Add uv to PATH
        run: echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Cache uv
        uses: actions/cache@v4
        with:
          path: |
            ~/.cache/uv
            .venv
          key: release-uv-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'uv.lock') }}
          restore-keys: |
            release-uv-${{ runner.os }}-

      - name: Sync dependencies (dev)
        run: uv sync --dev

      - name: Ruff Lint
        run: uv run ruff check --output-format=github

      - name: Ty Type Check
        run: uvx ty check

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata (tags, labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository }}
          tags: |
            type=raw,value=latest
            type=ref,event=tag

      - name: Set up Buildx
        uses: docker/setup-buildx-action@v3

      - name: Set up QEMU (multi-arch)
        uses: docker/setup-qemu-action@v3

      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          platforms: linux/amd64,linux/arm64
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v2
        with:
          generate_release_notes: true
          draft: false
          prerelease: ${{ contains(github.ref_name, '-') }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
.pybuilder/
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
.python-version

# pipenv
Pipfile.lock

# poetry
poetry.lock

# pdm
.pdm.toml
.pdm-python
.pdm-build/

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug/

# PyCharm
.idea/

# UV
.uv/

# OS
.DS_Store
.DS_Store?
._*
.Spotlight-V100
.Trashes
ehthumbs.db
Thumbs.db

# Project specific
storage/
query_logs/
*.log
sec_filings.db
sec_insiders.db
sec_insiders.db-shm
sec_insiders.db-wal
file_analysis_*.json
finviz_test_results_*.json
tests/e2e/logs/
presentation_test_results*.json
*.bak

# SQLite temp directory
.sqlite_temp/


*.db
*.sqlite3
*.db-journal
*.db-shm
*.db-wal
*.db-shm.backup
*.db-wal.backup
*.db.new
*.db-shm.backup
*.db-wal.backup
*.db.new
coverage.json
logs/
.sqlite_temp/
.ruff_cache/
.mypy_cache/
.pytest_cache/
.coverage/
.coverage.*
.coverage.xml
.coverage.json
.coverage.html
.coverage.xml
.coverage.json
.coverage.html
tmp
.mypy_errors_by_file.txt
.index_migration_errors_*.json
.artifacts*
run_server_clean.sh.txt
vendor/*

# Benchmark results - exclude transient JSON output files
benchmarks/tmp_*
benchmarks/results/**/*.json
benchmarks/**/*.json
tests/benchmarks/results/**/*.json
data/baselines/*
*.sqlite3
.env
.pytest_out/*
storage.sqlite3-shm
storage.sqlite3-wal
storage.sqlite3.old
*.bak.*
screenshots/gif_canvas_frames
screenshots/gif_canvas_frames_2k
screenshots/renamed
screenshots/gif_frames
temp.lock
temp.lock.owner.json
server.lock
server.pid
archived_mailbox_states/
# Share export test output
out/

# Cryptographic signing keys (Ed25519 key pairs for bundle signing)
signing-*.key
signing-*.pub

# Generic private-key / secret patterns — belt-and-suspenders.
# A real Ed25519 signing key was committed once via `git add -f` despite
# signing-*.key being above; .githooks/pre-commit blocks the same mistake at
# the index level, and these patterns block at the working-tree level.
*.key
!*.pub.key
*.priv
*.pem
*.pfx
*.p12
id_rsa
id_dsa
id_ecdsa
id_ed25519
secrets.*
*-secret
*-secret.*

# IDE settings
.vscode/
.idea/

# Local agent configuration directories (per-user, not project config)
# We track .template files as examples; actual settings.json is user-specific
.claude/
!.claude/settings.json.template
.codex/
!.codex/config.toml
.cursor/
.gemini/

# Backup files
*.backup
AGENTS.md.backup

# SQLite WAL/SHM temp files (test databases)
test.sqlite3-shm
test.sqlite3-wal

# bv (beads viewer) local config and caches
.bv/
tests/benchmarks/regression_reports/

# Ephemeral files
a.out
.beads/.bv.lock

# Ephemeral/temporary files (agent workflow artifacts)
RESEARCH_FINDINGS.md
TOON_INTEGRATION_BRIEF.md
cov_*.out
rustc-ice-*.txt
*.snap.new
sweep_*.png
test_screenshot.png

# Claude Code local settings (contains secrets)
.claude/settings.local.json

# Literal tilde directory (created by agent mail git mailbox init)
~/

# SQLite activity lock files
*.activity.lock

# OpenCode config (user-local; contains bearer tokens)
/opencode.json

{
  "mcpServers": {
    "mcp-agent-mail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/api/",
      "headers": {
        "Authorization": "Bearer YOUR_BEARER_TOKEN"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-agent-mail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/api/",
      "headers": { "Authorization": "Bearer YOUR_BEARER_TOKEN" },
      "note": "Import or configure this server in Cline's MCP settings"
    }
  }
}

{
  "mcpServers": {
    "mcp-agent-mail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/api/",
      "headers": { "Authorization": "Bearer YOUR_BEARER_TOKEN" }
    }
  }
}

services:
  agent-mail:
    build: .
    environment:
      HTTP_HOST: "0.0.0.0"
      STORAGE_ROOT: "/data/mailbox"
      LOG_RICH_ENABLED: "true"
    ports:
      - "8765:8765"
    volumes:
      - agent_mail_data:/data
      # Optional: mount a local .env file (read-only) for config
      - ./.env:/app/.env:ro
volumes:
  agent_mail_data:

{
  "mcpServers": {
    "mcp-agent-mail": {
      "type": "http",
      "url": "http://127.0.0.1:8765/api/",
      "headers": { "Authorization": "Bearer YOUR_BEARER_TOKEN" }
    }
  }
}

# Example capability mapping for MCP agents.
# Copy to deploy/capabilities/agent_capabilities.yaml and populate with real data.

agents:
  - name: BlueLake
    project: /abs/path/backend
    capabilities:
      - messaging
      - read
      - ack
  - name: GreenCastle
    project: /abs/path/backend
    capabilities:
      - messaging
      - write
      - claims
      - repository
  - name: OpsBot
    project: /abs/path/backend
    capabilities:
      - workflow
      - contact
      - messaging
      - summarization

# Example: pass these capabilities to an MCP client (pseudo-code)
#
# allowed = lookup_capabilities(agent_name, project)
# client = MCPClient(..., metadata={"allowed_capabilities": allowed})

{
  "agents": [
    {
      "name": "BlueLake",
      "project": "/abs/path/backend",
      "capabilities": ["messaging", "read", "ack", "summarization"]
    },
    {
      "name": "GreenCastle",
      "project": "/abs/path/backend",
      "capabilities": ["messaging", "write", "claims", "repository", "workflow"]
    },
    {
      "name": "OpsBot",
      "project": "/abs/path/backend",
      "capabilities": ["workflow", "contact", "messaging", "summarization", "infrastructure"]
    }
  ]
}

"""Sample gunicorn configuration for MCP Agent Mail."""

import multiprocessing
from pathlib import Path

# Bind to same interface/port as default settings; override via GUNICORN_CMD_ARGS if needed.
bind = "0.0.0.0:8765"

# Use number of workers proportional to cores; uvicorn workers handle async FastAPI app.
workers = multiprocessing.cpu_count() * 2 + 1
worker_class = "uvicorn.workers.UvicornWorker"

# Graceful timeouts to match long running tasks.
keepalive = 5
graceful_timeout = 60
timeout = 120

# Location for PID/log files (customize as desired).
pidfile = str(Path("/var/run/mcp-agent-mail/gunicorn.pid"))
errorlog = "-"  # stderr
accesslog = "-"  # stdout
loglevel = "info"

# Optional: forward standard proxy headers.
forwarded_allow_ips = "*"

/var/log/mcp-agent-mail/*.log {
    weekly
    rotate 7
    size 50M
    compress
    delaycompress
    missingok
    notifempty
    create 0640 appuser appuser
    sharedscripts
    postrotate
        systemctl kill -s USR1 mcp-agent-mail.service >/dev/null 2>&1 || true
    endscript
}

groups:
  - name: mcp-agent-mail
    interval: 30s
    rules:
      - alert: MCPHighToolErrorRate
        expr: |
          sum by (tool) (rate(mcp_tool_errors_total[5m]))
            /
          sum by (tool) (rate(mcp_tool_calls_total[5m]))
          > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Tool {{ $labels.tool }} has an elevated error rate"
          description: |
            Over the last 5 minutes, tool {{ $labels.tool }} exceeded a 5% error ratio.
            Investigate recent changes, review capability assignments, or consider surfacing a macro.

[Unit]
Description=MCP Agent Mail HTTP Service
After=network.target postgresql.service

[Service]
EnvironmentFile=/etc/mcp-agent-mail.env
Type=simple
WorkingDirectory=/opt/mcp-agent-mail
ExecStart=/usr/bin/uvicorn mcp_agent_mail.http:build_http_app --factory --host 0.0.0.0 --port 8765
Restart=always
RestartSec=5
User=appuser
Group=appuser
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

version: '3.8'
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: agent_mail
      POSTGRES_USER: agent
      POSTGRES_PASSWORD: agent
    volumes:
      - pgdata:/var/lib/postgresql/data
  server:
    build: .
    ports:
      - "8765:8765"
    environment:
      DATABASE_URL: postgres+asyncpg://agent:agent@db:5432/agent_mail
      STORAGE_ROOT: /data/archive
      TOOL_METRICS_EMIT_ENABLED: "true"
      TOOL_METRICS_EMIT_INTERVAL_SECONDS: "120"
    volumes:
      - archive:/data/archive
    depends_on:
      - db
volumes:
  pgdata:
  archive:

# syntax=docker/dockerfile:1.7

# --------------------------------------------------------------------------
# Stage 1: build the toon_rust encoder (`tru`).
#
# The Python runtime can shell out to a `tru` binary to encode payloads in
# TOON format (`format='toon'` on any tool call). Without `tru` on $PATH the
# code path silently falls back to JSON. The image used to ship without a
# TOON encoder at all, so every `format='toon'` request from a container
# deployment was silently downgraded — see issue #163.
#
# We build the encoder from source pinned to a specific ref (default: main)
# so the container's TOON output matches a known toon_rust commit, then copy
# the single binary into the runtime stage. The crate name on cargo install
# is `tru` but the [[bin]] target name is `toon`, so we rename on copy.
# (Renaming the target upstream is tracked separately; this Dockerfile is
# tolerant of either name today.)
# --------------------------------------------------------------------------
#
# toon_rust pins nightly via rust-toolchain.toml. Install rustup into a
# stable Debian base, let the toolchain file drive channel selection — that
# way this builder stage tracks whatever toon_rust pins without us having
# to bump a hard-coded image tag every nightly cycle.
FROM debian:bookworm-slim AS tru-builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl build-essential git ca-certificates pkg-config && \
    rm -rf /var/lib/apt/lists/*

# Install rustup with a minimal profile; the project's rust-toolchain.toml
# will pull the right channel + components on first `cargo` invocation.
ENV RUSTUP_HOME=/usr/local/rustup \
    CARGO_HOME=/usr/local/cargo \
    PATH=/usr/local/cargo/bin:$PATH
RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
    | sh -s -- -y --default-toolchain none --profile minimal --no-modify-path

ARG TOON_RUST_REPO=https://github.com/Dicklesworthstone/toon_rust.git
ARG TOON_RUST_REF=main

# Resolve ${TOON_RUST_REF} as a branch name, tag, or full 40-char commit
# SHA. We can't use `git clone --depth 1 --branch <ref>` because `--branch`
# refuses bare commit SHAs ("Remote branch <sha> not found in upstream
# origin"), which would prevent pinning the encoder to a specific upstream
# commit via `--build-arg TOON_RUST_REF=<sha>`. Instead: init an empty
# repo, fetch *just* the requested ref with depth 1, then check it out.
#
# Caveat: GitHub's smart-http upload-pack
# (uploadpack.allowReachableSHA1InWant) only resolves *full* 40-char SHAs
# in the want list — abbreviated SHAs error out with "couldn't find remote
# ref". Pass the full SHA, a branch, or a tag.
RUN git init -q /build/toon_rust && \
    cd /build/toon_rust && \
    git remote add origin "${TOON_RUST_REPO}" && \
    git fetch --depth 1 origin "${TOON_RUST_REF}" && \
    git checkout -q FETCH_HEAD && \
    cargo build --release && \
    # The [[bin]] target is currently named "toon" but mcp_agent_mail expects
    # the binary on $PATH as `tru`. Copy under the expected name. Fall back
    # to whichever target file exists so this stage stays valid if/when the
    # upstream [[bin]] target is renamed to `tru`.
    install -m 0755 \
        "$(test -f target/release/toon && echo target/release/toon || echo target/release/tru)" \
        /tru && \
    strip /tru

# --------------------------------------------------------------------------
# Stage 2: Python application runtime.
# --------------------------------------------------------------------------
FROM python:3.14-slim AS base

ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    UV_SYSTEM_PYTHON=1 \
    PYTHONPATH=/app/src

RUN apt-get update && apt-get install -y --no-install-recommends \
    curl git ca-certificates && \
    rm -rf /var/lib/apt/lists/*

# Install uv to a shared path so it remains available after USER switch
RUN curl -LsSf https://astral.sh/uv/install.sh | UV_UNMANAGED_INSTALL=/usr/local/bin sh

# Install the TOON encoder built in stage 1 so `format='toon'` requests are
# served by the real toon_rust encoder rather than silently falling back to
# JSON. /usr/local/bin is on $PATH for all users including the unprivileged
# appuser below.
COPY --from=tru-builder /tru /usr/local/bin/tru

WORKDIR /app

# Copy project metadata and sync deps first for better caching.
# README.md is required by hatchling since pyproject.toml references it.
COPY pyproject.toml README.md ./
# Install runtime deps only — the project itself (hatchling wheel from
# src/mcp_agent_mail) can't be built yet because src/ isn't present, so defer
# its install with --no-install-project to keep this dependency layer cached.
RUN uv sync --no-dev --no-install-project

# Copy source, then install the project itself now that src/ exists.
COPY src ./src
RUN uv sync --no-dev

# Defaults suitable for container
ENV HTTP_HOST=0.0.0.0 \
    STORAGE_ROOT=/data/mailbox

EXPOSE 8765
VOLUME ["/data"]

# Create non-root user and set ownership on data dir
RUN adduser --disabled-password --gecos "" --uid 10001 appuser && \
    mkdir -p /data/mailbox && chown -R appuser:appuser /data /app
USER appuser

# Mark the mounted mailbox directory as a git safe.directory so git does not
# refuse to operate when the host volume is owned by a different uid than
# appuser (uid 10001) — a common Docker-on-Linux scenario. Without this, git
# treats /data/mailbox (and every per-project repo created underneath it) as
# "dubious ownership" and falls back to a compat mode that fails with
# "Unknown parameter: --cached" on diff/status operations.
#
# git safe.directory entries must be absolute paths (no glob patterns other
# than the special catch-all '*'). Since per-project repos live at
# /data/mailbox/<slug>, we need the catch-all to cover the container's
# dynamically-created subdirectories. This is safe here because the user has
# explicitly mounted the volume into this dedicated container.
# See: https://github.com/Dicklesworthstone/mcp_agent_mail/issues/143
RUN git config --global --add safe.directory /data/mailbox && \
    git config --global --add safe.directory '*'

# Healthcheck
HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=5 \
  CMD curl -fsS http://127.0.0.1:8765/health/liveness || exit 1

# Run the HTTP server via the prebuilt venv (avoids uv overhead at startup)
CMD ["/app/.venv/bin/python", "-m", "mcp_agent_mail.cli", "serve-http"]

name = "mailbox-share"

[site]
bucket = "./out/mailbox-share"

[build]
command = "uv run python -m mcp_agent_mail.cli share export --output ./out/mailbox-share --zip"

[vars]
SCRUB_PRESET = "standard"
INLINE_THRESHOLD = "65536"
DETACH_THRESHOLD = "262144"

# Usage:
#   uv sync --frozen
#   wrangler pages deploy ./out/mailbox-share --project-name mailbox-share

name: Static Mailbox Export

on:
  workflow_dispatch:
  schedule:
    - cron: '0 6 * * 1'

jobs:
  export-mailbox:
    runs-on: ubuntu-latest
    env:
      DATABASE_URL: ${{ secrets.MAILBOX_DATABASE_URL }}
      STORAGE_ROOT: ${{ secrets.MAILBOX_STORAGE_ROOT }}
      APP_ENVIRONMENT: ci
    steps:
      - uses: actions/checkout@v4

      - name: Install UV
        uses: astral-sh/setup-uv@v1

      - name: Sync dependencies
        run: uv sync --frozen

      - name: Generate static bundle
        run: |
          uv run python -m mcp_agent_mail.cli share export \ 
            --output ./out/mailbox-share \ 
            --inline-threshold 65536 \ 
            --detach-threshold 262144 \ 
            --scrub-preset standard \ 
            --zip

      - name: Upload mailbox artifact
        uses: actions/upload-artifact@v4
        with:
          name: mailbox-share
          path: out/mailbox-share.zip

      - name: Publish HOW_TO_DEPLOY
        if: github.ref == 'refs/heads/main'
        uses: actions/upload-artifact@v4
        with:
          name: mailbox-deployment-guide
          path: out/mailbox-share/HOW_TO_DEPLOY.md

{
  "mcpServers": {
    "mcp-agent-mail": {
      "httpUrl": "http://127.0.0.1:8765/api/",
      "headers": { "Authorization": "Bearer YOUR_BEARER_TOKEN" }
    }
  }
}

m0ExUyPijqQmySaP1wncJf2duRL8u9P9BmkajMyFgUc=