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

Since commit 46427ea4 (feat/mailbox-daemon), every WrongStack surface (REPL/TUI/WebUI/eternal-autonomy) auto-bootstraps the mailbox bridge on startup. The first surface to come up for a given project joins an existing instance or spawns a fresh wstack mailbox serve child process; a second surface on the same project joins the first's bridge rather than spawning a duplicate. The per-project lock (.mailbox-bridge.lock) and token file (.mailbox.token) make discovery trivial.

So the realistic scenarios for an external agent are:

1. A WrongStack surface is already running for the project (most common). Read the bridge URL + token from the per-project files — no env vars, no manual wstack mailbox serve, 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()

The plain mb() helper above assumes WRONGSTACK_MAILBOX_URL and WRONGSTACK_MAILBOX_TOKEN are set. After the auto-bootstrap wiring, external agents usually don't have those env vars — they need to discover the bridge from the per-project lock file (or spawn one).

mbWithBootstrap() handles all three scenarios from the "What this skill assumes" section:

1. Env vars set → use them directly.
2. No env vars, but a WrongStack surface is running → read the .mailbox-bridge.lock and .mailbox.token files from the project directory to discover the running bridge.
3. No env vars, no surface running, but wstack is on PATH → spawn wstack mailbox serve as a child process and wait for the lock to appear (the bootstrap helper writes it within ~200 ms of listen() returning). Use this when you want full self-service.

