ADR-0181proposed

AT Protocol Mail Adapter for Capability Port

Status: proposed
Date: 2026-02-28
Updated: 2026-02-28
Deciders: Joel Hooks
Related: ADR-0169 (CLI capability contracts), ADR-0172 (MCP mail adoption)

Context

ADR-0169 is now shipped through phase 4, with mail running through the capability registry/runtime via mcp-agent-mail.

ADR-0172 shipped MCP Agent Mail end-to-end and established stable operations for:

  • identity registration
  • inbox/send/read
  • file reservations
  • loop-worker coordination

AT Protocol mail remains a valid evolution path, but it is materially different work:

  • lexicon design and versioning for mail + reservations
  • PDS auth/identity model for agent writes
  • parity guarantees vs current MCP semantics
  • migration/rollback safety for active agent workflows

Bundling that into ADR-0169 muddies scope and completion criteria.

Decision

Treat AT Protocol mail adapter work as its own ADR track.

  • ADR-0169 remains shipped (capability contract rollout complete through phase 4).
  • mcp-agent-mail remains the production default adapter.
  • AT Proto adapter work is tracked and accepted/rejected independently under this ADR.

Entry Criteria for Implementation

Before implementation starts, require all of:

  1. Lexicon readiness — stable draft for mail thread, message, reservation, and release records.
  2. Identity/auth model — clear mapping from joelclaw agents to AT Proto identities with write permissions.
  3. Parity matrix — command-level behavior parity documented for status/register/send/inbox/read/reserve/release/locks/search.
  4. Rollback plan — one-command adapter fallback to mcp-agent-mail with no CLI surface change.

Entry-criteria artifacts (drafted 2026-02-28)

Implementation Shape (when approved)

  • Add atproto-pds adapter implementing the same MailPort contract.
  • Gate via capability config only:
[capabilities.mail]
enabled = true
adapter = "atproto-pds"
 
[capabilities.mail.adapters.atproto-pds]
endpoint = "http://localhost:3000"
lexicon = "dev.joelclaw.agent.mail"
timeout_ms = 5000
  • Keep joelclaw mail UX and envelopes unchanged.
  • Add adapter parity tests and failure-mode coverage.

Consequences

  • Scope clarity: capability rollout stays closed; AT Proto exploration is explicit.
  • Lower operational risk: no accidental destabilization of shipped mail workflows.
  • Better ADR hygiene: lifecycle states map to real implementation boundaries.

Current State

  • No AT Proto adapter implementation in production path yet.
  • This ADR exists to approve/reject that work independently from ADR-0169.
  • Entry-criteria planning artifacts are now drafted under docs/decisions/0181-artifacts/ (no adapter code yet).