feat(mcp): poll_messages watch primitive + source echo-guard

[hamr0]

First consumer-driven feature — multis, beeperbox's first customer, was hand-rolling a seed→poll→dedup loop against the raw /v1/ API and hitting the classic off-by-ones. This exposes the missing capability natively. Ability, not policy: beeperbox provides the watch mechanism; poll cadence and "handled" state stay with the integrator. It does not make beeperbox a streaming system (PRD §3) — it's a better-shaped poll.

What's in it

poll_messages (the watch primitive) — 11 tools now. Passive, cursor-based "what's new since I last looked?" feed across all recent chats (or one via chat_id). Read-only: never marks read, archives, or mutates.

• First call (no cursor) seeds "from now" and returns an empty backlog + a starting cursor.
• The cursor is opaque and fully stateless server-side → persist it and resume across process/container restarts with no missed or duplicated messages. Same-millisecond messages dedup by id (the {ts, ids@ts} encoding) — the specific bug hand-rolled pollers get wrong.
• Fetches the newest 100 per chat (headroom over the delivery page) and advances the cursor over only what was delivered, so an over-limit burst pages out across polls instead of being skipped.

source echo-guard — new source ("api"|"external") + echoed client_tag on every Message. On one account both the owner's own typed messages and the agent's API replies are is_self: true, so is_self can't guard echo. send_message/note_to_self record sends to a ledger persisted in the config volume (BEEPERBOX_SENT_LEDGER); read-back tags the match. Branch on source, not is_self. The content fallback is is_self-gated, so an external sender can never be mis-tagged and dropped.

Raw /v1/ contract made explicit (context guide + GUIDE) so direct-API consumers match the MCP layer: the ?limit=N ~25-item floor, the client-side cursor recipe, and the canonical heuristics (note-to-self total===1 && isSelf, network via accountID, group type==='group', pendingMessageID not stable).

Versioning

New tool + additive schema fields (source/client_tag on Message; client_tag on the two send tools) = MINOR. No field renamed/removed; existing clients need no edits.

Tests

node --test mcp/server.test.js (21 tests) over the pure cursor/dedup/echo-guard/delivery logic — same-ms dedup, a seed→poll→restart-resume walk, an over-page burst that must not lose/dupe, and the source matcher's id/content/window/cross-chat cases. Each guard was mutation-verified to fail without its fix. Wired into mcp-test.yml as a fast unit job; poll_messages added to the guard-check + smoke-test contracts.

Honest limitations (documented, not hidden)

• The source match is unverified against a live Beeper account (no live account in CI — the standing gate limitation), compounded by pendingMessageID possibly being swapped for a real bridge id on ack. Matcher is deliberately conservative; validate against a real account before a high-stakes auto-responder leans on it.
• A single chat receiving >100 messages between two polls can lose the oldest of that burst — Beeper's messages endpoint returns only the newest N with no backward paging.

Security

Ran /security on the diff. Closed two Lows by bounding caller-supplied input: cursor ids capped at 4096 on decode (CPU-amplification guard); client_tag truncated to 256 before the ledger (bloat guard). Both have tests that fail without the cap. Single-tenant trust model means IDOR/tenant-isolation are N/A.

🤖 Generated with Claude Code