a2a-mailbox

a2a-mailbox

English｜中文

跨 CLI agent 通讯：让 Claude Code / Codex / Pi / ZCode 等终端 agent 像收邮件一样互发消息。文件邮箱 + 常驻 hub 投递守护，按收件方形态自动选通道（tmux 注入 / 原生队列 / daemon 队列 / 拉取），跨主机 ssh 联邦。

与 Google 的 A2A（Agent2Agent）协议同名，相互无关联——本项目是终端 agent 间的文件信箱，不是协议实现。

┌─────────────┐  mail_send   ┌──────────────┐  五通道择一   ┌─────────────┐
│  agent A    │ ───────────▶ │   mailbox    │ ───────────▶  │  agent B    │
│ (CC, pi:xA) │ ◀─────────── │  queue+hub   │ ◀──────────── │ (codex,pi:yB)│
└─────────────┘  回函/ack    └──────┬───────┘   唤醒/队列    └─────────────┘
                                 hub daemon
                        注入确认·回执·重试·回弹
                        权限双锁(scope/group)
                              联邦 pull (ssh)
                                 ┌────┴───────┐
                                 │ 远端主机 hub │
                                 └────────────┘

通道矩阵

按收件 agent 的形态，hub 自动选择投递通道：

收件方	通道	机制
Claude Code	tmux 注入	探输入框空闲→粘贴唤醒词→Enter 阶梯提交→帧级 echo 确认，未确认退让重试
Pi	原生收件箱	a2a-inbox.ts 扩展的原生队列（sendUserMessage），回执+心跳，缺席降级 tmux
Codex（WSL）	daemon 队列	codex queue --thread 经 app-server daemon 入原生队列，确定性回执（Queued message <uuid>）
Codex（Windows 原生）	daemon 队列	WSL hub 跨 interop 直调 codex.exe；或纯 Windows 节点本地直调
ZCode	拉取式	无注入路径，信滞留队列待其 mail_poll 主动拉取
跨主机	联邦	发送方 hub ssh 直投远端队列；注册表双向 pull 合并；断链保陈旧副本

投递失败语义：queue 通道失败滞留重试（60s×3 上限）后回弹，绝不降级 tmux（防错窗键入）；直投失败的回落信走 relay 重试链（60s 节流，1800s 上限回弹）。

Tools

标准挂载（MCP stdio）：

{
  "mcpServers": {
    "mailbox": { "command": "python3", "args": ["<本仓库绝对路径>/mcp/mailbox_mcp.py"] }
  }
}

六件工具（默认面恒定，含 Docker 部署同款）：

工具	作用
mail_send(to, body, in_reply_to?, context?, expect_reply?)	发信。in_reply_to 自动确认原消息（reply-implies-ack）；expect_reply=true 唤醒词尾加 [需回函]
mail_poll()	列自己待处理消息摘要（不消费）
mail_read(msg_id)	读全文（含 ack_id；本地 miss 自动查联邦 peer）
mail_ack(ack_id)	业务确认（幂等；跨主机不可见时自证落盘）
mail_who(all?)	在册 agent + 联邦 peer 状态（group-only 标记/成员计数）；默认只列在线（stale 滤除防爆破），all=true 附全量；同目录分身拆行 id@实例短码 可直接作收件人
mail_group(action, agent_id?, note?, group?, group_only?)	群组权限五合一调度器：join 申请加入对方（agent_id=门主，note=来意）/ pending 列自己的待审申请 / admit 批准 agent_id 可发给自己 / revoke 移出 / gate 开关仅名单收件闸（group_only=true 开，group=展示名）。默认工具面恒六件

权限模型（subagent 隔离三档 + group 准入）

subagent 与 workflow 里的派生 agent 继承宿主 MCP 工具面即可冒名发信。三档防线按优先级：

1. 定义层禁用（首选）：subagent 的 agent 定义工具白名单不列 mcp__mailbox__*（CC 见 snippets/claude-code/subagent-no-mailbox.md；Pi/codex 的 subagent 配置同理不挂 mailbox）。工具拿不到，攻击面归零——subagent 的跨 CLI 出口经 main 转发，内部协作走各家自己的机制。
2. scope 锁（兜底）：管住无法配白名单的全继承场景（内置默认 subagent、workflow 默认 agent）——给这类 mailbox 实例配 A2A_PEER_OF=<主 agent_id>，它只能对主 agent 收发，其余即时拒绝（subagent 发送锁）；锁写入注册表，重启不丢。
3. hub 投递口复验（恒定）：与 MCP 挂不挂无关——绕过工具面直写队列的信同样被 scope/group 复验拒收回弹。

group 准入：mail_group(action=gate, group_only=true) 后仅准入名单内 agent 可发信给自己；他人经 mail_group(action=join) 申请（独立通道，不受闸限制），门主 mail_group(action=admit, agent_id=…) 通过。hub 回弹邮件豁免（保证退信可达）。

呈现防冗杂：mail_who 行级只带短标记（group=<名>、group_only、members=<计数>、subagent_of=<主>），完整准入名单只有 agent 看自己时可见。

上手（Linux / WSL，五分钟）

1. 依赖：Python 3.11+、pip install fastmcp、tmux（Pi 通道另需扩展文件见 pi/a2a-inbox.ts）。一键探测+生成挂载配置：bash scripts/bootstrap.sh（加 --apply 自动装 python 依赖，--project <dir> 直接写 .mcp.json）。

