agent-mailbox 0.5.0__py3-none-any.whl

agent_mailbox/__init__.py

@@ -0,0 +1,3 @@
+"""agent-mailbox: give every local AI agent its own mailbox."""
+
+__version__ = "0.5.0"

agent_mailbox/__main__.py

@@ -0,0 +1,8 @@
+"""`python -m agent_mailbox` — delegates to the cleanup CLI (the mail root's
+maintenance entry point; server startup is via `agent-mailbox` / `-m
+agent_mailbox.server`)."""
+
+from .cleanup import main
+
+if __name__ == "__main__":
+    main()

agent_mailbox/cleanup.py

@@ -0,0 +1,177 @@
+"""Scan a mail root for suspected test residue (dry-run by default).
+
+``python -m agent_mailbox.cleanup --dry-run`` lists — never deletes —
+directories and letters that look like leftovers:
+
+- agent ``inbox/``/``archive/`` directories whose id is not in registry.json;
+- NEWBIE/WBTEST-style test-named directories;
+- orphan letters: stray files directly under inbox/ or archive/, JSON a
+  mailbox_list can no longer parse, and ``*.tmp`` left by an interrupted
+  atomic write.
+
+The default mode is dry-run. Actual deletion requires explicit ``--yes`` and
+an interactive confirmation; registered-but-test-named directories are
+reported as review-only and never deleted. Pure stdlib.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+
+# case-insensitive substrings that mark a directory as test residue
+TEST_NAME_MARKERS = ("test", "newbie", "demo", "scratch")
+
+
+def _is_test_name(name: str) -> bool:
+    low = name.lower()
+    return any(marker in low for marker in TEST_NAME_MARKERS)
+
+
+def _human(n: int) -> str:
+    if n >= 1024 * 1024:
+        return f"{n / 1024 / 1024:.1f} MB"
+    if n >= 1024:
+        return f"{n / 1024:.1f} KB"
+    return f"{n} B"
+
+
+def _dir_stats(d: Path) -> tuple[int, int]:
+    files = [p for p in d.rglob("*") if p.is_file()]
+    return sum(p.stat().st_size for p in files), len(files)
+
+
+def scan(root: Path) -> list[dict]:
+    """Return suspected-residue findings for ``root`` (no mutation)."""
+    findings: list[dict] = []
+    agents: set[str] = set()
+    try:
+        reg = json.loads((root / "registry.json").read_text(encoding="utf-8"))
+        agents = set(reg.get("agents", {}))
+    except FileNotFoundError:
+        pass  # empty/missing registry: every agent dir counts as residue
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"cleanup: corrupt registry.json: {e}") from e
+
+    for base_name in ("inbox", "archive"):
+        base = root / base_name
+        if not base.is_dir():
+            continue
+        for entry in sorted(base.iterdir()):
+            rel = f"{base_name}/{entry.name}"
+            if entry.is_file():
+                findings.append({
+                    "kind": "orphan-letter",
+                    "path": rel,
+                    "size": entry.stat().st_size,
+                    "reason": "stray file directly under inbox/archive (no agent dir)",
+                    "action": "delete file",
+                })
+                continue
+            size, n_files = _dir_stats(entry)
+            registered = entry.name in agents
+            test_named = _is_test_name(entry.name)
+            if not registered:
+                kind = "test-named-dir" if test_named else "unregistered-dir"
+                reason = "agent not in registry.json"
+                if test_named:
+                    reason += "; name matches test pattern"
+                findings.append({
+                    "kind": kind, "path": rel, "size": size,
+                    "reason": reason, "action": f"delete dir ({n_files} files)",
+                })
+            elif test_named:
+                findings.append({
+                    "kind": "test-named-dir", "path": rel, "size": size,
+                    "reason": f"test-named but registered ({n_files} files)",
+                    "action": "review only — not deleted",
+                })
+            else:
+                for p in sorted(entry.glob("*.json")):
+                    try:
+                        json.loads(p.read_text(encoding="utf-8"))
+                    except (json.JSONDecodeError, OSError):
+                        findings.append({
+                            "kind": "orphan-letter",
+                            "path": f"{rel}/{p.name}",
+                            "size": p.stat().st_size,
+                            "reason": "unparseable JSON — invisible to mailbox_list",
+                            "action": "delete file",
+                        })
+
+    for p in sorted(root.glob("*.tmp")):
+        findings.append({
+            "kind": "orphan-letter",
+            "path": p.name,
+            "size": p.stat().st_size,
+            "reason": "stray *.tmp from an interrupted atomic write",
+            "action": "delete file",
+        })
+    return findings
+
+
+def _delete(root: Path, findings: list[dict]) -> int:
+    n = 0
+    for f in findings:
+        if not f["action"].startswith("delete"):
+            continue
+        path = root / f["path"]
+        if path.is_dir():
+            shutil.rmtree(path)
+        elif path.exists():
+            path.unlink()
+        n += 1
+    return n
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="agent-mailbox-cleanup",
+        description="List (default) or delete suspected test residue in a mail root.",
+    )
+    parser.add_argument(
+        "--root", default=None,
+        help="mail root (default $AGENT_MAIL_HOME or ~/.agent-mail)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="list suspects only, never delete (the default behaviour)",
+    )
+    parser.add_argument(
+        "--yes", action="store_true",
+        help="actually delete the listed suspects (asks for confirmation)",
+    )
+    args = parser.parse_args(argv)
+
+    root = Path(args.root or os.environ.get("AGENT_MAIL_HOME", "~/.agent-mail")).expanduser()
+    if not root.is_dir():
+        print(f"cleanup: mail root not found: {root}", file=sys.stderr)
+        raise SystemExit(1)
+
+    findings = scan(root)
+    if not findings:
+        print(f"cleanup: no suspected residue in {root}")
+        return
+
+    total = 0
+    for f in findings:
+        total += f["size"]
+        print(f"[{f['kind']}] {f['path']}  {_human(f['size'])}  ({f['reason']})  -> {f['action']}")
+    print(f"\n{len(findings)} finding(s), {_human(total)} total")
+
+    if args.dry_run or not args.yes:
+        print("nothing deleted (pass --yes to actually delete)")
+        return
+    answer = input(f"Delete the listed items in {root}? Type 'yes' to confirm: ")
+    if answer.strip().lower() != "yes":
+        print("aborted — nothing deleted")
+        return
+    print(f"deleted {_delete(root, findings)} item(s)")
+
+
+if __name__ == "__main__":
+    main()

agent_mailbox/reap.py

@@ -0,0 +1,44 @@
+"""Reap orphaned ``acked`` mail back to ``pending`` (task t-6 wiring, v0.5).
+
+``MailStore.check()`` moves pending -> acked and hands the letters to the
+caller; a caller that dies, is cancelled, or was a foreign-identity check
+leaves them acked forever, invisible to a pending-only drain. This CLI is the
+thin shell the wake loop calls *before* counting pending, so those letters
+come back into view instead of hiding behind a zero count.
+
+``python -m agent_mailbox.reap --agent ZC --ttl 3600``
+Never deletes anything: status flips back to pending and ``handled_log``
+records a ``reclaimed`` entry. Pure stdlib.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .store import MailboxError, MailStore
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="agent-mailbox-reap")
+    parser.add_argument("--agent", required=True, help="mailbox to reap (defaults to AGENT_MAIL_ID when omitted)")
+    parser.add_argument(
+        "--ttl",
+        type=float,
+        default=3600.0,
+        help="seconds a letter may stay acked before it is reclaimed (default: 3600)",
+    )
+    args = parser.parse_args()
+
+    try:
+        reaped = MailStore().reap_stale_acked(args.agent, ttl_seconds=args.ttl)
+    except MailboxError as e:
+        print(f"reap: {e}", file=sys.stderr)
+        raise SystemExit(1) from e
+    for mid in reaped:
+        print(f"reclaimed {mid}")
+    print(f"reap: {len(reaped)} reclaimed (agent={args.agent}, ttl={args.ttl:g}s)")
+
+
+if __name__ == "__main__":
+    main()

agent_mailbox/server.py

@@ -0,0 +1,268 @@
+"""agent-mailbox MCP server.
+
+Expose a local, file-backed mailbox as MCP tools. Any MCP-capable agent on
+this machine can register once and then message every other agent — no cron,
+no polling daemons, no shared markdown files.
+
+Run:  ``agent-mailbox``            (stdio transport, for host apps)
+      ``agent-mailbox --http 8642`` (streamable HTTP, for remote agents)
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+
+from mcp.server.mcpserver import MCPServer
+
+from .store import MailboxError, MailStore
+
+server = MCPServer(
+    "agent-mailbox",
+    instructions=(
+        "A global mailbox for local AI agents. Register once with mailbox_register, "
+        "then use mailbox_send / mailbox_check / mailbox_reply / mailbox_list / "
+        "mailbox_done / mailbox_broadcast. Check your inbox when you start a session "
+        "and after finishing a task — messages wait here even when the recipient is offline. "
+        "Task cards: task_create / task_move / task_list manage a shared task board; "
+        "creating or moving a card auto-messages the assignee, so board motion wakes "
+        "agents without polling."
+    ),
+)
+
+_store: MailStore | None = None
+
+
+def _store_instance() -> MailStore:
+    global _store
+    if _store is None:
+        _store = MailStore()
+    return _store
+
+
+# --------------------------------------------------------------------- tools
+
+@server.tool()
+def mailbox_register(agent_id: str, owner: str = "", description: str = "") -> dict:
+    """Register this agent and claim its mailbox. Idempotent — safe to call again."""
+    return _store_instance().register(agent_id, owner, description)
+
+
+@server.tool()
+def mailbox_send(
+    to: str | list[str],
+    subject: str,
+    body: str,
+    priority: str = "normal",
+    reply_to: str | None = None,
+    from_id: str = "",
+    dedupe: bool = True,
+) -> dict:
+    """Send a message to one agent, a list of agents, or \"all\" for broadcast.
+
+    dedupe=True (default) suppresses a re-send of semantically identical
+    mail to a recipient whose inbox still holds it non-terminal (pending /
+    acked) within the 24h dedup window: that recipient's entry comes back as
+    {\"to\", \"deduped\": true, \"existing_id\"} with zero side effects — no
+    letter, no sent.log line, no webhook. Pass dedupe=False to exempt
+    periodic jobs. \"count\" counts only letters that actually landed.
+    """
+    frm = from_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not frm:
+        raise MailboxError("from_id required (or set AGENT_MAIL_ID env)")
+    sent = _store_instance().send(
+        frm, to, subject, body, reply_to=reply_to, priority=priority, dedupe=dedupe
+    )
+    delivered = sum(1 for e in sent if not e.get("deduped"))
+    return {"delivered": sent, "count": delivered}
+
+
+@server.tool()
+def mailbox_check(agent_id: str = "", mark: bool = True) -> dict:
+    """Fetch your pending messages (they become acked). Call at session start."""
+    me = agent_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("agent_id required (or set AGENT_MAIL_ID env)")
+    msgs = _store_instance().check(me, mark=mark)
+    return {"agent_id": me, "unread": len(msgs), "messages": msgs}
+
+
+@server.tool()
+def mailbox_reply(msg_id: str, body: str, agent_id: str = "") -> dict:
+    """Reply to a message thread. Routes to the original sender automatically."""
+    me = agent_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("agent_id required (or set AGENT_MAIL_ID env)")
+    st = _store_instance()
+    mine = [m for m in st.list_messages(me) if m["id"] == msg_id]
+    from_archive = False
+    if not mine:
+        mine = [m for m in st.list_archived(me) if m["id"] == msg_id]
+        from_archive = True
+    if not mine:
+        raise MailboxError(
+            f"message {msg_id!r} not found in inbox or archive for {me!r}"
+        )
+    original = mine[0]
+    sent = st.send(
+        me,
+        original["from"],
+        f"Re: {original['subject']}",
+        body,
+        reply_to=msg_id,
+        dedupe=False,  # replies are thread-addressed; keep the legacy contract
+    )
+    if from_archive:
+        # Original is already done + archived; nothing left to close.
+        return {"replied": sent[0], "closed": None, "archived_original": msg_id}
+    st.set_status(me, msg_id, "done")
+    return {"replied": sent[0], "closed": msg_id}
+
+
+@server.tool()
+def mailbox_list(agent_id: str = "", status: str | None = None) -> dict:
+    """List messages in your mailbox, optionally filtered by status."""
+    me = agent_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("agent_id required (or set AGENT_MAIL_ID env)")
+    msgs = _store_instance().list_messages(me, status)
+    return {"agent_id": me, "count": len(msgs), "messages": msgs}
+
+
+@server.tool()
+def mailbox_done(msg_id: str, agent_id: str = "") -> dict:
+    """Mark a message as handled. Done messages can be archived."""
+    me = agent_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("agent_id required (or set AGENT_MAIL_ID env)")
+    m = _store_instance().set_status(me, msg_id, "done")
+    n = _store_instance().archive_done(me)
+    return {"message": m["id"], "status": "done", "archived": n}
+
+
+@server.tool()
+def mailbox_broadcast(subject: str, body: str, from_id: str = "", dedupe: bool = True) -> dict:
+    """Broadcast to every registered agent (including boss). dedupe=True
+    (default) suppresses semantically identical re-broadcasts per recipient
+    within the dedup window — see mailbox_send."""
+    frm = from_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not frm:
+        raise MailboxError("from_id required (or set AGENT_MAIL_ID env)")
+    sent = _store_instance().send(frm, "all", subject, body, priority="high", dedupe=dedupe)
+    delivered = sum(1 for e in sent if not e.get("deduped"))
+    return {"delivered": sent, "count": delivered}
+
+
+@server.tool()
+def mailbox_whoami() -> dict:
+    """List all registered agents and the mail root location."""
+    st = _store_instance()
+    reg = st.registry()
+    return {
+        "mail_root": str(st.root),
+        "default_identity": os.environ.get("AGENT_MAIL_ID", ""),
+        "agents": reg["agents"],
+    }
+
+
+@server.tool()
+def mailbox_wait(agent_id: str = "", timeout_seconds: float = 25.0) -> dict:
+    """Block until a new message arrives (long-poll, up to timeout). Returns
+    immediately if pending messages exist. Import 'time' is at module top."""
+    me = agent_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("agent_id required (or set AGENT_MAIL_ID env)")
+    st = _store_instance()
+    deadline = time.time() + max(1.0, min(timeout_seconds, 60.0))
+    while True:
+        msgs = st.list_messages(me, status="pending")
+        if msgs:
+            got = st.check(me, mark=True)
+            return {"agent_id": me, "received": len(got), "messages": got}
+        if time.time() >= deadline:
+            return {"agent_id": me, "received": 0, "messages": [], "timeout": True}
+        time.sleep(0.5)
+
+
+# ---------------------------------------------------------------- task tools
+
+@server.tool()
+def task_create(
+    title: str, assignee: str, due: str = "", from_id: str = "", notify: bool = True
+) -> dict:
+    """Create a task card (starts at todo). The assignee is auto-messaged —
+    skip with notify=False."""
+    me = from_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("from_id required (or set AGENT_MAIL_ID env)")
+    task = _store_instance().task_create(title, assignee, me, due, notify=notify)
+    return {"task": task}
+
+
+@server.tool()
+def task_move(
+    task_id: str,
+    status: str,
+    assignee: str | None = None,
+    note: str = "",
+    force: bool = False,
+    notify: bool = True,
+    from_id: str = "",
+) -> dict:
+    """Move a task along todo→doing→review→done. Skips need force=True;
+    done is terminal. Pass assignee to reassign. The (new) assignee is
+    auto-messaged — moving a card wakes its owner."""
+    me = from_id or os.environ.get("AGENT_MAIL_ID", "")
+    if not me:
+        raise MailboxError("from_id required (or set AGENT_MAIL_ID env)")
+    task = _store_instance().task_move(
+        task_id, status, moved_by=me, assignee=assignee,
+        force=force, notify=notify, note=note,
+    )
+    return {"task": task}
+
+
+@server.tool()
+def task_list(assignee: str | None = None, status: str | None = None) -> dict:
+    """List task cards, optionally filtered by assignee and/or status."""
+    tasks = _store_instance().task_list(assignee=assignee, status=status)
+    return {"count": len(tasks), "tasks": tasks}
+
+
+def main() -> None:
+    # MCP stdio speaks UTF-8; on Windows/macOS CI the default console codec
+    # (cp1252 etc.) cannot encode arrows/CJK in tool output and crashes the
+    # child process before the handshake completes.
+    for _stream in (sys.stdout, sys.stderr):
+        if _stream is not None and hasattr(_stream, "reconfigure"):
+            try:
+                _stream.reconfigure(encoding="utf-8")
+            except (OSError, ValueError):
+                pass
+
+    parser = argparse.ArgumentParser(prog="agent-mailbox")
+    parser.add_argument("--http", metavar="PORT", type=int, default=None,
+                        help="serve streamable HTTP on PORT (default: stdio)")
+    parser.add_argument("--web", metavar="PORT", type=int, default=None,
+                        help="serve the kanban board UI + JSON API on PORT (default: stdio)")
+    parser.add_argument("--home", metavar="DIR", default=None,
+                        help="mail root directory (default: ~/.agent-mail)")
+    args = parser.parse_args()
+
+    if args.home:
+        os.environ["AGENT_MAIL_HOME"] = args.home
+
+    if args.web:
+        from .web import run_web
+
+        run_web(args.web)
+    elif args.http:
+        server.run(transport="streamable-http", port=args.http)
+    else:
+        server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()