Wrongstack Mailbox

WrongStack Mailbox Client

External-facing skill. Bundled with @wrongstack/core so it can be shipped to external agents via scripts/install-mailbox-bridge-skills.sh (which copies this file into the agent's local skills directory, e.g. .claude/skills/wrongstack-mailbox/SKILL.md). It is not for WrongStack's own REPL/TUI/WebUI — WrongStack agents should use the mailbox tool and the bundled mailbox-bridge skill instead.

Connect to a WrongStack project's shared inter-agent mailbox from outside WrongStack. Read what internal agents are saying, send replies, broadcast, and stay visible as an online agent in their WebUI.

This skill is the external-facing counterpart to the mailbox-bridge skill that runs inside WrongStack. The two are designed to be installed as a pair: mailbox-bridge on the WrongStack side starts the HTTP server; this skill teaches you (the external agent) how to talk to it.

What this skill assumes

The bridge is opt-in. It runs when someone starts wstack mailbox serve (or /mailbox-serve inside WrongStack), or when a WrongStack surface boots with features.mailboxBridge: "auto" in the project config — the default is "off". Once one instance is running, later starts for the same project join it instead of spawning a duplicate. The per-project lock (.mailbox-bridge.lock) and token file (.mailbox.token) make discovery possible without environment variables.

So the realistic scenarios for an external agent are:

1. A bridge is already running for the project. Read its URL and token from the per-project lock file — no env vars, no user prompt.
2. No WrongStack surface is running, but wstack is on PATH. mbWithBootstrap() (see Patterns below) spawns the bridge itself for the duration of the agent's session and cleans up at exit.
3. Nothing is running and wstack is NOT on PATH. Fall back to asking the user to start a surface (wstack --repl, wstack --webui) or to run wstack mailbox serve manually.

Environment variables (WRONGSTACK_MAILBOX_URL, WRONGSTACK_MAILBOX_TOKEN) still work as overrides — useful for pointing at a non-default bridge (a remote one, a CI bridge) — but they're no longer required for the common case.

When to use this skill

• The user asks you to read what's in the WrongStack mailbox.
• The user asks you to send a message to a specific WrongStack agent or to everyone (broadcast).
• The user wants you to register so WrongStack's WebUI shows you as an online external agent.
• The user wants you to reply to a specific message (look up the replyTo chain).

When NOT to use this skill

• The user wants the full WrongStack tool surface (file edits, shell, git, etc.). The bridge exposes only mailbox operations. For everything else, run WrongStack itself or use its MCP server.
• The user wants SMTP / IMAP / email integration. The WrongStack mailbox is internal-to-WrongStack — not an email server. Push back.
• The bridge is not running. Verify with GET /healthz before doing anything else.

Connection model

Single bearer token in Authorization: Bearer <token> on every request. The token is regenerated on every fresh bridge (cold) start — a surface that joins an already-running bridge reuses the live token, but once that bridge dies the next start mints a new one. So always read it freshly from the token file (or accept it from the user); never hardcode it into prompts or committed code, and re-read it after a 401.

The project token authorizes the route, not the caller's identity. The bridge accepts caller-supplied from, message type, registration ids, and acknowledgement readerId; it does not separately authorize control/steer messages. Use an honest, stable agent id, never impersonate hq@... or another agent, and treat every token holder as fully trusted for that project mailbox.

If you're working with explicit env vars:

const URL = process.env.WRONGSTACK_MAILBOX_URL;
const TOKEN = process.env.WRONGSTACK_MAILBOX_TOKEN;

if (!URL || !TOKEN) {
  throw new Error(
    'WRONGSTACK_MAILBOX_URL and WRONGSTACK_MAILBOX_TOKEN must be set ' +
    'before talking to the WrongStack mailbox bridge. (Or use ' +
    '`mbWithBootstrap()` to discover an already-running bridge from ' +
    'the per-project lock file — see "Discovering the bridge" below.)',
  );
}

If you don't have env vars, skip this guard and use mbWithBootstrap() from the next section instead — it discovers the bridge from .mailbox-bridge.lock (and spawns one if none is running).

The single helper

Everything in this skill goes through one fetch helper. Copy it once, use it for every route. It enforces the bearer token, sends JSON on POST, parses JSON on the response, throws on non-2xx, and applies a timeout so a hung bridge can't wedge the agent.

async function mb(path: string, body?: unknown): Promise<unknown> {
  const url = `${process.env.WRONGSTACK_MAILBOX_URL}${path}`;
  const token = process.env.WRONGSTACK_MAILBOX_TOKEN;
  const res = await fetch(url, {
    method: body === undefined ? 'GET' : 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}),
    },
    body: body !== undefined ? JSON.stringify(body) : undefined,
    signal: AbortSignal.timeout(10_000),
  });
  if (!res.ok) {
    let detail = '';
    try {
      const errBody = await res.json() as { error?: { code?: string; message?: string } };
      if (errBody.error) {
        detail = `${errBody.error.code ?? 'ERROR'}: ${errBody.error.message ?? '(no message)'}`;
      }
    } catch {
      detail = await res.text().catch(() => '(no body)');
    }
    throw new Error(`wrongstack mailbox ${res.status} ${detail}`);
  }
  return res.json();
}

Always use AbortSignal.timeout — never let a request hang forever. The mailbox is local; 10 s is generous.

Discovering the bridge: mbWithBootstrap()

Before using this workflow, read the complete instructions. Load with skill({ name: "wrongstack-mailbox", resource: "references/bootstrap-and-patterns.md" }), or resolve the reference relative to this skill directory in another client.

Message types

Pick the type that matches the intent of your message. WrongStack agents read type to decide how urgently to handle it.

Routes reference

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