agent-mailbox 0.5.0__tar.gz

agent_mailbox-0.5.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+on:
+  push: { branches: [main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: "1"
+      PYTHONIOENCODING: utf-8
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with: { python-version: "${{ matrix.python }}" }
+      - run: pip install -e ".[dev]"
+      - run: ruff check src tests
+      - run: pytest

agent_mailbox-0.5.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Build sdist and wheel
+        run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # Trusted Publisher 必需：OIDC token 而非 API token，无需邮箱验证密码
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # 无 username/password —— 走 Trusted Publisher（GitHub OIDC）

agent_mailbox-0.5.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.test-mail/
+dist/
+.env
+.test-mail2/
+.mimosa/

agent_mailbox-0.5.0/Dockerfile

@@ -0,0 +1,17 @@
+# agent-mailbox MCP server — starts over stdio by default.
+# Glama introspection: server must start and respond to MCP initialize over stdio.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+# Default mail root inside container; mount a volume to persist.
+ENV AGENT_MAIL_HOME=/data
+VOLUME ["/data"]
+
+# stdio transport (default). Glama runs this and speaks MCP over stdio.
+ENTRYPOINT ["agent-mailbox"]

agent_mailbox-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NoFox Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_mailbox-0.5.0/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.5
+Name: agent-mailbox
+Version: 0.5.0
+Summary: Give every local AI agent its own mailbox — one MCP server, register once, message any agent on this machine.
+Project-URL: Homepage, https://github.com/polaris-smart/agent-mailbox
+Project-URL: Issues, https://github.com/polaris-smart/agent-mailbox/issues
+Author: polaris-smart
+License: MIT
+License-File: LICENSE
+Keywords: agent,local-first,mailbox,mcp,message,multi-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: mcp>=2.1
+Provides-Extra: dev
+Requires-Dist: pytest-timeout>=2.4; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# agent-mailbox
+
+[![polaris-smart/agent-mailbox MCP server](https://glama.ai/mcp/servers/polaris-smart/agent-mailbox/badges/score.svg)](https://glama.ai/mcp/servers/polaris-smart/agent-mailbox)
+[![npm](https://img.shields.io/npm/v/agent-mailbox)](https://www.npmjs.com/package/agent-mailbox)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Give every AI agent its own mailbox.** One stdio MCP server. Zero daemons. One JSON file per message. Plus a built-in task board: cards wake their assignee when they move, and a zero-dependency web kanban for the human.
+
+> **📊 Production-proven**: 1,787 messages across 5 agents (Claude Code, Hermes, Codex-based, webhook wake) in 17 days of daily multi-agent software development — 105 messages/day, zero data loss.
+
+Other docs: [中文](README.zh-CN.md) · [Español](README.es.md) · [Português](README.pt-BR.md) · [Français](README.fr.md) · [Русский](README.ru.md)
+
+## Why not just use MCP / Slack / raw files?
+
+| Approach | Cross-CLI | Async | Wake-up | Human board | Deps |
+|---|---|---|---|---|---|
+| **agent-mailbox** | ✅ any MCP host | ✅ inbox persists | ✅ webhook + task cards | ✅ built-in kanban | **0** |
+| Raw MCP tools | ❌ per-CLI sessions | ❌ lost on restart | ❌ | ❌ | — |
+| Slack/Discord bot | ✅ | ✅ | ✅ | ❌ | API tokens, rate limits, cloud dependency |
+| Shared files + conventions | ✅ | ⚠️ ad-hoc | ❌ manual | ❌ | your own locking code |
+
+The gap agent-mailbox fills: **agents on different CLIs, on the same machine, messaging each other asynchronously — with delivery guarantees and a human-visible board — without a single dependency.**
+
+> 🆕 **v0.3.0 — Task board**: agents now share a task surface on the same mail root. 3 new MCP tools (12 total), a zero-dependency drag-and-drop board (`--web`), and every move messages the assignee. ⚠️ **Upgrade note:** restart your agent session to pick up the new tools. → [Task board](#task-board)
+
+---
+
+## The problem
+
+Run several AI agents on one machine — Claude Code, Hermes, your own scripts — and they have no way to leave each other messages. Agents overlap, wait on each other, or you end up copy-pasting between their windows like a human switchboard.
+
+## The fix
+
+A mailbox is a directory of plain JSON files:
+
+```
+~/.agent-mail/
+  registry.json                agent_id → {owner, description, created_at}
+  inbox/HS/20260905-….json     one file per message
+  archive/HS/…
+  tasks.json                   the task board ({"next
+
+
+A mailbox is a directory of plain JSON files:
+
+```
+~/.agent-mail/
+  registry.json                agent_id → {owner, description, created_at}
+  inbox/HS/20260905-….json     one file per message
+  archive/HS/…
+  tasks.json                   the task board ({"next_id", "tasks": {id: card}})
+```
+
+Agents read and write it through a small stdio MCP server. No broker process, no ports, no database, no network by default. Any number of MCP host processes share one mail root safely (file-lock guarded).
+
+![agent-mailbox architecture](docs/architecture.png)
+
+## Quick start
+
+**Prerequisites** — one-time: install [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS/Linux, or `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` on Windows). `uvx` runs everything else; nothing else to install.
+
+### 1 · Register the server with your MCP host
+
+Claude Code:
+
+```bash
+claude mcp add agent-mailbox -- uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox
+```
+
+Any MCP host (generic JSON):
+
+```json
+{
+  "mcpServers": {
+    "agent-mailbox": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/polaris-smart/agent-mailbox", "agent-mailbox"]
+    }
+  }
+}
+```
+
+Tip: set `AGENT_MAIL_ID=HS` (or whichever id) in the agent's environment and every tool becomes self-addressed — no need to pass `agent_id` on each call.
+
+### 2 · Agents register once
+
+```json
+{ "tool": "mailbox_register", "arguments": { "agent_id": "HS", "owner": "Hermes", "description": "PM & QA" } }
+```
+
+Registration is idempotent. Every registered agent is immediately addressable by everyone — including a human `boss` id you can read yourself.
+
+### 3 · Send, check, reply
+
+```json
+{ "tool": "mailbox_send", "arguments": { "to": "HS", "subject": "deploy ready", "body": "v0.1.0 is staged, please verify." } }
+{ "tool": "mailbox_check", "arguments": {} }
+{ "tool": "mailbox_reply", "arguments": { "msg_id": "20260905-…-hs", "body": "verified, marked done." } }
+```
+
+`mailbox_check` fetches pending messages and marks them `acked`. Lifecycle: `pending → acked → done`, then optionally archived. A message is one JSON file you can `cat` — the boss reads the inbox directly.
+
+### 4 · Wait instead of poll
+
+`mailbox_wait` blocks (long-poll) until a message arrives — call it as the last action of a turn:
+
+```json
+{ "tool": "mailbox_wait", "arguments": { "timeout_seconds": 25 } }
+```
+
+## Task board
+
+Task cards live in `<mail-root>/tasks.json` (plain JSON, same file lock as the mail). The state machine is strict: `todo→doing→review→done`, non-adjacent moves rejected unless `force=True`; `done` is terminal. Creating or moving a card sends the assignee a normal mailbox message (`[task#t-12 → review] …`) — so board motion wakes the owning agent through the existing inbox, no polling, no webhooks. Self-assigned moves stay silent, and `notify=False` opts out.
+
+**Web board (for the human).** `agent-mailbox --web 8643` serves a zero-dependency kanban (stdlib `http.server` + one embedded HTML page, no framework) on `127.0.0.1`. Four lanes mirror the state machine; drag a card between adjacent lanes to move it, or create cards from the form; one toggle switches light/dark themes. Auth is a bearer token — set `AGENT_MAIL_WEB_TOKEN` for a stable one, or a fresh token is printed at boot (open `http://127.0.0.1:8643/?token=…`). The board acts as agent `boss`: every card you create or drag still auto-messages the assignee, so even human drag-and-drop wakes the right agent. The page auto-refreshes every 5 seconds.
+
+## For AI agents (hand this section to your agent)
+
+If you are an AI agent reading this because your user said "install agent-mailbox": do exactly this, no questions needed.
+
+1. Check `uvx --version`; if missing, install uv with the Prerequisites command above for the OS you are running on.
+2. Register the MCP server with your host app — use the generic JSON above (step 1) or your host's native mechanism.
+3. Pick an identity: any id matching `[A-Za-z0-9_-]` up to 64 chars. Set `AGENT_MAIL_ID=<id>` in your environment, then call `mailbox_register` once (it is idempotent).
+4. Verify: call `mailbox_whoami` — you should appear in the registry. You are now addressable by every other agent on this machine.
+5. Report your id back to your user so they can send you mail at `~/.agent-mail/inbox/<id>/`.
+
+Read English even if your user speaks another language — the commands are identical everywhere.
+
+## Works with your agent CLI
+
+Anything that speaks MCP stdio can host a mailbox — which is all of them. Register per your CLI's config:
+
+| Agent CLI | How to register |
+|-----------|-----------------|
+| Claude Code | `claude mcp add agent-mailbox -- uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox` |
+| Gemini CLI | `~/.gemini/settings.json` → `"mcpServers": { … }` (same JSON as Quick start) |
+| Qwen Code | same as Gemini CLI (`~/.qwen/settings.json`) |
+| Codex CLI | `~/.codex/config.toml` → `[mcp_servers.agent-mailbox]` with `command` / `args` |
+| OpenCode | `opencode.json` → `"mcp": { "agent-mailbox": { "type": "local", "command": ["uvx", "--from", "git+https://github.com/polaris-smart/agent-mailbox", "agent-mailbox"] } }` |
+| Hermes / Ark CLI / veCLI / OpenClaw / any MCP host | same generic JSON — point `command` at the `uvx` line above |
+
+Then set `AGENT_MAIL_ID` for that CLI's sessions and `mailbox_register` once. Agents on the same machine can now message each other **across different CLIs** — a Claude Code agent and a Gemini CLI agent share the same mail root with zero extra setup.
+
+## Waking a sleeping agent (one config line)
+
+If the receiving agent isn't even running, `mailbox_send` itself can POST every new message to a webhook the moment it lands — no daemon, no polling, no extra process:
+
+```json
+// ~/.agent-mail/webhook.json   (chmod 600)
+{ "url": "http://localhost:8644/webhooks/agent-mailbox", "secret": "…" }
+```
+
+Generate the secret yourself once: `openssl rand -hex 32`. Omit it for unsigned posts (fine for local testing; your receiver decides whether to require it).
+
+Your host's webhook handler receives:
+
+```json
+{ "event": "agent_mailbox_new_message", "event_type": "agent_mailbox_new_message", "message": { "id": "…", "from": "ZC", "to": "HS", "subject": "…", "body": "…" } }
+```
+
+…wakes the agent, and the agent calls `mailbox_check` on arrival. That is the whole integration.
+
+- Signed `X-Hub-Signature-256: sha256=<hmac>` (GitHub scheme — accepted by Hermes gateway and most webhook consumers).
+- The signature style is configurable via `AGENT_MAIL_SIGNATURE_STYLE`: `github` (default, `X-Hub-Signature-256: sha256=<hex>`) / `generic` (`X-Webhook-Signature: <hex>`, bare hex) / `slack` (`X-Slack-Signature: v0=<hex>`; this webhook emits no `ts` field, so receivers must NOT verify against the full Slack `v0:ts:body` base string).
+- The target is pinned: http/https only, loopback/private addresses by default, redirects refused, system proxy bypassed.
+- Env vars `AGENT_MAIL_WEBHOOK_URL` / `AGENT_MAIL_WEBHOOK_SECRET` override the file. Unset → fully offline.
+- The config file is resolved **per mail root** (the store's own `webhook.json`), so a `MailStore(root=…)` built on a scratch root can never wake the production gateway. `webhook.json` in the default home still covers normal use.
+- Every delivered mail is also appended to `<mail-root>/sent.log` (one JSONL line: id/from/to/subject/created_at) under the same lock as the write — a webhook notification with no matching `sent.log` line never was a mail.
+
+### Self-echo protection (on by default)
+
+A notification whose sender equals its target (self-echo, from == to) is **not delivered** by default: the letter still lands on disk, `mailbox_list` / `mailbox_check` are unaffected — the sender just isn't woken by its own send. The drop is audited in `sent.log` as `echo_suppressed: true`, so "there was a notification but no mail"-style disputes stay one grep away. Set `notify_self_echo: true` in the mail root's `config.json` (or env `AGENT_MAIL_NOTIFY_SELF_ECHO`) to restore delivery — restored self-echo notifications carry an `[echo] ` subject prefix (the stored letter keeps its original subject, so the prefix is regex-strippable).
+
+### Duplicate suppression (v0.5.0, delivery-side)
+
+Every letter stores a `semantic_hash` — `sha256(norm(subject) + "\0" + norm(prose) + "\0" + code_regions.join("\0"))`. Prose is NFKC/NFC normalized with whitespace folded; fenced ` ``` ` code regions are lifted out first and hashed **raw, in their original order** (zero folding — reordering code must not collapse to one hash). Legacy letters without the field never match (old mail is never back-filled).
+
+`mailbox_send` / `mailbox_broadcast` dedupe by default: if the target inbox already holds a same-hash letter in a non-terminal state (`pending`/`acked`) inside the dedup window, no new mail is created. **How callers notice**: that recipient's entry in the result carries `"deduped": true` and `"existing_id"` — nothing lands on disk, nothing is appended to `sent.log`, and no webhook fires (zero side effects). `"count"` counts only letters that actually landed. Pass `dedupe: false` to exempt a send; replies (`mailbox_reply`) are exempt by design. Only inboxes are consulted, never archives — a same-hash letter that is `done` or archived never blocks a re-send.
+
+- **Scope boundary (by design)**: normalization keeps timestamps verbatim, so periodic jobs whose bodies embed dates naturally hash differently — A does **not** stop them. A prevents same-semantics repeat wakes; periodic-task replay protection relies on the B compensation flow (below) plus `dedupe: false`.
+- **Expected, not a bug**: once the dedup window passes, a re-send goes through, so the queue can legitimately hold two same-hash non-terminal letters (the older one is still being handled).
+- **铁1 config coupling**: the reclaim window must stay strictly below the dedup window — `reap_ttl` (default 3600s) **<** `dedup_ttl` (default 86400s = 24h), both settable in `<mail-root>/config.json`. Violating configs fail loudly (`MailboxError`) at load time instead of silently distorting the windows.
+
+### Half-done handling: compensation + reclaim (v0.5.0)
+
+An agent that claims mail (`check` → `acked`) and dies leaves it invisible to a pending-only drain. v0.5 closes the loop three ways:
+
+- **Two-phase handled_log**: the handling layer records `intent` when it starts and `outcome` when finished via `MailStore.record_handled(agent_id, msg_id, action)` — the store is the single writer (mail-root flock), so `handled_log` stays append-only and auditable across sessions. `set_status(done)` comes last.
+- **Compensation table**: `MailStore.resume_plan(agent_id, msg_id)` reads only the log ("which segment did it reach?") and returns `resume`: `process` (pending, or acked with no records at all — claimed then crashed before the intent — same treatment: handle normally from the intent), `replay` (intent without outcome: idempotently redo the handling body), `finalize` (intent + outcome recorded but not `done` yet: only the status flip remains), `skip` (terminal).
+- **Stale-`acked` reclaim**: `python -m agent_mailbox.reap --agent ID --ttl 7200` flips `acked` mail older than the TTL back to `pending` with a `reclaimed` entry in `handled_log` (acked → reclaimed → done stays auditable end to end). Defaults: TTL 3600s in the store, 7200s in the wake script. A letter whose newest `intent` is fresher than 30 minutes is deferred — someone is actively on it. Reclaim is a manual maintenance operation: nothing in the library calls it automatically; the deployed wake script is the only wired caller.
+- **Wake wiring**: `scripts/wake-zc.sh` reaps **before** counting pending on every loop iteration (fail-open with an explicit log line) and carries a **circuit breaker**: after N consecutive no-progress drain rounds it latches (`~/.agent-mail/wake-zc.breaker`, auto-expires after 6h) and stops launching drain turns — backoff stretches the interval, the breaker stops the bleeding.
+
+## The tools
+
+| Tool | Notes |
+|------|-------|
+| `mailbox_register(agent_id, owner?, description?)` | claim a mailbox; idempotent |
+| `mailbox_send(to, subject, body, priority?)` | `to` = one id, a list, or `"all"`; `dedupe?` (default true) suppresses same-hash repeats (see above) |
+| `mailbox_check(agent_id?, mark?)` | fetch pending (→ `acked`) |
+| `mailbox_reply(msg_id, body)` | routes back to the original sender (dedupe-exempt) |
+| `mailbox_list(agent_id?, status?)` | list messages, optional status filter |
+| `mailbox_done(msg_id)` | mark handled |
+| `mailbox_broadcast(subject, body)` | to every registered agent; `dedupe?` per recipient |
+| `mailbox_whoami()` | directory of agents + mail root |
+| `mailbox_wait(agent_id?, timeout_seconds?)` | long-poll for new mail |
+| `task_create(title, assignee, due?)` | create a task card (starts `todo`); assignee auto-messaged |
+| `task_move(task_id, status, assignee?, note?, force?)` | move along `todo→doing→review→done` (skips need `force`); moving a card auto-messages its owner |
+| `task_list(assignee?, status?)` | list task cards, optional filters |
+
+Identity: pass `agent_id` explicitly, or set `AGENT_MAIL_ID` once per agent.
+
+## Optional: desktop notifications for humans
+
+A companion watcher prints every new message as a JSON line and fires desktop notifications (macOS / Linux / Windows). It is never on the agent wake-up path — agents don't need it:
+
+```bash
+uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox-watch --notify boss
+```
+
+Run it as a service on your platform:
+
+| Platform | Install | Verify |
+|----------|---------|--------|
+| macOS (launchd) | `scripts/install-watch-macos.sh --notify boss` | `tail -f ~/.agent-mail/watch.log` |
+| Linux (systemd user) | `scripts/install-watch-linux.sh …` | `journalctl --user -u agent-mailbox-watch -f` |
+| Windows (schtasks) | `scripts\install-watch-windows.ps1` | `schtasks /Query /TN AgentMailboxWatch /V` |
+
+## Maintenance: cleaning up test residue (cleanup)
+
+```bash
+python -m agent_mailbox.cleanup --dry-run              # list only (the default behaviour)
+python -m agent_mailbox.cleanup --dry-run --root ~/.agent-mail
+python -m agent_mailbox.cleanup --yes                  # actually delete: explicit --yes + interactive confirmation
+```
+
+Scans the mail root and lists **suspected test residue**: agent `inbox/` / `archive/` directories missing from registry.json, `NEWBIE` / `WBTEST`-style test-named directories, and orphan letters (stray files directly under `inbox/` / `archive/`, unparseable JSON, `*.tmp` left by an interrupted atomic write). Each finding prints path + size + reason; `--dry-run` (and the flagless default) deletes nothing; `--yes` deletes for real but requires typing `yes` to confirm. Registered-but-test-named directories are reported as review-only and never deleted. The `--yes` capability shipped with v0.4.0 — actually running it against a production mail root remains an explicit operator (boss) approval, separate from the release.
+
+## Design
+
+- **Local-first** — plain JSON files under `~/.agent-mail/`. No SMTP, no IMAP, no domain, no cloud relay, no network by default.
+- **Register-once addressing** — `mailbox_register("HS")` is all it takes; every registered agent is immediately addressable by everyone.
+- **Zero external dependencies** — only `mcp`. The store is one Python file with `flock`-guarded atomic writes; multiple MCP host processes share one mail root safely.
+- **Human-readable** — every message is a small JSON file you can `cat`. The boss reads the inbox directly.
+- **Honors existing identities** — set `AGENT_MAIL_ID` in each agent's environment and its tools become self-addressed.
+
+## Security notes
+
+- Mail root lives in your home directory; messages never leave the machine unless you opt into the webhook, which is pinned to loopback/private targets by default.
+- Agent ids are strictly validated (`[A-Za-z0-9_-]`, ≤64 chars) — no path traversal.
+- The store is append-oriented with atomic writes and file locks; a crashed writer cannot corrupt the registry.
+- Webhook payloads are HMAC-signed; verifiers should compare with a constant-time function.
+- For tamper-evidence, signed receipts (ed25519) are on the roadmap.
+
+## Development
+
+```bash
+git clone https://github.com/polaris-smart/agent-mailbox && cd agent-mailbox
+uv venv && uv pip install -e ".[dev]"
+pytest
+```
+
+## Upgrading
+
+Upgrade with `uv tool upgrade agent-mailbox` (or re-pull however you installed it).
+
+⚠️ **Restart your agent session (or reconnect the MCP client) after upgrading** — MCP tool lists are enumerated at session start, so new tools (12 now, was 9) only appear after a restart. No config changes needed; `tasks.json` is created automatically on first use.
+
+## Roadmap
+
+- **v0.5.0** (current) — lifecycle hardening from the 2026-09-13 incidents (task `t-6`): **duplicate suppression** (delivery-side `semantic_hash`, same-hash non-terminal repeats within a 24h window return `{"deduped": true, "existing_id"}` with zero side effects; `dedupe: false` exempts; code-fence-raw hashing, inbox-only scope, hash→inbox index); **half-done compensation** (`record_handled` two-phase intent/outcome API as the single `handled_log` writer + `resume_plan` four-row table: process / replay / finalize / skip); **stale-`acked` reclaim** shipped earlier as `reap_stale_acked` / `python -m agent_mailbox.reap` now wired into the wake loop (reap first, count second, fail-open) with the 铁1 coupling enforced — `reap_ttl` (3600s) must stay strictly below `dedup_ttl` (24h), violations fail loudly; **wake circuit breaker** — N consecutive no-progress drain rounds latch a breaker file and stop launching turns (backoff stretches the interval, the breaker stops the bleeding).
+- **v0.5.x (open)** — still tracked from the t-6 reviews, not in this release: `status filtering` (ask for "pending or acked" views), `identity binding` (bind MCP callers to `AGENT_MAIL_ID` against foreign checks; today's model is local trust — anyone on the machine can read any box), `wake routing` (gateway subscription `to`-filter; lives outside this repo), `unread_count` in webhook payloads, claim semantics for `mailbox_wait` (P1–P4 from the 09-13 forensics).
+- **v0.4.0** — feature batch: configurable webhook signature style (`AGENT_MAIL_SIGNATURE_STYLE`: github default / generic / slack); self-echo protection (notifications where sender == target are dropped by default, audited as `echo_suppressed` in `sent.log`; `notify_self_echo` / `AGENT_MAIL_NOTIFY_SELF_ECHO` restores delivery with an `[echo] ` subject prefix on the notification while the letter keeps its subject); new `cleanup --dry-run` maintenance command (scans for test residue, lists without deleting, `--yes` deletes after confirmation).
+- **v0.3.1** — patch batch: reply subjects no longer pile up `Re: Re:` (first reply, re-replies, and mixed-case prefixes all normalize to a single `Re:`); web board tokens use constant-time comparison (`hmac.compare_digest`) and persist across reboots (`~/.agent-mail/web_token`, mode 0600, `AGENT_MAIL_WEB_TOKEN` env always wins); `sent.log` auto-rotates one generation past 10 MB (to `sent.log.1`).
+- **v0.3.0** — task board + web kanban: `task_create` / `task_move` / `task_list` with a strict todo→doing→review→done state machine; creating or moving a card auto-messages the assignee, so board motion wakes agents with zero polling. `--web 8643` serves a token-protected zero-dependency kanban UI where human drag-and-drop goes through the same wake-up path. Messages + tasks + wake-up + board, still zero dependencies.
+- **v0.5.0+** — maybe: deeper kanban integrations (Kaneo as reference/competitor). Under discussion.
+- **Next** — federation: streamable HTTP transport for agents on other machines (Tailscale/LAN friendly); signed receipts (ed25519) for tamper-evident delivery.
+- **v1.0.0** — cross-organization bridge: local threads reach agents on other machines and organizations over standard email infrastructure, with the same mailbox lifecycle.
+
+## License
+
+MIT

agent_mailbox-0.5.0/README.es.md

@@ -0,0 +1,185 @@
+# agent-mailbox
+
+[![polaris-smart/agent-mailbox MCP server](https://glama.ai/mcp/servers/polaris-smart/agent-mailbox/badges/score.svg)](https://glama.ai/mcp/servers/polaris-smart/agent-mailbox)
+
+**Un buzón propio para cada agente de IA local.** Un servidor MCP por stdio. Cero demonios. Un archivo JSON por mensaje. Más un tablero de tareas integrado: las tarjetas despiertan a su responsable al moverse, y un kanban web sin dependencias para el humano.
+
+📖 **Docs**: [English](README.md) · [中文](README.zh-CN.md) · [Español](README.es.md) · [Português](README.pt-BR.md) · [Français](README.fr.md) · [Русский](README.ru.md)
+
+> 🆕 **v0.3.0 — Tablero de tareas**: los agentes comparten ahora una superficie de tareas sobre la misma raíz de correo. 3 herramientas MCP nuevas (12 en total), un tablero de arrastrar y soltar sin dependencias (`--web`), y cada movimiento avisa al responsable. ⚠️ **Nota de actualización**: reinicia tu sesión de agente para cargar las herramientas nuevas. → [Tablero de tareas](#tablero-de-tareas)
+
+---
+
+## El problema
+
+Ejecutar varios agentes de IA en una misma máquina — Claude Code, Hermes, tus propios scripts — y no tienen forma de dejarse mensajes. Se quedan esperándose, o terminas copiando y pegando entre ventanas como un operador humano.
+
+## La solución
+
+Un buzón es un directorio de archivos JSON simples:
+
+```
+~/.agent-mail/
+  registry.json                agent_id → {owner, description, created_at}
+  inbox/HS/20260905-….json     un archivo por mensaje
+  archive/HS/…
+  tasks.json                   el tablero de tareas ({"next_id", "tasks": {id: tarjeta}})
+```
+
+Los agentes lo leen y escriben a través de un pequeño servidor MCP por stdio. Sin proceso intermediario, sin puertos, sin base de datos, sin red por defecto. Cualquier número de hosts MCP comparten una misma raíz de correo de forma segura (con bloqueo de archivos).
+
+## Inicio rápido
+
+**Requisitos previos** — solo una vez: instala [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh` en macOS/Linux, o `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` en Windows). `uvx` ejecuta todo lo demás; no hay nada más que instalar.
+
+### 1 · Registra el servidor en tu host MCP
+
+Claude Code:
+
+```bash
+claude mcp add agent-mailbox -- uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox
+```
+
+Cualquier host MCP (JSON genérico):
+
+```json
+{
+  "mcpServers": {
+    "agent-mailbox": {
+      "command": "uvx",
+      "args": ["--from", "git+https://github.com/polaris-smart/agent-mailbox", "agent-mailbox"]
+    }
+  }
+}
+```
+
+Consejo: define `AGENT_MAIL_ID=HS` (o el id que quieras) en el entorno del agente y todas las herramientas quedan autodireccionadas — sin pasar `agent_id` en cada llamada.
+
+### 2 · Los agentes se registran una vez
+
+```json
+{ "tool": "mailbox_register", "arguments": { "agent_id": "HS", "owner": "Hermes", "description": "PM & QA" } }
+```
+
+El registro es idempotente. Todo agente registrado es direccionable de inmediato por todos — incluido un id humano `boss` que puedes leer tú mismo.
+
+### 3 · Enviar, revisar, responder
+
+```json
+{ "tool": "mailbox_send", "arguments": { "to": "HS", "subject": "deploy ready", "body": "v0.1.0 preparada, por favor verifica." } }
+{ "tool": "mailbox_check", "arguments": {} }
+{ "tool": "mailbox_reply", "arguments": { "msg_id": "20260905-…-hs", "body": "verificado, marcado done." } }
+```
+
+`mailbox_check` trae los mensajes pendientes y los marca `acked`. Ciclo de vida: `pending → acked → done`, y luego se archivan opcionalmente. Cada mensaje es un JSON que puedes `cat` — el jefe lee la bandeja directamente.
+
+### 4 · Esperar en vez de sondear
+
+`mailbox_wait` se bloquea (long-poll) hasta que llega un mensaje — llámalo como última acción del turno:
+
+```json
+{ "tool": "mailbox_wait", "arguments": { "timeout_seconds": 25 } }
+```
+
+## Tablero de tareas
+
+Las tarjetas viven en `<raíz de correo>/tasks.json` (JSON plano, el mismo bloqueo de archivos que el correo). La máquina de estados es estricta: `todo→doing→review→done`; los saltos no adyacentes se rechazan salvo `force=True`, y `done` es terminal. Crear o mover una tarjeta envía al responsable un mensaje normal del buzón (`[task#t-12 → review] …`) — el movimiento del tablero despierta al agente por la bandeja existente, sin sondeos ni webhooks. Los movimientos que uno se hace a sí mismo permanecen en silencio, y `notify=False` los desactiva.
+
+**Tablero web (para el humano).** `agent-mailbox --web 8643` sirve un kanban sin dependencias (`http.server` de stdlib + una sola página HTML embebida, sin frameworks) en `127.0.0.1`. Cuatro columnas reflejan la máquina de estados; arrastra una tarjeta entre columnas adyacentes para moverla, o crea tarjetas desde el formulario, con una sola alternancia entre tema claro y oscuro. La autenticación es un token bearer — define `AGENT_MAIL_WEB_TOKEN` para uno fijo, o se genera e imprime uno nuevo en cada arranque (abre `http://127.0.0.1:8643/?token=…`). El tablero actúa como agente `boss`: cada tarjeta que crees o arrastres sigue avisando al responsable — cada movimiento le envía un mensaje. La página se refresca cada 5 segundos.
+
+## Despertar a un agente dormido (una línea de configuración)
+
+Si el agente receptor ni siquiera está en ejecución, `mailbox_send` puede hacer POST de cada mensaje nuevo a un webhook en el instante en que aterriza — sin demonios, sin sondeo, sin procesos extra:
+
+```json
+// ~/.agent-mail/webhook.json   (chmod 600)
+{ "url": "http://localhost:8644/webhooks/agent-mailbox", "secret": "…" }
+```
+
+Genera el secreto una vez: `openssl rand -hex 32`. Omítelo para POSTs sin firmar (suficiente para pruebas locales; exigir la verificación lo decide el receptor).
+
+El manejador de webhooks del host recibe:
+
+```json
+{ "event": "agent_mailbox_new_message", "event_type": "agent_mailbox_new_message", "message": { "id": "…", "from": "ZC", "to": "HS", "subject": "…", "body": "…" } }
+```
+
+…despierta al agente, y el agente llama a `mailbox_check` al llegar. Esa es toda la integración.
+
+- Firmado con `X-Hub-Signature-256: sha256=<hmac>` (esquema GitHub — aceptado por Hermes gateway y la mayoría de consumidores de webhooks).
+- El destino queda fijado: solo http/https, direcciones loopback/privadas por defecto, redirecciones rechazadas, proxy del sistema omitido.
+- Las variables de entorno `AGENT_MAIL_WEBHOOK_URL` / `AGENT_MAIL_WEBHOOK_SECRET` tienen prioridad sobre el archivo. Sin configurar → totalmente offline.
+
+## Las herramientas
+
+| Herramienta | Notas |
+|-------------|-------|
+| `mailbox_register(agent_id, owner?, description?)` | reclama un buzón; idempotente |
+| `mailbox_send(to, subject, body, priority?)` | `to` = un id, una lista, o `"all"` |
+| `mailbox_check(agent_id?, mark?)` | trae pendientes (→ `acked`) |
+| `mailbox_reply(msg_id, body)` | enruta de vuelta al remitente original |
+| `mailbox_list(agent_id?, status?)` | lista mensajes, filtro opcional por estado |
+| `mailbox_done(msg_id)` | marca como atendido |
+| `mailbox_broadcast(subject, body)` | a todos los agentes registrados |
+| `mailbox_whoami()` | directorio de agentes + raíz de correo |
+| `mailbox_wait(agent_id?, timeout_seconds?)` | long-poll de correo nuevo |
+| `task_create(title, assignee, due?)` | crea una tarjeta de tarea (arranca en `todo`); avisa al responsable |
+| `task_move(task_id, status, assignee?, note?, force?)` | avanza por `todo→doing→review→done` (los saltos requieren `force`); mover una tarjeta avisa a su responsable |
+| `task_list(assignee?, status?)` | lista tarjetas de tarea, filtros opcionales |
+
+## Opcional: notificaciones de escritorio para humanos
+
+Un watcher complementario imprime cada mensaje nuevo como línea JSON y lanza notificaciones de escritorio (macOS / Linux / Windows). Nunca está en la ruta de despertar de agentes — los agentes no lo necesitan:
+
+```bash
+uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox-watch --notify boss
+```
+
+| Plataforma | Instalar | Verificar |
+|------------|----------|-----------|
+| macOS (launchd) | `scripts/install-watch-macos.sh --notify boss` | `tail -f ~/.agent-mail/watch.log` |
+| Linux (systemd user) | `scripts/install-watch-linux.sh …` | `journalctl --user -u agent-mailbox-watch -f` |
+| Windows (schtasks) | `scripts\install-watch-windows.ps1` | `schtasks /Query /TN AgentMailboxWatch /V` |
+
+## Diseño
+
+- **Local-first** — archivos JSON simples bajo `~/.agent-mail/`. Sin SMTP, sin IMAP, sin dominio, sin relé en la nube, sin red por defecto.
+- **Direccionamiento con un registro** — `mailbox_register("HS")` es todo lo que hace falta; todo agente registrado es direccionable por todos.
+- **Cero dependencias externas** — solo `mcp`. El almacén es un archivo Python con escrituras atómicas protegidas por `flock`.
+- **Legible por humanos** — cada mensaje es un JSON pequeño que puedes `cat`. El jefe lee la bandeja directamente.
+- **Respeta identidades existentes** — define `AGENT_MAIL_ID` en el entorno de cada agente y sus herramientas quedan autodireccionadas.
+
+## Notas de seguridad
+
+- La raíz de correo vive en tu directorio personal; los mensajes nunca salen de la máquina salvo que actives el webhook, fijado por defecto a destinos loopback/privados.
+- Los ids de agente se validan estrictamente (`[A-Za-z0-9_-]`, ≤64 caracteres) — sin path traversal.
+- El almacén es orientado a anexión con escrituras atómicas y bloqueos; un escritor caído no corrompe el registro.
+- Los payloads del webhook van firmados con HMAC; los verificadores deben usar comparación en tiempo constante.
+- Los recibos firmados (ed25519) están en el roadmap.
+
+## Desarrollo
+
+```bash
+git clone https://github.com/polaris-smart/agent-mailbox && cd agent-mailbox
+uv venv && uv pip install -e ".[dev]"
+pytest
+```
+
+## Actualización
+
+Actualiza con `uv tool upgrade agent-mailbox` (o vuelve a instalar según tu método original).
+
+⚠️ **Tras actualizar, reinicia tu sesión de agente (o reconecta el cliente MCP)** — la lista de herramientas MCP se enumera al iniciar la sesión, así que las herramientas nuevas (12 ahora, antes 9) solo aparecen tras un reinicio. No hay que cambiar ninguna configuración; `tasks.json` se crea automáticamente al primer uso.
+
+## Roadmap
+
+- **v0.4.0** (actual) — lote de funcionalidades: estilo de firma de webhook configurable (`AGENT_MAIL_SIGNATURE_STYLE`: github por defecto / generic / slack); protección contra auto-eco (las notificaciones donde remitente == destinatario no se entregan por defecto y se auditan como `echo_suppressed` en `sent.log`; `notify_self_echo` / `AGENT_MAIL_NOTIFY_SELF_ECHO` restaura la entrega con un prefijo `[echo] ` en el asunto de la notificación mientras la carta conserva el suyo); nuevo comando de mantenimiento `cleanup --dry-run` (escanea residuos de prueba, lista sin borrar, `--yes` borra tras confirmación).
+- **v0.3.1** — lote de parches: los asuntos de respuesta ya no acumulan `Re: Re:` (primera respuesta, re-respuestas y prefijos con mayúsculas/minúsculas mixtas se normalizan a un solo `Re:`); los tokens del tablero web usan comparación en tiempo constante (`hmac.compare_digest`) y persisten entre reinicios (`~/.agent-mail/web_token`, modo 0600, el env `AGENT_MAIL_WEB_TOKEN` siempre gana); `sent.log` rota automáticamente una generación pasados los 10 MB (a `sent.log.1`).
+- **v0.3.0** — tablero de tareas + kanban web: `task_create` / `task_move` / `task_list` con una estricta máquina de estados todo→doing→review→done; crear o mover una tarjeta avisa automáticamente al responsable, así el movimiento del tablero despierta agentes sin ningún sondeo. `--web 8643` sirve una interfaz kanban sin dependencias protegida por token donde el arrastre humano pasa por la misma ruta de despertar. Mensajes + tareas + despertar + tablero, cero dependencias.
+- **v0.5.0+** — quizá: integraciones kanban más profundas (Kaneo como referencia/competidor). En discusión.
+- **Siguiente** — federación: transporte HTTP streamable para agentes en otras máquinas (amigable con Tailscale/LAN); recibos firmados (ed25519) para entrega a prueba de manipulación.
+- **v1.0.0** — puente entre organizaciones: los hilos locales alcanzan agentes en otras máquinas y organizaciones sobre infraestructura de email estándar, con el mismo ciclo de vida del buzón.
+
+## Licencia
+
+MIT