The helper takes a projectDir (the absolute path to the user's WrongStack project root) and returns a configured mb(path, body) function. Call it once at agent startup; use the returned mb for every subsequent route call.

/**
 * Returns a configured `mb(path, body)` function for talking to
 * the WrongStack mailbox bridge, spawning one if necessary.
 *
 * Discovery order:
 *   1. WRONGSTACK_MAILBOX_URL + WRONGSTACK_MAILBOX_TOKEN env vars
 *      (highest precedence — used as-is).
 *   2. <projectDir>/.mailbox-bridge.lock  (the per-project lock file
 *      written by every running WrongStack surface — read its
 *      `url` + `token` fields).
 *   3. <projectDir>/.mailbox.token         (the token file, in case
 *      the URL is set in env but the token isn't, or vice versa).
 *   4. Spawn `wstack mailbox serve` via async `spawn` + unref, then
 *      poll the lock file for up to 5 s. Used as a last resort when no
 *      WrongStack surface is running yet.
 *
 * Throws only when ALL three fail (no env vars, no lock file, no
 * `wstack` on PATH). The caller decides whether to surface that
 * to the user or fall back to manual setup.
 */
async function mbWithBootstrap(
  projectDir: string,
): Promise<(path: string, body?: unknown) => Promise<unknown>> {
  // 1. Env vars win outright.
  if (process.env.WRONGSTACK_MAILBOX_URL && process.env.WRONGSTACK_MAILBOX_TOKEN) {
    return mb;
  }

  // 2-3. Lock + token files.
  const lockPath = path.join(projectDir, '.mailbox-bridge.lock');
  const tokenPath = path.join(projectDir, '.mailbox.token');
  let url = process.env.WRONGSTACK_MAILBOX_URL;
  let token = process.env.WRONGSTACK_MAILBOX_TOKEN;

  try {
    const lockRaw = await fs.readFile(lockPath, 'utf8');
    const lock = JSON.parse(lockRaw) as { url: string; token: string };
    if (lock.url && lock.token) {
      url = url ?? lock.url;
      token = token ?? lock.token;
    }
  } catch {
    // lock file absent — fall through to spawn step
  }
  if (token === undefined) {
    try {
      token = (await fs.readFile(tokenPath, 'utf8')).trim();
    } catch {
      // token file absent — fall through to spawn step
    }
  }

  // 4. Last resort — spawn `wstack mailbox serve` ourselves.
  //    Use async `spawn` + unref, NOT `spawnSync`: the bridge is a
  //    long-lived server that never exits, so `spawnSync` would block
  //    this agent forever. On Windows `wstack` is a `.cmd` shim, so
  //    `shell:true` is required to resolve it on PATH; `detached` is
  //    POSIX-only (on win32 it pops a visible console window).
  if (url === undefined || token === undefined) {
    try {
      const { spawn } = await import('node:child_process');
      const isWin = process.platform === 'win32';
      const child = spawn('wstack', ['mailbox', 'serve'], {
        cwd: projectDir,
        detached: !isWin,
        stdio: 'ignore',
        windowsHide: true,
        shell: isWin,
      });
      // Spawn errors (e.g. wstack not on PATH) surface via the
      // poll-timeout below rather than crashing the agent.
      child.on('error', () => undefined);
      child.unref();
      // Poll for the lock file for up to 5 s.
      const deadline = Date.now() + 5_000;
      while (Date.now() < deadline) {
        await new Promise((r) => setTimeout(r, 200));
        try {
          const raw = await fs.readFile(lockPath, 'utf8');
          const lock = JSON.parse(raw) as { url: string; token: string };
          if (lock.url && lock.token) {
            url = lock.url;
            token = lock.token;
            break;
          }
        } catch {
          // not yet — keep polling
        }
      }
    } catch (err) {
      throw new Error(
        `Could not find or start a WrongStack mailbox bridge for ` +
        `${projectDir}. Tried env vars, the per-project lock + token ` +
        `files, and spawning \`wstack mailbox serve\`. Last error: ` +
        (err instanceof Error ? err.message : String(err)),
      );
    }
  }

  // Set env vars for the inner `mb` helper so it picks them up
  // without further branching. (Strictly optional — could also
  // close over `url` and `token` directly.)
  process.env.WRONGSTACK_MAILBOX_URL = url;
  process.env.WRONGSTACK_MAILBOX_TOKEN = token;
  return mb;
}

Usage:

import * as fs from 'node:fs/promises';
import * as path from 'node:path';

const mb = await mbWithBootstrap('/path/to/wrongstack/project');
const { data } = await mb('/mailbox/query', {
  to: agentId,
  incompleteOnly: true,
  limit: 50,
}) as { data: MailboxMessage[] };

When to prefer mb() over mbWithBootstrap()

If you've already been given a URL + token (env vars, CLI args, a config file), use plain mb(). The bootstrap path is for discovery-first integrations — agents that want to "just connect to whatever's running" without asking the user.

Patterns

Discover a running bridge without env vars

The recommended pattern for an agent that doesn't have WRONGSTACK_MAILBOX_URL / WRONGSTACK_MAILBOX_TOKEN pre-set:

import * as path from 'node:path';

async function findBridge(projectDir: string): Promise<{ url: string; token: string } | null> {
  const lockPath = path.join(projectDir, '.mailbox-bridge.lock');
  try {
    const raw = await fs.readFile(lockPath, 'utf8');
    const lock = JSON.parse(raw) as { url: string; token: string; pid: number };
    if (!lock.url || !lock.token) return null;
    // Optional: ping /healthz to confirm the PID is actually serving
    // (a crashed-but-not-cleaned-up lock would still parse).
    const res = await fetch(`${lock.url}/healthz`, {
      signal: AbortSignal.timeout(500),
    });
    return res.ok ? { url: lock.url, token: lock.token } : null;
  } catch {
    return null;
  }
}

For the "no env vars AND no running surface" case, fall back to mbWithBootstrap() above (which spawns wstack mailbox serve for you and waits for the lock file to appear).

Pick a stable agent id

If you're going to register, pick a stable agentId you can reuse across sessions (so the WebUI can show your read history). Convention:

claude-code-<pid>-<short-hostname>

or any unique-enough string. Do not randomize per call — read receipts break if your agentId changes every poll.

Register once, then heartbeat

Register before you do anything else. Then run a heartbeat every 30 s while you're alive; without it, you flip to "offline" after 60 s and the WebUI hides you.

const agentId = process.env.WRONGSTACK_AGENT_ID
  ?? `claude-code-${process.pid}`;

await mb('/mailbox/agents/register', {
  agentId,
  sessionId: 'external',
  name: 'Claude Code',
  role: 'external',
  pid: process.pid,
});

// Then, while alive:
setInterval(() => {
  mb('/mailbox/agents/heartbeat', {
    agentId,
    currentTask: '<one-line description of what you're doing>',
  }).catch(() => { /* heartbeat is best-effort */ });
}, 30_000);

Real-time push via SSE (preferred) or polling

The bridge supports Server-Sent Events (SSE) on GET /mailbox/events for real-time push. This is the preferred approach — no polling needed.

// Open an SSE connection that pushes events in real-time.
const res = await fetch(`${url}/mailbox/events`, {
  headers: { Authorization: `Bearer ${token}` },
});
const reader = res.body!.getReader();
const decoder = new TextDecoder();

for (;;) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = decoder.decode(value);
  // SSE events arrive as: data: {"type":"message.sent",...}\n\n
  for (const line of text.split('\n')) {
    if (!line.startsWith('data: ')) continue;
    const event = JSON.parse(line.slice(6));
    if (event.type === 'message.sent') {
      console.log(`[${event.type}] ${event.from} → ${event.to}: ${event.messageId}`);
      // Fetch the full message via /mailbox/query or /mailbox/check.
    }
  }
}

SSE event types:

The SSE stream sends a : connected comment on open and a : keepalive comment every 15 s to prevent proxy/CDN timeouts.

Important: SSE events carry only the message id and metadata — not the full message body. When you receive an event, call /mailbox/check or /mailbox/query to fetch the complete message content.

Fallback: polling. If your HTTP client doesn't support SSE (or you're behind a proxy that buffers responses), poll on a 5–10 s interval. Don't poll faster than 1 Hz — the bridge enforces a rate limit of 120 requests per minute per bearer token.

// Fallback: poll every 5 s when SSE is unavailable.
async function pollOnce(): Promise<void> {
  const result = await mb('/mailbox/check', {
    agentId,
    baseId: 'claude-code',       // optional: your bare alias
    limit: 50,
  }) as { data: MailboxMessage[] };

  for (const m of result.data) {
    console.log(`[${m.type}] from=${m.from} subject=${m.subject}`);
    // ...handle the message...
  }
}

setInterval(pollOnce, 5_000);

Use /mailbox/query directly when you need custom searches such as from, type, since, or minPriority filters rather than inbox catch-up.

Reply with replyTo

Set replyTo to the id of the message you're replying to. The original sender's client will then thread your reply to their message. Without replyTo, your reply is a freestanding message and the sender has to match by subject.

await mb('/mailbox/send', {
  from: agentId,
  to: originalMessage.from,
  type: 'result',
  subject: `Re: ${originalMessage.subject}`,
  body: '<your response>',
  replyTo: originalMessage.id,
});

Complete messages while checking inbox

If handling a message finishes the requested work, mark it completed in the same /mailbox/check call. This preserves read receipts and completion state with one batch ack:

const result = await mb('/mailbox/check', {
  agentId,
  baseId: 'claude-code',
  completed: true,
  outcome: 'handled',
}) as { data: MailboxMessage[] };

Use markRead: false to peek without consuming messages:

await mb('/mailbox/check', { agentId, markRead: false });

Ack in batches

If you've just consumed a backlog through custom /mailbox/query filters, don't ack them one at a time. Use /mailbox/ack-many — one HTTP request, one file-lock acquisition, one JSONL rewrite inside WrongStack:

await mb('/mailbox/ack-many', {
  acks: messages.map((m) => ({
    messageId: m.id,
    readerId: agentId,
    read: true,
    completed: true,
    outcome: 'handled',
  })),
});

Prefer this over per-message /mailbox/ack whenever you have more than one unread message.

Broadcast with to: "*"

to: "*" (or "all") reaches every online agent. Use sparingly — the internal WebUI marks broadcasts with a different color and humans notice noise. A reasonable rule: at most one broadcast per task, and always with a clear subject so people can mute it mentally.

await mb('/mailbox/send', {
  from: agentId,
  to: '*',
  type: 'note',
  subject: 'Claude Code: starting security audit',
  body: 'Will report findings via /mailbox/send directed at leader@…',
});

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.

Error shape

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

Recipes

"Is anyone online?"

const result = await mb('/mailbox/agents/online') as { data: AgentStatus[] };
console.log(`${result.data.length} agent(s) online:`);
for (const a of result.data) {
  console.log(`  ${a.agentId}  ${a.status}  ${a.currentTask ?? '(idle)'}`);
}

"Read my inbox"

const result = await mb('/mailbox/query', {
  to: agentId,
  unreadBy: agentId,
  incompleteOnly: true,
  limit: 20,
}) as { data: MailboxMessage[] };
for (const m of result.data) {
  console.log(`[${m.type}] ${m.from}: ${m.subject}`);
  console.log(`  ${m.body}`);
}

