beeperbox 0.8.0 → 0.9.0

package/README.md

@@ -1,18 +1,28 @@
-# beeperbox (lite mode)
+```
+                ╭──────────────────────────────────╮
+                │  ╔╗ ╔═╗╔═╗╔═╗╔═╗╦═╗╔╗ ╔═╗ ╦ ╦    │
+                │  ╠╩╗╠╣ ╠╣ ╠═╝╠╣ ╠╦╝╠╩╗║ ║ ╚╦╝    │
+                │  ╚═╝╚═╝╚═╝╩  ╚═╝╩╚═╚═╝╚═╝ ╩ ╩    │
+                │   one agent ──→ 50+ messengers   │
+                ╰──────────────────────────────────╯
+```
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/beeperbox"><img src="https://img.shields.io/npm/v/beeperbox?label=npm&color=2a4f8c" alt="npm version"></a>
+  <a href="https://github.com/hamr0/beeperbox"><img src="https://img.shields.io/badge/source-github-2a4f8c" alt="source on GitHub"></a>
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+</p>
 
 **Run beeperbox's MCP verb server against a Beeper Desktop you already have open — no Docker, no Electron, no Xvfb.**
 
 This is the *lite* half of [beeperbox](https://github.com/hamr0/beeperbox). The full project ships a Docker image with a headless Beeper Desktop inside; lite mode is the same single-file, zero-dependency MCP server pointed at a Beeper Desktop **you** run on your laptop. Identical verb surface, identical version — you just supply Beeper.
 
-- **Always-on / VPS / no local Beeper?** Use the [Docker image](https://github.com/hamr0/beeperbox#quick-start).
+- **Always-on / VPS / no local Beeper?** Use the [Docker image](https://github.com/hamr0/beeperbox#quick-start-container).
 - **Beeper already open on your machine?** Use this.
 
-## Prerequisites
+## Quick start
 
-1. **Beeper Desktop** running locally.
-2. **Developer API enabled:** Beeper → **Settings → Developers** → enable the API and create an access token (the same token the container uses).
-
-## Run
+**Prereqs:** Beeper Desktop running locally, with the Developer API enabled — Beeper → **Settings → Developers** → enable the API and create an access token (the same token the container uses).
 
 ```sh
 BEEPER_TOKEN=your-token-here npx beeperbox
@@ -20,12 +30,22 @@ BEEPER_TOKEN=your-token-here npx beeperbox
 
 That starts the MCP HTTP server on `http://127.0.0.1:23375`, pointed at the local Beeper Desktop API on `http://127.0.0.1:23373`. On boot it logs a one-line reachability verdict (`preflight OK: … N account(s)` or `preflight FAIL: …`) so a misconfigured token or API is obvious immediately.
 
-For stdio transport (Claude Code, Cursor, Cline, Continue, bareagent):
+For stdio transport (Claude Code, Cursor, Cline, Continue, [bareagent](https://npmjs.com/package/bare-agent)):
 
 ```sh
 BEEPER_TOKEN=your-token-here npx beeperbox --stdio
 ```
 
+## The 12 tools
+
+One opinionated MCP verb layer over Beeper — every tool returns a normalized `Chat` / `Message` schema, propagates `chat_id` + `network` onto every message, and is documented in-schema for the model. Reach across all 50+ networks without knowing which bridge you're talking to.
+
+- **Read / triage** — `list_accounts` · `list_inbox` · `list_unread` · `get_chat` · `read_chat` · `search_messages`
+- **Write / act** — `send_message` · `note_to_self` · `react_to_message` · `archive_chat`
+- **Watch / reach** — `poll_messages` (read-only watch primitive, restart-safe cursor, `source` echo-guard) · `download_asset` (attachment bytes; every message carries `attachments[]`)
+
+Full schemas and usage in the [main README](https://github.com/hamr0/beeperbox#the-mcp).
+
 ## Config
 
 | Env | Meaning | Default |
@@ -45,6 +65,19 @@ The server binds **loopback only** (`127.0.0.1`) by default, so it's safe with n
 
 There's no Docker restart policy in lite mode. For an always-on setup, run it under `systemd` or `pm2`.
 
-See the [full README](https://github.com/hamr0/beeperbox#lite-mode) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build.
+See the [full README](https://github.com/hamr0/beeperbox#the-mcp) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build.
+
+## The bare ecosystem
+
+Local-first, composable agent infrastructure. Same API patterns throughout — mix and match, each module works standalone.
+
+- **[bareagent](https://npmjs.com/package/bare-agent)** — the think→act→observe loop. *Goal in → coordinated actions out.*
+- **[bareguard](https://npmjs.com/package/bareguard)** — the single gate every action passes through. *Action in → allow / deny / ask-a-human out.*
+- **[litectx](https://npmjs.com/package/litectx)** — code + memory graph with activation decay. *Query in → ranked context out.*
+- **[barebrowse](https://npmjs.com/package/barebrowse)** — a real browser for agents. *URL in → pruned snapshot out.*
+- **[baremobile](https://npmjs.com/package/baremobile)** — Android + iOS device control. *Screen in → pruned snapshot out.*
+- **beeperbox** *(this)* — 50+ messaging networks via one MCP server. *Chat in → unified message stream out.*
+
+## License
 
-[Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE)
+[Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE). Independent wrapper around Beeper Desktop, no affiliation with Beeper / Automattic.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beeperbox",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Lite mode for beeperbox — the opinionated MCP verb server for Beeper Desktop, run standalone against a Beeper you already have open (no Docker, no Electron). The full headless-Beeper-in-Docker build lives at github.com/hamr0/beeperbox.",
   "bin": {
     "beeperbox": "server.js"
@@ -34,7 +34,7 @@
     "url": "git+https://github.com/hamr0/beeperbox.git",
     "directory": "mcp"
   },
-  "homepage": "https://github.com/hamr0/beeperbox#lite-mode",
+  "homepage": "https://github.com/hamr0/beeperbox#lite-mode-npx",
   "bugs": "https://github.com/hamr0/beeperbox/issues",
   "author": "hamr0",
   "license": "Apache-2.0"

package/server.js

@@ -95,6 +95,21 @@ const ASSET_TIMEOUT_MS = envIntNonNeg('BEEPERBOX_ASSET_TIMEOUT_MS', 30000);
 // neither, so this is its boot sanity check. Opt out with BEEPERBOX_PREFLIGHT=0.
 const PREFLIGHT_TIMEOUT_MS = envIntNonNeg('BEEPERBOX_PREFLIGHT_TIMEOUT_MS', 5000);
 
+// The accountID -> network map is cached so chat normalizers don't re-fetch
+// /v1/accounts on every call. But an UNBOUNDED cache is a resilience bug: an
+// account added at runtime (e.g. WhatsApp via noVNC) would render network
+// "unknown" in every chat verb until the MCP *process* restarts, and an empty/
+// partial map captured during the backend's post-restart sync window would
+// freeze for the whole process life — so a plain `docker restart` re-poisons it
+// from a still-syncing backend and the account list stays wrong (the exact wedge
+// multis reported). Bound it with a TTL, and never cache an EMPTY result. Set to
+// 0 to disable caching (always read live).
+const ACCOUNT_CACHE_TTL_MS = envIntNonNeg('BEEPERBOX_ACCOUNT_CACHE_TTL_MS', 60000);
+
+// Injectable clock — overridable in tests so the TTL is verifiable without a
+// real sleep. Production reads the wall clock.
+let nowFn = () => Date.now();
+
 // Real attachment src_urls come in two shapes: remote Matrix content
 // (mxc:// / localmxc://) and, once Beeper caches the file locally,
 // file:///root/.config/BeeperTexts/media/... — verified against a live account.
@@ -293,17 +308,59 @@ async function getNoteToSelfChatID() {
   throw rpcError(-32002, 'note-to-self chat not found in top 100 chats — open Beeper Desktop and verify a "Note to self" chat exists');
 }
 
+// Unwrap /v1/accounts into a bare array — Beeper returns a bare array today, but
+// tolerate a {items:[...]} envelope. One place so list_accounts, getAccountMap,
+// and preflight agree.
+function accountList(accounts) {
+  return Array.isArray(accounts) ? accounts : (accounts?.items || []);
+}
+
+// accountCache: { map, at } | null. Bounded by ACCOUNT_CACHE_TTL_MS and NEVER
+// populated from an empty result — see ACCOUNT_CACHE_TTL_MS above for why the old
+// unbounded cache wedged after a runtime account-add / post-restart sync window.
 async function getAccountMap() {
-  if (accountCache) return accountCache;
-  const accounts = await beeperFetch('/v1/accounts');
-  accountCache = {};
-  for (const a of (Array.isArray(accounts) ? accounts : (accounts.items || []))) {
-    accountCache[a.accountID] = {
-      network: networkSlug(a.network),
-      network_label: a.network,
-    };
+  const now = nowFn();
+  const cacheValid =
+    accountCache &&
+    ACCOUNT_CACHE_TTL_MS > 0 &&
+    (now - accountCache.at) < ACCOUNT_CACHE_TTL_MS;
+  if (cacheValid) return accountCache.map;
+
+  const list = accountList(await beeperFetch('/v1/accounts'));
+  const map = {};
+  for (const a of list) {
+    map[a.accountID] = { network: networkSlug(a.network), network_label: a.network };
+  }
+  // An empty /v1/accounts is almost always the backend mid-sync (just after a
+  // restart or an account-add), not a real "no accounts" state. Caching it would
+  // freeze every chat verb's network labels until the *process* restarts. Serve
+  // it for THIS call (the verb still returns, just with "unknown" labels) but
+  // leave the cache empty so the very next call re-reads and self-heals the
+  // moment the backend populates. Log it so a recurrence is diagnosable, not silent.
+  if (list.length === 0) {
+    process.stderr.write('[beeperbox-mcp] /v1/accounts returned 0 accounts — Beeper may still be syncing; not caching, will re-read next call\n');
+    accountCache = null;
+    return map;
   }
-  return accountCache;
+  accountCache = { map, at: now };
+  return map;
+}
+
+// Map one raw /v1/accounts entry into the list_accounts shape. `status` is the
+// backend's per-account connection state ("connected" / "connecting" / …) —
+// surfaced (not dropped) so a caller can tell a still-syncing bridge from a real
+// one instead of reading a transient as "gone".
+function normalizeAccount(a) {
+  return {
+    account_id: a.accountID,
+    network: networkSlug(a.network),
+    network_label: a.network,
+    status: a.status || null,
+    user: {
+      id: a.user?.id || null,
+      display_name: a.user?.fullName || a.user?.displayText || a.user?.username || null,
+    },
+  };
 }
 
 // ─── chat normalizer ──────────────────────────────────────────────
@@ -673,7 +730,7 @@ function applyEchoTags(messages, now) {
 const TOOLS = [
   {
     name: 'list_accounts',
-    description: 'List all messaging accounts (networks) connected to this Beeper account. Each account corresponds to one platform — WhatsApp, Telegram, Discord, etc. Use this to see which platforms are reachable before calling other tools, or to discover what kinds of chats exist. Returns network slug (machine-readable, e.g. "whatsapp"), network label (human, e.g. "WhatsApp"), the underlying account ID, and the user\'s display name on that platform.',
+    description: 'List all messaging accounts (networks) connected to this Beeper account. Each account corresponds to one platform — WhatsApp, Telegram, Discord, etc. Use this to see which platforms are reachable before calling other tools, or to discover what kinds of chats exist. Returns network slug (machine-readable, e.g. "whatsapp"), network label (human, e.g. "WhatsApp"), the underlying account ID, the bridge connection `status` ("connected", "connecting", etc. — lets you tell a still-syncing account from a real one rather than reading a transient as "gone"), and the user\'s display name on that platform.',
     inputSchema: {
       type: 'object',
       properties: {},
@@ -827,17 +884,15 @@ const TOOLS = [
 async function callTool(name, args) {
   switch (name) {
     case 'list_accounts': {
-      const accounts = await beeperFetch('/v1/accounts');
-      const list = Array.isArray(accounts) ? accounts : (accounts.items || []);
-      return list.map((a) => ({
-        account_id: a.accountID,
-        network: networkSlug(a.network),
-        network_label: a.network,
-        user: {
-          id: a.user?.id || null,
-          display_name: a.user?.fullName || a.user?.displayText || a.user?.username || null,
-        },
-      }));
+      const list = accountList(await beeperFetch('/v1/accounts'));
+      // A live read, so a 0 here is the backend's current truth — but that is far
+      // more often "Beeper still syncing after a restart/account-add" than a real
+      // empty account set. Log it so the operator can tell the difference instead
+      // of silently relaying an ambiguous empty list.
+      if (list.length === 0) {
+        process.stderr.write('[beeperbox-mcp] list_accounts: backend /v1/accounts returned 0 accounts — Beeper may still be syncing (retry shortly)\n');
+      }
+      return list.map(normalizeAccount);
     }
 
     case 'get_chat': {
@@ -1173,8 +1228,7 @@ async function preflight() {
     return;
   }
   try {
-    const accounts = await beeperFetch('/v1/accounts', { timeoutMs: PREFLIGHT_TIMEOUT_MS });
-    const list = Array.isArray(accounts) ? accounts : (accounts?.items || []);
+    const list = accountList(await beeperFetch('/v1/accounts', { timeoutMs: PREFLIGHT_TIMEOUT_MS }));
     say(`preflight OK: ${BEEPER_API} reachable, token accepted, ${list.length} account(s)`);
   } catch (e) {
     say(`preflight FAIL: ${BEEPER_API} unreachable or token rejected — ${e.message}`);
@@ -1310,6 +1364,7 @@ module.exports = {
   selectDelivery,
   textHash,
   normalizeAttachments,
+  normalizeAccount,
   assertServableSrcUrl,
   matchSentMessage,
   recordSent,
@@ -1317,4 +1372,8 @@ module.exports = {
   loadLedger,
   // test hook: drop the in-memory ledger so a test can re-load from a fresh path
   _resetLedger: () => { ledger = null; ledgerPersistWarned = false; },
+  // account-map cache surface (resilience): the map + its TTL/empty-cache rules.
+  getAccountMap,
+  _resetAccountCache: () => { accountCache = null; },
+  _setNow: (fn) => { nowFn = fn || (() => Date.now()); },
 };