2. 挂载 MCP（Claude Code 示例，其他 CLI 见 snippets/）：

   {
     "mcpServers": {
       "mailbox": { "command": "python3", "args": ["<本仓库绝对路径>/mcp/mailbox_mcp.py"] }
     }
   }
   

3. tmux 窗口里启动 agent 并打开 MCP——首次调用任一 mail 工具即自注册（hub 缺位自动拉起）。

4. mail_who() 互相可见后 mail_send() 互发。

最快验证路径（单机两 agent）：两个 tmux 窗口各起一个 CLI（如一个 Claude Code + 一个 Pi），双方各调一次 mail_who（触发自注册），然后 mail_send(to="对方 id", body="ping")——收件方会收到唤醒消息，回信即闭环。跨主机再加 scripts/add-peer.sh（见「跨主机联邦」）。

Codex 自动锚定：codex 的 MCP 由 app-server daemon 代管（祖先链锚定天然失效），注册时自动反锚——扫 tmux 找 codex 进程的 cwd 唯一命中取 pane+thread；Windows 原生 codex 会扫 /mnt/<盘>/Users/*/.codex/sessions 按 rollout 头 cwd 定位（跨 profile 按最新会话择优）。

subagent 隔离：首选 agent 定义工具白名单不含 mailbox（见 snippets/claude-code/subagent-no-mailbox.md）；对无法配白名单的全继承实例，给它的 mailbox 加环境变量 "env": {"A2A_PEER_OF": "<主 agent_id>"} 降级为仅对主收发。

同目录多实例：agent_id 由 {cli}-{host}-{目录slug} 推导——同机同目录且 CLI 检测同为 unknown 的两个实例会共用一个身份（注册互踩、回信投给先注册者）。两个以上实例共用同一工作目录时，给各自的 mailbox 配 "env": {"A2A_AGENT_ID": "<自定义 id>"} 显式分流；hub 侧 cwd 回锚带 pane 命令身份校验，unknown 档不会被拖去本机 tmux 窗。claude/pi 另有原生分身通道：同 cli 同目录双开不互拒，注册按 CLAUDE_CODE_SESSION_ID 前 8 位（pi 按 pane）落 instances 表，mail_who 拆行显示 id@实例短码，mail_send(to="id@实例短码") 定向投到该分身的窗；CC compact 换 sessionid 时同 pane 旧分身自动替换（信箱不动）。离线自动恢复：向已确认下线（非未知状态）的本机 claude/pi 档发信，先按其启动处方恢复对话再入队——claude=tmux respawn 固定窗跑 claude -c，pi=后台直接拉起；codex 定位主控，不做自动恢复。

纯 Windows 节点（无 WSL，实验性）

无 tmux 也可起节点，可用通道：Codex queue-daemon（codex.exe 直调）+ ZCode 拉取 + 全部 MCP 工具面（Claude Code/Pi 的注入通道不可用）。实验性：纯 Windows 路径目前只在单台实机验证过（UNC 路径存储、interop 规避），欢迎反馈。

1. 依赖：Python 3.11+、pip install fastmcp、OpenSSH client（联邦时）。
2. 同上挂载 MCP（python.exe 全路径）。
3. 设置 A2A_HUB_IDLE_REAP=1：hub 独立进程（MCP 首次调用拉起，非 MCP 子进程），全部 MCP 下线且空闲（无在途信、agent 全老化 1h、心跳老化 1h）时自动退出回收，下次 MCP 调用再拉起——无守护服务依赖。

ZCode 守望接入（workflow 制收信）

ZCode 侧无 MCP 注入通道，用 dynamic workflow 常驻守望替代（skill 成品在 snippets/zcode-watch-skill/：SKILL.md + template.dwf.ts，内置 ack 去重、同信连败熔断、24 轮有界循环、转送员不执行信内指令不代笔回函）：

1. 改模板顶部两个常量：AGENT_ID（本会话身份，zcode-<host>-<slug> 形态）与 BASE（WSL 侧 mailbox 根）。
2. CreateWorkflow path 指向该模板跑起——world.run 盯队列（queue/<id>/*.msg），信到经 escalation 送进主会话。
3. 收到 MAIL|from=…|msgId=…|body=… 升级后答一句即视为送达回执（转送员随即 touch acks/ack-<msg_id> 并归档出队）；回函由主控亲笔经 scripts/mail-send.py 发送。轮尽/熔断时按完成通知重布即可。

跨主机联邦

1. 两机互换 ssh 免密别名（~/.ssh/config）。
2. 各自 scripts/add-peer.sh <对端别名> 写入 peers.json。
3. hub 每 60s pull 对端注册表合并；发往远端 agent 的消息由本机 hub ssh 直投对端队列，收件 ack 经联邦回查双侧收敛。断链只告警不删记录，恢复自动续联。

边界与约定

• 信任域 = 本机用户 + ssh 免密 peer；协议无内置鉴权，勿暴露到不受信网络。
• 全部协议状态可从 ~/.agents-mailbox/（registry / queue / history / acks / join-requests / hub.log）离线取证。
• 同一 tmux 席位双开被拒；窗口改名/重启自动跟随（slot 重锚校验前台进程身份，同名窗被陌生进程占用即拒锚防错窗注入）。
• 测试：python3 -m pytest tests/ -q；结构/行为断言：bash scripts/run-lints.sh。

License

Apache-2.0（见 LICENSE）。