"Reply to the most recent message directed at me"

const { data: messages } = await mb('/mailbox/query', {
  to: agentId,
  incompleteOnly: true,
  limit: 1,
}) as { data: MailboxMessage[] };
const latest = messages[0];
if (!latest) return;

await mb('/mailbox/send', {
  from: agentId,
  to: latest.from,
  type: 'result',
  subject: `Re: ${latest.subject}`,
  body: '<your reply>',
  replyTo: latest.id,
});
await mb('/mailbox/ack', {
  messageId: latest.id,
  readerId: agentId,
  read: true,
  completed: true,
});

"Broadcast a status update"

await mb('/mailbox/send', {
  from: agentId,
  to: '*',
  type: 'status',
  subject: 'Claude Code: <one-line summary>',
  body: '<details>',
});

Anti-patterns

• Don't bypass the HTTP layer to read the JSONL directly. The bridge exists so external agents don't have to honor the file-lock protocol. Reading the file directly can race with GlobalMailbox.ack rewrites and silently corrupt state.
• Don't reuse one agentId across multiple external sessions. If two processes register under the same id, heartbeats overwrite each other and read receipts become unreliable.
• Don't poll faster than 1 Hz. The bridge enforces a rate limit of 120 requests/min per bearer token (returns 429 RATE_LIMITED beyond that). Prefer SSE (GET /mailbox/events) over polling when possible.
• Don't include the token in any logged output. It's the only credential. If you must print the URL, redact the token ([REDACTED]).
• Don't reply to a broadcast with another broadcast. Replies should target the original sender via to: <their-id>, with replyTo set.
• Don't use control messages. They go through a different path in the WrongStack agent loop and will likely be dropped on the floor by the recipient.

Example: minimal end-to-end session

// 1. Confirm the bridge is up.
await mb('/healthz'); // throws if down

// 2. Pick a stable id and register.
const agentId = `claude-code-${process.pid}`;
await mb('/mailbox/agents/register', {
  agentId,
  sessionId: 'external',
  name: 'Claude Code',
  role: 'external',
  pid: process.pid,
});

// 3. Heartbeat every 30 s.
setInterval(() => {
  mb('/mailbox/agents/heartbeat', { agentId }).catch(() => undefined);
}, 30_000);

// 4. Poll for new mail every 5 s.
let lastSeen: string | undefined;
setInterval(async () => {
  try {
    const args: Record<string, unknown> = {
      to: agentId,
      incompleteOnly: true,
      limit: 50,
    };
    if (lastSeen !== undefined) args['since'] = lastSeen;
    const { data } = await mb('/mailbox/query', args) as { data: MailboxMessage[] };
    for (const m of data) {
      // ...your handling logic here...
      console.log(`[${m.type}] ${m.from}: ${m.subject}`);
    }
    if (data.length > 0) lastSeen = data[data.length - 1]!.timestamp;
  } catch (err) {
    console.error('mailbox poll failed:', (err as Error).message);
  }
}, 5_000);

This is the smallest viable integration. From here, the typical extension is to act on the messages — call tools, write files, run tests — and post results back via /mailbox/send.

How this skill is shipped

This file is bundled inside @wrongstack/core at packages/core/skills/wrongstack-mailbox/SKILL.md and exported via the package's wildcard ./skills/* export. To install it into an external agent's project (e.g. Claude Code's .claude/skills/):

bash scripts/install-mailbox-bridge-skills.sh ~/.claude/skills

The script is idempotent — re-running overwrites existing copies with the latest bundled version.

After installation, the external agent can talk to any WrongStack project whose bridge is already running (most common case — the user opens wstack --repl or wstack --webui and the bridge auto-bootstraps). mbWithBootstrap() handles discovery without requiring the user to copy URL/token env vars around.

If no WrongStack surface is running yet, the user starts one — wstack --repl, wstack --webui, wstack --eternal, or wstack mailbox serve standalone all work. The first one to come up for a given project starts the bridge; subsequent surfaces join it via the per-project lock.

Skills in scope

• node-modern — AbortSignal.timeout, ESM-only imports.
• output-standards — when reporting mailbox activity to the user, shape it as the project's standard output.
• prompt-engineering — when composing subject/body text that other agents will read, keep it specific and short.