Skip to content

mailroom 0.1.0: per-agent mailbox for Discord and GitHub, read over MCP - #1

Merged
cycle-five merged 14 commits into
masterfrom
feat/v0.1.0
Nov 18, 2026
Merged

cycle-five merged 14 commits into
masterfrom
feat/v0.1.0

Conversation

@cycle-five

Copy link
Copy Markdown
Member

What this is

A mailbox per agent. A poller collects Discord and GitHub activity through the existing broker Workers and appends it to one append-only inbox per agent. When an agent wakes up it reads its mail over MCP (read_mail, ack, mailbox_info) instead of spending inference checking Discord and GitHub directly.

Design: docs/superpowers/specs/2026-11-18-mailroom-design.md. Plan: docs/superpowers/plans/2026-11-18-mailroom.md.

Shape

  • crates/logic (pure Rust, native tests): record and config types, filter rules, the Discord channel poller, the GitHub repo poller, the MCP JSON-RPC transport.
  • crates/worker → Worker mailroom-core (workers-rs 0.9.0): one SQLite-backed Durable Object per agent, a once-a-minute cron tick, no public URL.
  • door/ → Worker mailroom (TypeScript): the public OAuth door. Sign in with Discord is delegated to discord-broker's Feed entrypoint, so mailroom holds no secrets. The operator picks which agent's mailbox a grant is bound to on the consent page; the door forwards /mcp to the core with the agent taken from the grant.

The brokers serve the poller through a read-only named Feed entrypoint over service bindings: CycleFive/discord-broker#1 and CycleFive/github-broker#1 (both merged, v0.2.0).

Properties

  • Fail closed. A poll returns either records plus new state, or an error. Records and state are written together; a failed poll writes neither, and the target is retried when next due.
  • Nothing lost silently. When a poll cannot cover everything (Discord paging limit, a full GitHub list, more than 1,000 reviews on a PR) a gap record says so, and gap records cannot be filtered away.
  • Single-consumer cursor. ack moves the cursor only forward and only over existing mail; acknowledged mail is pruned after retain_days.
  • One boundary. Authorization lives in the door; the core has neither a workers.dev URL nor preview URLs.

Verification

  • cargo fmt --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (100 tests)
  • door: npm run typecheck, npm test (22 tests)
  • crates/worker/smoke/run.sh: the real wasm build under workerd against a fake Feed (first contact, delta, mention routing, failed poll keeps state, ack bounds, unknown agent)
  • Each task was reviewed on its own, then the whole branch (with both broker diffs) was reviewed once more; the one Important finding (PR reviews past the first page) and five hardening items are fixed in the last commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_017zqkEBoTfRovHZ26Cjjc91

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…riod

Use one tick-start timestamp as last_attempt and add a 30 s slack to the
due comparison (time::due).

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
- Reviews are paged 100 at a time (max 10 pages); a full last page yields a gap record.
- GitHub lists that come back full and all-new yield a gap record (not on first contact).
- gap records bypass rules and keep.
- Discord reactions compare count_details.normal and stop refetching at the 100 cap.
- The door shows a generic page for core config errors and logs the detail.
- preview_urls: false in the core's wrangler config.

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
…config errors

Co-Authored-By: Claude & Lothrop (cycle.five@proton.me)
@cycle-five
cycle-five merged commit c5bd2d4 into master Nov 18, 2026
2 checks passed
@cycle-five
cycle-five deleted the feat/v0.1.0 branch November 18, 2026 14:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant