Mailbox Bridge

Mailbox Bridge — Expose the Shared Mailbox to External Agents

Bundled skill. This file is shipped with @wrongstack/core and auto-discovered via bundledSkillsDir. To pin it to a specific project, run wstack skill install <path-to-this-file> once — the project-level manifest at ~/.wrongstack/projects/<slug>/installed-skills.json will record that override.

Overview

WrongStack-internal agents (CLI, TUI, WebUI, ACP) already share one project-level mailbox, a SQLite store at ~/.wrongstack/projects/<slug>/_mailbox.sqlite. This skill starts a thin loopback HTTP server that wraps that exact same GlobalMailbox so external coding agents — Claude Code, Aider, Continue, a user's own scripts — can read and send messages on the same channel without touching the store directly.

┌────────────────────────────────────────────────────────────────────┐
│                    WrongStack project dir                          │
│                                                                    │
│   ~/.wrongstack/projects/<slug>/                                  │
│   ├── _mailbox.sqlite           ← shared message store              │
│   ├── _mailbox.registry.json    ← agent heartbeats                  │
│   └── _mailbox.clients.json     ← REPL/TUI/WebUI/external clients   │
│                                                                    │
│              ▲             ▲             ▲             ▲            │
│              │             │             │             │            │
│       ┌──────┴───┐  ┌──────┴───┐  ┌──────┴───┐  ┌──────┴───┐       │
│       │ Leader A │  │ BugHunter│  │ WebUI    │  │ External │        │
│       │ (CLI)    │  │ (CLI)    │  │ (browser)│  │ agent    │        │
│       └──────────┘  └──────────┘  └──────────┘  └─────▲────┘       │
│                                                       │            │
│                                            HTTP POST │ /mailbox/* │
│                                                       │            │
└───────────────────────────────────────────────────────┼────────────┘
                                                        │
                                          ┌─────────────┴───────────┐
                                          │  wstack mailbox serve   │
                                          │  (this skill)           │
                                          │  wraps GlobalMailbox    │
                                          └─────────────────────────┘

The bridge does NOT introduce a parallel store. External calls go through GlobalMailbox, so agent heartbeats, read receipts, and HQ telemetry happen exactly as they do for WrongStack-internal callers. An external agent and a WrongStack-internal agent posting to the same agentId are indistinguishable to the rest of the system — the WebUI's "online agents" panel will show them side by side, with source = 'http' distinguishing the HTTP path.

When to use this skill

• The user asks to "let Claude Code send/receive on the mailbox".
• The user wants to run a script (build bot, CI hook, alerting agent) alongside WrongStack that should participate in the project's inter-agent coordination.
• The user wants to debug or inspect mailbox traffic from another tool without granting it access to the JSONL file.

When NOT to use this skill

• The external agent speaks MCP natively — use wstack mcp serve instead (it exposes WrongStack's tool registry, including the mailbox tool).
• The user wants SMTP/IMAP-style email integration — WrongStack's mailbox is internal-only and is not an email server. Reject that direction.
• The user wants the external agent to act on the wider file system or other WrongStack tools — the bridge exposes ONLY mailbox operations.

Setup

Run from any terminal where wstack is on PATH and the project is the working directory:

wstack mailbox serve

Or, if the user is already in a WrongStack REPL/TUI:

/mailbox-serve

To have every WrongStack surface start or join the bridge on boot, set features.mailboxBridge: "auto" in the project config. The default is "off", because nothing inside WrongStack needs the bridge — only external agents do.

The server prints its bind URL and writes the bearer token to ~/.wrongstack/projects/<slug>/.mailbox.token (mode 0600). The token is rotated on every server start, so external agents must read it freshly each time they connect — never hardcode.

To pass it to the external agent, set two environment variables:

WRONGSTACK_MAILBOX_URL=http://127.0.0.1:7788
WRONGSTACK_MAILBOX_TOKEN=$(cat ~/.wrongstack/projects/<slug>/.mailbox.token)

Flags

Routes

All routes take JSON bodies on POST (or no body on GET). All requests require Authorization: Bearer <token>. All responses are JSON.

Error shape

Every error response follows the WrongStack API convention:

{ "error": { "code": "VALIDATION_ERROR", "message": "field \"from\" is required (string)" } }

Limits

• Body cap: 256 KB. The mailbox message format is small; this leaves headroom for long bodies and base64 attachments while rejecting pathological payloads before they reach JSON.parse.
• Authenticated routes share a per-bearer sliding-window limit of 120 requests per 60 seconds. /healthz bypasses authentication and the limit. This bounds accidental flooding; it is not an identity or authorization boundary because every caller uses the same project token.

The HQ dashboard writes to the same mailbox

The HQ command center (wstack --hq) shares this exact GlobalMailbox. When an operator sends a prompt from the HQ screen, it lands in the same _mailbox.sqlite store an external agent reads through /mailbox/query — so an external agent participating via this bridge sees HQ prompts too.

HQ delivers a prompt one of two ways:

• POST /api/command on the HQ server — routes to a connected client, which then calls GlobalMailbox.send.
• POST /api/mailbox-send on the HQ server — writes to the project mailbox directly, so the prompt is delivered even when no agent is connected. The HQ server resolves the target projectRoot from its SessionRegistry (never a browser-supplied path).

Either way, the resulting mailbox message carries one of the HQ send types, which map onto the mailbox type field an external agent will observe:

An external agent does not need to distinguish HQ-originated messages — they arrive with from set to hq@<tag> and are read, acked, and completed through the same /mailbox/query + /mailbox/ack routes as any other message. Filter on from if you want to treat HQ prompts specially.

Pairing with the external-facing skill

This internal skill describes how to run the server. The wrongstack-mailbox skill (also bundled with @wrongstack/core) describes how the external agent uses the routes. When configuring an external agent, install both:

• In the WrongStack project: bundledSkillsDir/mailbox-bridge/ (this file)
• In the external agent's project: copy bundledSkillsDir/wrongstack-mailbox/SKILL.md to the agent's skills directory (e.g. .claude/skills/wrongstack-mailbox/SKILL.md). The repo ships scripts/install-mailbox-bridge-skills.sh for this.