agent-mailbox — Mailbox and Wake System for AI Agent Teams

Broadcast to every registered agent (including boss). dedupe=True (default) suppresses semantically identical re-broadcasts per recipient within the dedup window — see mailbox_send.

Fetch your pending letters and your true backlog. Call at session start. v0.7.6 (F 状态可信): by default this is a **read-only probe** — letters stay ``pending``; counting mail never consumes it (禁自动 ack). The numbers report the mailbox as it is *right now*, straight from the store: - ``unread`` — 真·待办: letters currently ``pending``. Acked letters are never counted, so a mailbox full of acked-but-unhandled mail reports ``unread: 0`` honestly (the pre-0.7.6 bug: it counted the letters the call itself had just acked). - ``total`` — all non-done letters (pending + acked): the backlog you still owe, visible even when ``unread`` is 0. - ``messages`` — the pending letters themselves (sealed bodies redacted). Pass ``mark=True`` to explicitly flip the returned letters to ``acked`` (the legacy auto-ack behavior, now opt-in); the numbers above are still computed after that pass, so they never describe consumed mail as unread. Nothing here ever sets ``done`` or moves a status backwards. Adds ``ghosts`` when any thread you hold more than 5 open (non-done) letters in — that is the acked-sinking failure mode; drain those threads before starting new work.

Human confirmation gate for an external-origin letter (§3.3). Flips ``origin`` external→local so the wake/webhook paths may act on it. Only an owner-kind member (``boss`` or a registered ``owner``) may confirm; the operation appends to audit.log and the letter's handled_log (greppable by name). Anything else is a structured rejection.

Mark a message as handled. Done messages can be archived.

List messages in your mailbox, optionally filtered by status and/or thread. Spans inbox **and** archive: ``check()`` moves handled letters into the archive, so an inbox-only view reports zero for any agent that drains regularly (HS 09-24: five status queries all returned 0 against 877 on-disk letters). ``thread`` takes a thread_id, or any subject on the thread (legacy letters without a thread_id are matched by the subject key heuristic).

Register this member and claim its mailbox. Idempotent — safe to call again. ``kind`` (v0.7.5): ``owner`` (the human), ``agent`` (a local agent) or ``guest`` (an external source). Empty keeps the existing/default kind; an explicit kind is a visibility decision and is written to audit.log.

Reply to a message thread. Routes to the original sender automatically.

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. v0.7.5: ``sealed=True`` marks a 密封信 — the body stays readable only through the recipient agent's own tools; every other view (owner, web, other agents) sees metadata only. ``origin="external"`` marks outside-origin mail: it lands but never triggers actions (no wake, no webhook) until an owner confirms it. ``attention`` is the 打扰三档 (decision=需你拍板 / report=报备 / archive=存档). A ``guest`` sender must present a valid ``pairing_token``. v0.7.6 (PR2): ``links`` optionally carries structured pointers ``[{"title", "uri", "kind"?, "sha256"?, "note"?}]``. Schemes file/http/https/git only — anything else (ftp://, etc.) is a structured reject before the letter lands. Read paths annotate each link with a fresh ``state`` (ok/stale/denied) + ``reason``; ``file://`` links are gated by the mail root's ``allowed_roots`` config (fail-closed).

Pull one thread in time order across every agent (inbox + archive). ``thread`` may be a thread_id, any message id on the thread, or a subject on the thread. Legacy letters without an id/thread_id are included via the subject-key heuristic (Re:/Fwd: prefixes stripped), so a 12-deep "Re: Re: ..." chain resolves to one thread. Letters come back oldest first with their status, so the full cross-agent conversation is visible in one call. v0.7.5 scope: an ``agent``/``guest`` caller sees only the letters it took part in (from/to includes them) — if the thread exists but none of its letters do, that is a structured ``permission denied``, not silent emptiness. Sealed bodies are readable only by the recipient agent; everyone else gets metadata.

Block until a new message arrives (long-poll, up to timeout). Returns immediately if pending messages exist. Import 'time' is at module top.

List all registered agents and the mail root location.

Create a task card (starts at todo). The assignee is auto-messaged — skip with notify=False.

List task cards, optionally filtered by assignee and/or status.

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.