ghostbus 0.0.0-stage → 0.5.2

package/src/handler.mjs

@@ -0,0 +1,166 @@
+/**
+ * GhostBus HTTP request handler — transport logic shared by the single-workspace
+ * relay (http-server.mjs) and the hosted multi-workspace server (hosted-server.mjs).
+ *
+ * createBusHandler({ id, bus, key }) -> async (req, res, url)
+ * - `url` is a URL whose pathname is the path WITHIN the workspace (any
+ *   /w/<id> prefix already stripped by the caller).
+ * - `key` is the workspace key ('' = open). /health, /probe and the board page
+ *   stay open; everything else needs the key when one is set.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import { GHOSTBUS_VERSION } from './core.mjs';
+import { TOOLS, callTool } from './tools.mjs';
+
+export const BOARD_HTML = fs.readFileSync(new URL('./board.html', import.meta.url), 'utf8');
+
+const agentTokenOf = (req, body = {}, q = {}) =>
+  body.token || q.token || req.headers['x-agent-token'] || null;
+
+const hashEq = (given, expected) => {
+  const a = Buffer.from(crypto.createHash('sha256').update(String(given)).digest('hex'));
+  const b = Buffer.from(crypto.createHash('sha256').update(String(expected)).digest('hex'));
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+};
+export const keyMatches = (given, expected) => !!expected && !!given && hashEq(given, expected);
+
+export function createBusHandler({ id = 'default', bus, key = '' }) {
+  const buckets = new Map();
+  const rateOk = (req) => {
+    const ip = (req.socket && req.socket.remoteAddress) || 'unknown';
+    const t = Date.now();
+    let b = buckets.get(ip);
+    if (!b || t - b.start > 60_000) { b = { start: t, count: 0 }; buckets.set(ip, b); }
+    b.count += 1;
+    return b.count <= 300;
+  };
+  const keyOk = (req) => {
+    if (!key) return true;
+    const given = req.headers['x-bus-key'] || String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
+    return keyMatches(given, key);
+  };
+
+  return async function handle(req, res, url) {
+    res.setHeader('x-content-type-options', 'nosniff');
+    res.setHeader('referrer-policy', 'no-referrer');
+    const send = (status, obj, type = 'application/json') => {
+      const body = type === 'application/json' ? JSON.stringify(obj) : String(obj);
+      res.writeHead(status, { 'content-type': type }); res.end(body);
+    };
+    if (!rateOk(req) && url.pathname !== '/health' && url.pathname !== '/probe') {
+      return send(429, { error: 'rate limit: 300 requests/min per IP per workspace' });
+    }
+    const readBody = () => new Promise((resolve) => {
+      let data = ''; req.on('data', c => { data += c; if (data.length > 5_000_000) req.destroy(); });
+      req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch { resolve(null); } });
+    });
+
+    try {
+      if (req.method === 'GET' && url.pathname === '/') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); return res.end(BOARD_HTML); }
+      if (req.method === 'GET' && url.pathname === '/health') return send(200, { ok: true, server: 'ghostbus', workspace: id, version: GHOSTBUS_VERSION });
+      if (req.method === 'GET' && url.pathname === '/probe') {
+        const s = await bus.status();
+        return send(200, { workspace: id, queued: s.tasks.queued, needsApproval: s.tasks.needsApproval, agents: s.agents, version: GHOSTBUS_VERSION });
+      }
+      if (!keyOk(req)) return send(401, { error: 'missing or wrong bus key' });
+
+      if (req.method === 'GET' && url.pathname === '/api/stream') {
+        const agent = url.searchParams.get('agent');
+        if (!agent) return send(400, { error: 'agent query param required' });
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+        res.write(`event: ready\ndata: ${JSON.stringify({ agent, workspace: id, version: GHOSTBUS_VERSION })}\n\n`);
+        const off = bus.onEvent((ev) => {
+          const forMe = ev.type === 'message.send' ? (ev.to === agent || ev.to === '*' || ev.actor === agent) : true;
+          if (!forMe) return;
+          res.write(`event: ${ev.type}\ndata: ${JSON.stringify(ev)}\n\n`);
+        });
+        const ping = setInterval(() => res.write(': ping\n\n'), 25000);
+        req.on('close', () => { clearInterval(ping); off(); });
+        return;
+      }
+
+      if (req.method === 'GET' && url.pathname === '/api/wait') {
+        const agent = url.searchParams.get('agent');
+        if (!agent) return send(400, { error: 'agent query param required' });
+        const timeout = Math.min(Number(url.searchParams.get('timeout') || 25), 55) * 1000;
+        const sinceSeq = url.searchParams.has('sinceSeq') ? Number(url.searchParams.get('sinceSeq')) : (await bus.sync({})).headSeq;
+        const immediate = await bus.sync({ sinceSeq, limit: 100 });
+        const relevantNow = immediate.events.filter(ev => ev.type !== 'message.send' || ev.to === agent || ev.to === '*' || ev.actor === agent);
+        if (relevantNow.length) return send(200, { events: relevantNow, headSeq: immediate.headSeq, waited: false });
+        return await new Promise((resolve) => {
+          let done = false;
+          const finish = (events) => { if (done) return; done = true; off(); clearTimeout(timer); resolve(send(200, { events, headSeq: events.length ? events[events.length - 1].seq : sinceSeq, waited: true })); };
+          const off = bus.onEvent((ev) => {
+            if (ev.seq <= sinceSeq) return;
+            if (ev.type === 'message.send' && !(ev.to === agent || ev.to === '*' || ev.actor === agent)) return;
+            finish([ev]);
+          });
+          const timer = setTimeout(() => finish([]), timeout);
+          req.on('close', () => { if (!done) { done = true; off(); clearTimeout(timer); resolve(); } });
+        });
+      }
+
+      if (req.method === 'POST' && url.pathname === '/mcp') {
+        const msg = await readBody();
+        if (!msg) return send(400, { error: 'invalid JSON body' });
+        if (msg.method === 'tools/list') return send(200, { jsonrpc: '2.0', id: msg.id, result: { tools: TOOLS } });
+        if (msg.method === 'tools/call') {
+          try {
+            const argsIn = { ...(msg.params.arguments || {}) };
+            const hdrToken = req.headers['x-agent-token'];
+            if (hdrToken && !argsIn.token) argsIn.token = hdrToken;
+            const out = await callTool(bus, msg.params.name, argsIn);
+            return send(200, { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: JSON.stringify(out, null, 2) }] } });
+          } catch (e) { return send(200, { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true } }); }
+        }
+        return send(400, { error: `unsupported MCP method over HTTP relay: ${msg.method} (use tools/list or tools/call)` });
+      }
+
+      const body = ['POST', 'PUT', 'DELETE'].includes(req.method) ? await readBody().catch(() => ({})) : {};
+      const safeBody = body && typeof body === 'object' ? body : {};
+      const q = Object.fromEntries(url.searchParams);
+
+      if (req.method === 'GET' && url.pathname === '/api/status') return send(200, await bus.status());
+      if (req.method === 'GET' && url.pathname === '/api/agents') return send(200, { agents: await bus.listAgents() });
+      if (req.method === 'POST' && url.pathname === '/api/agents') return send(200, await bus.registerAgent({ name: safeBody.agent, role: safeBody.role, capabilities: safeBody.capabilities, token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'POST' && url.pathname === '/api/messages') return send(200, await bus.sendMessage({ from: safeBody.agent, to: safeBody.to ?? '*', body: safeBody.body, channel: safeBody.channel ?? 'general', threadId: safeBody.threadId ?? null, token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'GET' && url.pathname === '/api/inbox') return send(200, { messages: await bus.inbox(q.agent, { unreadOnly: q.unread === '1', limit: Number(q.limit || 50), token: agentTokenOf(req, {}, q) }) });
+      if (req.method === 'POST' && url.pathname === '/api/heartbeat') return send(200, await bus.heartbeat({ name: safeBody.agent, token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'GET' && url.pathname === '/api/search') return send(200, await bus.search(q.q || '', { limit: Number(q.limit || 20) }));
+      if (req.method === 'GET' && url.pathname === '/api/channels') return send(200, { channels: await bus.listChannels() });
+      if (req.method === 'POST' && url.pathname === '/api/tasks') return send(200, await bus.createTask({ from: safeBody.agent, title: safeBody.title, body: safeBody.body ?? '', assignee: safeBody.assignee ?? null, priority: safeBody.priority ?? 'normal', needsApproval: !!safeBody.needsApproval, blockedBy: safeBody.blockedBy ?? [], token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'GET' && url.pathname === '/api/tasks') return send(200, { tasks: await bus.listTasks({ status: q.status || null, assignee: q.assignee || null }) });
+      const taskAction = url.pathname.match(/^\/api\/tasks\/(\d+)\/(approve|claim|complete|cancel)$/);
+      if (req.method === 'POST' && taskAction) {
+        const [, tid, action] = taskAction;
+        const tk = agentTokenOf(req, safeBody);
+        if (action === 'approve') return send(200, await bus.approveTask(tid, { by: safeBody.agent, token: tk }));
+        if (action === 'claim') return send(200, await bus.claimTask(tid, { by: safeBody.agent, token: tk }));
+        if (action === 'complete') return send(200, await bus.completeTask(tid, { by: safeBody.agent, result: safeBody.result ?? '', token: tk }));
+        if (action === 'cancel') return send(200, await bus.cancelTask(tid, { by: safeBody.agent, token: tk }));
+      }
+      const taskComment = url.pathname.match(/^\/api\/tasks\/(\d+)\/comment$/);
+      if (req.method === 'POST' && taskComment) return send(200, await bus.addTaskComment(taskComment[1], { by: safeBody.agent, body: safeBody.body, token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'PUT' && url.pathname === '/api/files') return send(200, await bus.putFile({ by: safeBody.agent, path: safeBody.path, text: safeBody.text, token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'DELETE' && url.pathname === '/api/files') return send(200, await bus.deleteFile({ by: q.agent || safeBody.agent, path: q.path || safeBody.path, token: agentTokenOf(req, safeBody, q) }));
+      if (req.method === 'GET' && url.pathname === '/api/files') return send(200, await bus.getFile(q.path));
+      if (req.method === 'GET' && url.pathname === '/api/files/list') return send(200, { files: await bus.listFiles() });
+      if (req.method === 'GET' && url.pathname === '/api/files/history') return send(200, await bus.fileHistory(q.path));
+      if (req.method === 'PUT' && url.pathname === '/api/context') return send(200, await bus.putContext({ by: safeBody.agent, context: safeBody.context, token: agentTokenOf(req, safeBody) }));
+      if (req.method === 'GET' && url.pathname === '/api/context') return send(200, await bus.getContext());
+      if (req.method === 'GET' && url.pathname === '/api/board') return send(200, { board: await bus.board() });
+      if (req.method === 'GET' && url.pathname === '/api/events') return send(200, { events: await bus.events({ limit: Number(q.limit || 50) }) });
+      if (req.method === 'GET' && url.pathname === '/api/sync') return send(200, await bus.sync({ sinceSeq: Number(q.sinceSeq || 0), limit: Number(q.limit || 500) }));
+      if (req.method === 'GET' && url.pathname === '/api/capsules') return send(200, { capsules: await bus.listCapsules() });
+      const capsuleGet = url.pathname.match(/^\/api\/capsules\/([a-z0-9-]+)$/);
+      if (req.method === 'GET' && capsuleGet) return send(200, await bus.getCapsule(capsuleGet[1], { create: q.create === '1', by: q.agent || null }));
+      const capsulePut = url.pathname.match(/^\/api\/capsules\/([a-z0-9-]+)\/section$/);
+      if (req.method === 'POST' && capsulePut) return send(200, await bus.updateCapsule(capsulePut[1], { by: safeBody.agent, section: safeBody.section, text: safeBody.text, token: agentTokenOf(req, safeBody) }));
+
+      return send(404, { error: 'not found' });
+    } catch (e) {
+      return send(400, { error: e.message, code: e.code || undefined });
+    }
+  };
+}

package/src/hosted-server.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * GhostBus HOSTED server — many isolated workspaces, one process.
+ *
+ *   GHOSTBUS_ADMIN_KEY=<long secret> node src/hosted-server.mjs [--port 8388] [--data-dir ./ghostbus-hosted]
+ *
+ * - Each workspace lives under /w/<id>/… (board at /w/<id>/, REST at
+ *   /w/<id>/api/*, MCP at /w/<id>/mcp, probe at /w/<id>/probe).
+ * - Workspaces are fully isolated: separate stores, agents, tasks, files.
+ * - Every workspace gets its OWN key at creation (returned once; only its
+ *   SHA-256 is kept in the registry). The admin key manages workspaces and
+ *   also works as a master key inside any workspace.
+ * - Admin API (x-bus-key: <admin key>):
+ *     POST   /api/workspaces {id?, name}   -> {id, name, key (once)}
+ *     GET    /api/workspaces               -> [{id, name, createdAt, agents, queued}]
+ *     DELETE /api/workspaces/<id>          -> removes registry entry + data file
+ *     POST   /api/workspaces/<id>/rotate-key -> {id, key (once)}; old key dies at once
+ *     GET    /api/workspaces/<id>/export   -> full-state export envelope (backup/migrate)
+ *     POST   /api/workspaces/import {id?, name?, state|export} -> {id, name, key (once)}
+ * - Registry + one data file per workspace live in the data dir.
+ * - Per-agent tokens are ENFORCED in all workspaces by default (v0.5.2):
+ *   hosted mode serves strangers, so a stolen agent name must not be enough
+ *   to act. GHOSTBUS_REQUIRE_TOKENS=0 is the only opt-out and starts with a
+ *   loud warning. GHOSTBUS_ADMIN_KEY is required and must be at least 16
+ *   characters — it is the operator root key (see docs/hosted.md).
+ */
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { createBus, FileStore, GHOSTBUS_VERSION, validateSnapshot } from './core.mjs';
+import { createBusHandler, keyMatches } from './handler.mjs';
+
+const argv = process.argv.slice(2);
+const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
+const port = Number(argVal('--port') || process.env.GHOSTBUS_PORT || 8388);
+const dataDir = argVal('--data-dir') || process.env.GHOSTBUS_DATA_DIR || './ghostbus-hosted';
+const ADMIN_KEY = process.env.GHOSTBUS_ADMIN_KEY || '';
+// v0.5.2: enforcement is the hosted DEFAULT. Only an explicit
+// GHOSTBUS_REQUIRE_TOKENS=0 turns it off (anything else, including unset,
+// means on) — the hosted server is the one deployment that serves people
+// other than the operator, so the safe posture cannot be opt-in.
+const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS !== '0';
+
+if (!ADMIN_KEY) {
+  process.stderr.write('GHOSTBUS_ADMIN_KEY is required for the hosted server (workspace creation must not be open).\n');
+  process.exit(2);
+}
+if (ADMIN_KEY.length < 16) {
+  process.stderr.write('GHOSTBUS_ADMIN_KEY is too short: use at least 16 characters (32+ random hex recommended). The admin key is the operator root key — it creates/deletes workspaces and acts as a master key inside every one of them.\n');
+  process.exit(2);
+}
+if (!REQUIRE_TOKENS) {
+  process.stderr.write('WARNING: GHOSTBUS_REQUIRE_TOKENS=0 — per-agent token enforcement is DISABLED in every workspace.\n');
+  process.stderr.write('WARNING: anyone holding a workspace key can act under ANY agent name in that workspace (impersonation).\n');
+  process.stderr.write('WARNING: hosted mode serves strangers; run with enforcement on unless you have a specific reason not to.\n');
+}
+
+fs.mkdirSync(dataDir, { recursive: true });
+const registryPath = path.join(dataDir, 'registry.json');
+const loadRegistry = () => { try { return JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return { workspaces: {} }; } };
+const saveRegistry = (reg) => {
+  // Unique temp per save: two processes sharing this registry must never
+  // collide on one fixed '.tmp' name (first rename wins, second throws ENOENT).
+  const tmp = registryPath + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
+  try {
+    fs.writeFileSync(tmp, JSON.stringify(reg, null, 2));
+    fs.renameSync(tmp, registryPath);
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* already renamed away */ }
+  }
+};
+const sha256 = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
+const validId = (id) => /^[a-z0-9][a-z0-9-]{1,62}$/.test(String(id || ''));
+
+const buses = new Map(); // id -> {bus, handle}
+async function getWorkspace(id) {
+  if (buses.has(id)) return buses.get(id);
+  const reg = loadRegistry();
+  const meta = reg.workspaces[id];
+  if (!meta) return null;
+  const bus = await createBus(new FileStore(path.join(dataDir, `${id}.json`)), { id, name: meta.name }, { requireTokens: REQUIRE_TOKENS });
+  const entry = { bus, meta };
+  buses.set(id, entry);
+  return entry;
+}
+
+// Per-workspace handler cache with hash-based key check: we build the core
+// handler with key '' (open) and gate in the router using the stored hash.
+const handlers = new Map();
+function handlerFor(id, bus) {
+  if (!handlers.has(id)) handlers.set(id, createBusHandler({ id, bus, key: '' }));
+  return handlers.get(id);
+}
+
+const isAdmin = (req) => keyMatches(req.headers['x-bus-key'] || String(req.headers.authorization || '').replace(/^Bearer\s+/i, ''), ADMIN_KEY);
+const wsKeyOk = (req, meta) => {
+  const given = req.headers['x-bus-key'] || String(req.headers.authorization || '').replace(/^Bearer\s+/i, '');
+  if (!given) return false;
+  if (keyMatches(given, ADMIN_KEY)) return true; // master key
+  return sha256(given) === meta.keyHash;
+};
+
+const LANDING = `<!doctype html><html><head><meta charset="utf-8"><title>GhostBus Hosted</title>
+<style>body{font-family:system-ui;background:#0e0c14;color:#ece8f5;margin:0;padding:40px}h1{font-size:22px}code{background:#17131f;padding:2px 7px;border-radius:6px;color:#c9b8ff}p{color:#9b8fb5;max-width:640px;line-height:1.55}</style></head>
+<body><h1>👻 GhostBus Hosted</h1>
+<p>Multi-workspace agent message bus. Each workspace lives at <code>/w/&lt;id&gt;/</code> with its own board, REST API, MCP endpoint, and key. Workspace data is never shown here — open your workspace board with its key.</p>
+<p>Operators: see <code>POST /api/workspaces</code> (admin key) and the repo's <code>docs/hosted.md</code>.</p>
+<p style="font-size:13px">GhostBus v${GHOSTBUS_VERSION} · Ghost Developer Studio</p></body></html>`;
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url, 'http://localhost');
+  const send = (status, obj, type = 'application/json') => {
+    const b = type === 'application/json' ? JSON.stringify(obj) : String(obj);
+    res.writeHead(status, { 'content-type': type }); res.end(b);
+  };
+  res.setHeader('x-content-type-options', 'nosniff');
+  res.setHeader('referrer-policy', 'no-referrer');
+  const readBody = () => new Promise((resolve) => {
+    let data = ''; req.on('data', c => { data += c; if (data.length > 5_000_000) req.destroy(); });
+    req.on('end', () => { try { resolve(data ? JSON.parse(data) : {}); } catch { resolve(null); } });
+  });
+
+  try {
+    if (req.method === 'GET' && url.pathname === '/') { res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }); return res.end(LANDING); }
+    if (req.method === 'GET' && url.pathname === '/health') return send(200, { ok: true, server: 'ghostbus-hosted', version: GHOSTBUS_VERSION, workspaces: Object.keys(loadRegistry().workspaces).length });
+
+    // ---- admin ----
+    if (url.pathname === '/api/workspaces' && req.method === 'POST') {
+      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      const body = await readBody();
+      if (!body) return send(400, { error: 'invalid JSON body' });
+      const reg = loadRegistry();
+      const id = body.id || `ws-${crypto.randomBytes(4).toString('hex')}`;
+      if (!validId(id)) return send(400, { error: 'workspace id: lowercase letters, digits, - (2-63 chars)' });
+      if (reg.workspaces[id]) return send(409, { error: `workspace already exists: ${id}` });
+      const key = crypto.randomBytes(24).toString('hex');
+      reg.workspaces[id] = { name: String(body.name || id).slice(0, 120), keyHash: sha256(key), createdAt: new Date().toISOString() };
+      saveRegistry(reg);
+      return send(201, { id, name: reg.workspaces[id].name, key, keyNote: 'Workspace key — shown ONCE, only its hash is stored. Agents use it as x-bus-key (or Bearer) under /w/' + id + '/.', board: `/w/${id}/` });
+    }
+    if (url.pathname === '/api/workspaces' && req.method === 'GET') {
+      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      const reg = loadRegistry();
+      const out = [];
+      for (const [id, meta] of Object.entries(reg.workspaces)) {
+        const w = await getWorkspace(id);
+        const s = await w.bus.status();
+        out.push({ id, name: meta.name, createdAt: meta.createdAt, agents: s.agents, queued: s.tasks.queued, needsApproval: s.tasks.needsApproval, messages: s.messages });
+      }
+      return send(200, { workspaces: out });
+    }
+    const rotateMatch = url.pathname.match(/^\/api\/workspaces\/([a-z0-9-]+)\/rotate-key$/);
+    if (req.method === 'POST' && rotateMatch) {
+      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      const reg = loadRegistry();
+      const id = rotateMatch[1];
+      if (!reg.workspaces[id]) return send(404, { error: `no such workspace: ${id}` });
+      const key = crypto.randomBytes(24).toString('hex');
+      reg.workspaces[id].keyHash = sha256(key);
+      reg.workspaces[id].keyRotatedAt = new Date().toISOString();
+      saveRegistry(reg);
+      // Refresh the cached meta so the old key dies immediately, not on restart.
+      const cached = buses.get(id);
+      if (cached) cached.meta = reg.workspaces[id];
+      return send(200, { id, key, keyNote: 'New workspace key — shown ONCE. The previous key is invalid from this moment.', keyRotatedAt: reg.workspaces[id].keyRotatedAt });
+    }
+    const exportMatch = url.pathname.match(/^\/api\/workspaces\/([a-z0-9-]+)\/export$/);
+    if (req.method === 'GET' && exportMatch) {
+      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      const id = exportMatch[1];
+      const w = await getWorkspace(id);
+      if (!w) return send(404, { error: `no such workspace: ${id}` });
+      const state = await w.bus.snapshot();
+      return send(200, { ghostbusExport: 1, version: GHOSTBUS_VERSION, exportedAt: new Date().toISOString(), workspace: { id, name: w.meta.name }, state });
+    }
+    if (url.pathname === '/api/workspaces/import' && req.method === 'POST') {
+      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      const body = await readBody();
+      if (!body) return send(400, { error: 'invalid JSON body' });
+      // Accept either a full export envelope or a bare {state} / raw state.
+      const env = body.ghostbusExport ? body : null;
+      const state = env ? env.state : (body.state || body);
+      const bad = validateSnapshot(state);
+      if (bad) return send(400, { error: `invalid snapshot: ${bad}` });
+      const reg = loadRegistry();
+      const id = body.id || (env && env.workspace && env.workspace.id) || state.workspace.id || `ws-${crypto.randomBytes(4).toString('hex')}`;
+      if (!validId(id)) return send(400, { error: 'workspace id: lowercase letters, digits, - (2-63 chars)' });
+      if (reg.workspaces[id]) return send(409, { error: `workspace already exists: ${id} (delete it first, or import under a new id)` });
+      const name = String(body.name || (env && env.workspace && env.workspace.name) || state.workspace.name || id).slice(0, 120);
+      const key = crypto.randomBytes(24).toString('hex');
+      reg.workspaces[id] = { name, keyHash: sha256(key), createdAt: new Date().toISOString(), importedAt: new Date().toISOString() };
+      saveRegistry(reg);
+      // Write the state file first, then load it through the normal path so
+      // the bus sees exactly what a restart would see.
+      const file = path.join(dataDir, `${id}.json`);
+      const tmp = file + '.tmp.' + process.pid + '.' + Math.random().toString(36).slice(2, 10);
+      fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+      fs.renameSync(tmp, file);
+      const w = await getWorkspace(id);
+      const status = await w.bus.status();
+      return send(201, { id, name, key, keyNote: 'Workspace key — shown ONCE, only its hash is stored. Imported workspaces always get a FRESH key; the source key is not carried over.', agents: status.agents, messages: status.messages, tasks: status.tasks.total, board: `/w/${id}/` });
+    }
+    const delMatch = url.pathname.match(/^\/api\/workspaces\/([a-z0-9-]+)$/);
+    if (req.method === 'DELETE' && delMatch) {
+      if (!isAdmin(req)) return send(401, { error: 'admin key required' });
+      const reg = loadRegistry();
+      const id = delMatch[1];
+      if (!reg.workspaces[id]) return send(404, { error: `no such workspace: ${id}` });
+      delete reg.workspaces[id];
+      saveRegistry(reg);
+      buses.delete(id); handlers.delete(id);
+      try { fs.unlinkSync(path.join(dataDir, `${id}.json`)); } catch {}
+      return send(200, { id, deleted: true });
+    }
+
+    // ---- workspace traffic ----
+    const wMatch = url.pathname.match(/^\/w\/([a-z0-9-]+)(\/.*)?$/);
+    if (wMatch) {
+      const id = wMatch[1];
+      const w = await getWorkspace(id);
+      if (!w) return send(404, { error: `no such workspace: ${id}` });
+      const sub = new URL(url.toString());
+      sub.pathname = wMatch[2] || '/';
+      // Open surfaces mirror the single relay: board page, health, probe.
+      const open = sub.pathname === '/' || sub.pathname === '/health' || sub.pathname === '/probe';
+      if (!open && !wsKeyOk(req, w.meta)) return send(401, { error: 'missing or wrong workspace key' });
+      return handlerFor(id, w.bus)(req, res, sub);
+    }
+
+    return send(404, { error: 'not found' });
+  } catch (e) {
+    return send(500, { error: e.message });
+  }
+});
+
+server.listen(port, () => {
+  process.stderr.write(`ghostbus HOSTED v${GHOSTBUS_VERSION} · http://127.0.0.1:${port} · data=${dataDir} · workspaces=${Object.keys(loadRegistry().workspaces).length} · agentTokens=${REQUIRE_TOKENS ? 'enforced' : 'issued, not enforced'}\n`);
+});

package/src/http-server.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * GhostBus HTTP relay (single workspace) — zero dependencies.
+ * Same core + same MCP tools over HTTP: agents that can't share a local file
+ * connect to one relay instead. For many isolated workspaces on one process,
+ * use hosted-server.mjs.
+ *
+ *   node src/http-server.mjs [--port 8377] [--store ./ghostbus-data.json]
+ * Env: GHOSTBUS_PORT, GHOSTBUS_STORE, GHOSTBUS_WORKSPACE_NAME,
+ *      GHOSTBUS_KEY — if set, every /api and /mcp call needs header
+ *      `x-bus-key: <key>` or `Authorization: Bearer <key>`. /health and
+ *      /probe (counts only) stay open.
+ *      GHOSTBUS_REQUIRE_TOKENS=1 enforces per-agent tokens.
+ */
+import http from 'node:http';
+import { createBus, MemoryStore, FileStore, GHOSTBUS_VERSION } from './core.mjs';
+import { createBusHandler } from './handler.mjs';
+
+const argv = process.argv.slice(2);
+const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
+const port = Number(argVal('--port') || process.env.GHOSTBUS_PORT || 8377);
+const storePath = argVal('--store') || process.env.GHOSTBUS_STORE || './ghostbus-data.json';
+const wsName = argVal('--name') || process.env.GHOSTBUS_WORKSPACE_NAME || 'GhostBus Workspace';
+const KEY = process.env.GHOSTBUS_KEY || '';
+
+const REQUIRE_TOKENS = process.env.GHOSTBUS_REQUIRE_TOKENS === '1';
+const store = storePath === ':memory:' ? new MemoryStore() : new FileStore(storePath);
+const bus = await createBus(store, { name: wsName }, { requireTokens: REQUIRE_TOKENS });
+const handle = createBusHandler({ id: 'default', bus, key: KEY });
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, 'http://localhost');
+  handle(req, res, url).catch((e) => { try { res.writeHead(500, { 'content-type': 'application/json' }); res.end(JSON.stringify({ error: e.message })); } catch {} });
+});
+server.listen(port, () => {
+  process.stderr.write(`ghostbus http relay v${GHOSTBUS_VERSION} · http://127.0.0.1:${port} · store=${storePath} · auth=${KEY ? 'workspace key required' : 'open (set GHOSTBUS_KEY)'}\n`);
+  // Node's listen() with no host binds ALL network interfaces, not just
+  // loopback — the 127.0.0.1 above is the local URL, not a bind restriction.
+  // Local trust is the relay's default model and stays unchanged, but an
+  // unkeyed or tokenless relay must never be network-reachable *silently*.
+  if (!KEY) {
+    process.stderr.write('WARNING: GHOSTBUS_KEY is not set — this relay is OPEN: anyone who can reach this port can read and write the workspace.\n');
+    process.stderr.write('WARNING: the relay listens on all network interfaces, not just localhost. Set GHOSTBUS_KEY (a long secret) before exposing it beyond this machine, or firewall the port.\n');
+  } else if (!REQUIRE_TOKENS) {
+    process.stderr.write('WARNING: per-agent tokens are not enforced (GHOSTBUS_REQUIRE_TOKENS is not 1): anyone holding the workspace key can act under any agent name. The relay listens on all network interfaces — set GHOSTBUS_REQUIRE_TOKENS=1 if untrusted agents share the key.\n');
+  }
+});

package/src/mcp-server.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * GhostBus MCP server (stdio) — zero dependencies.
+ * Any MCP client (Claude, Cursor, Antigravity, custom agents) connects here and
+ * every connected client shares the SAME workspace store, so agents actually
+ * meet each other instead of each holding a private copy.
+ *
+ *   node src/mcp-server.mjs [--store ./ghostbus-data.json] [--name "My Workspace"]
+ *
+ * Env: GHOSTBUS_STORE (file path; default ./ghostbus-data.json),
+ *      GHOSTBUS_WORKSPACE_NAME.
+ * Use ":memory:" as the store for an ephemeral workspace.
+ */
+import readline from 'node:readline';
+import { createBus, MemoryStore, FileStore, GHOSTBUS_VERSION } from './core.mjs';
+import { TOOLS, callTool } from './tools.mjs';
+
+const argv = process.argv.slice(2);
+const argVal = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : null; };
+const storePath = argVal('--store') || process.env.GHOSTBUS_STORE || './ghostbus-data.json';
+const wsName = argVal('--name') || process.env.GHOSTBUS_WORKSPACE_NAME || 'GhostBus Workspace';
+
+const store = storePath === ':memory:' ? new MemoryStore() : new FileStore(storePath);
+const bus = await createBus(store, { name: wsName }, { requireTokens: process.env.GHOSTBUS_REQUIRE_TOKENS === '1' });
+
+const send = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+const result = (id, value) => send({ jsonrpc: '2.0', id, result: value });
+const error = (id, code, message) => send({ jsonrpc: '2.0', id, error: { code, message } });
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  if (method === 'initialize') {
+    return result(id, {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: 'ghostbus', version: GHOSTBUS_VERSION },
+    });
+  }
+  if (method === 'notifications/initialized' || method === 'notifications/cancelled') return; // no id reply
+  if (method === 'ping') return result(id, {});
+  if (method === 'tools/list') return result(id, { tools: TOOLS });
+  if (method === 'tools/call') {
+    try {
+      const out = await callTool(bus, params.name, params.arguments || {});
+      const text = typeof out === 'string' ? out : JSON.stringify(out, null, 2);
+      return result(id, { content: [{ type: 'text', text }] });
+    } catch (e) {
+      return result(id, { content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true });
+    }
+  }
+  if (id !== undefined) return error(id, -32601, `method not found: ${method}`);
+}
+
+const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+rl.on('line', async (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  await handle(msg);
+});
+process.stderr.write(`ghostbus mcp-server v${GHOSTBUS_VERSION} · store=${storePath} · workspace="${wsName}"\n`);

package/src/tools.mjs

@@ -0,0 +1,71 @@
+/**
+ * GhostBus MCP tool definitions — shared by the stdio server and the HTTP /mcp endpoint.
+ * Every tool takes `agent` (the caller's registered name) where it acts on someone's behalf,
+ * so the provenance log always names a real participant.
+ */
+export const TOOLS = [
+  { name: 'bus_status', description: 'Workspace status: agents, message/task/file counts, version.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'bus_register', description: 'Register (or rejoin) this agent on the bus with a role and capabilities. First registration returns a per-agent token ONCE — store it; on a token-enforced bus it must be passed as `token` on later calls.', inputSchema: { type: 'object', required: ['agent'], properties: { agent: { type: 'string' }, role: { type: 'string' }, capabilities: { type: 'array', items: { type: 'string' } }, token: { type: 'string' } } } },
+  { name: 'bus_rotate_token', description: 'Rotate this agent\'s token (requires the current token on an enforced bus). The old token stops working; the new one is shown once.', inputSchema: { type: 'object', required: ['agent'], properties: { agent: { type: 'string' }, token: { type: 'string' } } } },
+  { name: 'bus_heartbeat', description: 'Heartbeat: mark this agent present and get the live agent list with online status.', inputSchema: { type: 'object', required: ['agent'], properties: { agent: { type: 'string' }, token: { type: 'string' } } } },
+  { name: 'bus_search', description: 'Search messages, tasks, and shared files by text.', inputSchema: { type: 'object', required: ['query'], properties: { query: { type: 'string' }, limit: { type: 'number', default: 20 } } } },
+  { name: 'bus_channels', description: 'List message channels with message counts.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'bus_agents', description: 'List registered agents with roles, capabilities, and last-seen times.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'bus_send', description: 'Send a message to one agent (to = its name) or broadcast (to = "*"). Set threadId to reply in a thread.', inputSchema: { type: 'object', required: ['agent', 'body'], properties: { agent: { type: 'string' }, to: { type: 'string', default: '*' }, body: { type: 'string' }, channel: { type: 'string', default: 'general' }, threadId: { type: 'number' } } } },
+  { name: 'bus_inbox', description: 'Read messages visible to this agent (direct, broadcast, and its own). Marks them read unless markRead=false.', inputSchema: { type: 'object', required: ['agent'], properties: { agent: { type: 'string' }, unreadOnly: { type: 'boolean', default: false }, limit: { type: 'number', default: 50 }, markRead: { type: 'boolean', default: true } } } },
+  { name: 'bus_thread', description: 'Read a message thread (root message + its replies).', inputSchema: { type: 'object', required: ['id'], properties: { id: { type: 'number' } } } },
+  { name: 'bus_create_task', description: 'Create a handoff task. Optionally assign it, mark urgent, or gate it behind human/agent approval (needsApproval).', inputSchema: { type: 'object', required: ['agent', 'title'], properties: { agent: { type: 'string' }, title: { type: 'string' }, body: { type: 'string' }, assignee: { type: 'string' }, priority: { type: 'string', enum: ['normal', 'urgent'] }, needsApproval: { type: 'boolean', default: false }, blockedBy: { type: 'array', items: { type: 'number' } } } } },
+  { name: 'bus_list_tasks', description: 'List tasks, optionally filtered by status or assignee/claimer.', inputSchema: { type: 'object', properties: { status: { type: 'string' }, assignee: { type: 'string' } } } },
+  { name: 'bus_approve_task', description: 'Approve a task that is waiting in needs-approval, releasing it to the queue.', inputSchema: { type: 'object', required: ['agent', 'id'], properties: { agent: { type: 'string' }, id: { type: 'number' } } } },
+  { name: 'bus_claim_task', description: 'Claim a queued task exclusively (15-minute lease). Fails if another agent holds it.', inputSchema: { type: 'object', required: ['agent', 'id'], properties: { agent: { type: 'string' }, id: { type: 'number' } } } },
+  { name: 'bus_complete_task', description: 'Complete a task you claimed, with a result summary for the sender.', inputSchema: { type: 'object', required: ['agent', 'id'], properties: { agent: { type: 'string' }, id: { type: 'number' }, result: { type: 'string' } } } },
+  { name: 'bus_cancel_task', description: 'Cancel an open task.', inputSchema: { type: 'object', required: ['agent', 'id'], properties: { agent: { type: 'string' }, id: { type: 'number' } } } },
+  { name: 'workspace_put_file', description: 'Write a shared workspace file (capsule, note, deliverable). Path may not contain "..".', inputSchema: { type: 'object', required: ['agent', 'path', 'text'], properties: { agent: { type: 'string' }, path: { type: 'string' }, text: { type: 'string' } } } },
+  { name: 'workspace_get_file', description: 'Read a shared workspace file.', inputSchema: { type: 'object', required: ['path'], properties: { path: { type: 'string' } } } },
+  { name: 'workspace_list_files', description: 'List shared workspace files with size and last writer.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'workspace_put_context', description: 'Publish the shared context object (project state every agent reads first).', inputSchema: { type: 'object', required: ['agent', 'context'], properties: { agent: { type: 'string' }, context: { type: 'object' } } } },
+  { name: 'workspace_get_context', description: 'Read the shared context object.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'workspace_board', description: 'Render the shared board: agents, open tasks, files, recent activity.', inputSchema: { type: 'object', properties: {} } },
+  { name: 'bus_comment_task', description: 'Comment on a task (discussion lives on the task, next to its history).', inputSchema: { type: 'object', required: ['agent', 'id', 'body'], properties: { agent: { type: 'string' }, id: { type: 'number' }, body: { type: 'string' }, token: { type: 'string' } } } },
+  { name: 'workspace_delete_file', description: 'Delete a shared workspace file.', inputSchema: { type: 'object', required: ['agent', 'path'], properties: { agent: { type: 'string' }, path: { type: 'string' }, token: { type: 'string' } } } },
+  { name: 'bus_sync', description: 'Catch-up sync: all provenance events after a sequence number (an agent that was offline replays exactly what it missed). Returns headSeq to store as the next cursor.', inputSchema: { type: 'object', properties: { sinceSeq: { type: 'number', default: 0 }, limit: { type: 'number', default: 500 } } } },
+  { name: 'workspace_get_capsule', description: 'Read a project capsule (structured shared memory: State / Decisions (locked) / Next / Session log). Creates it from the template when create=true.', inputSchema: { type: 'object', required: ['slug'], properties: { slug: { type: 'string' }, create: { type: 'boolean', default: false }, title: { type: 'string' }, agent: { type: 'string' }, token: { type: 'string' } } } },
+  { name: 'workspace_update_capsule', description: 'Update one capsule section (State, Decisions (locked), Next) or append a Session log entry. Other sections are preserved.', inputSchema: { type: 'object', required: ['agent', 'slug', 'section', 'text'], properties: { agent: { type: 'string' }, slug: { type: 'string' }, section: { type: 'string', enum: ['State', 'Decisions (locked)', 'Next', 'Session log'] }, text: { type: 'string' }, token: { type: 'string' } } } },
+  { name: 'workspace_file_history', description: 'Version history of a shared file (current version + up to 10 previous).', inputSchema: { type: 'object', required: ['path'], properties: { path: { type: 'string' } } } },
+  { name: 'bus_events', description: 'Read the provenance event log (who did what, when).', inputSchema: { type: 'object', properties: { limit: { type: 'number', default: 50 } } } },
+];
+
+export async function callTool(bus, name, args = {}) {
+  switch (name) {
+    case 'bus_status': return bus.status();
+    case 'bus_register': return bus.registerAgent({ name: args.agent, role: args.role, capabilities: args.capabilities, token: args.token ?? null });
+    case 'bus_agents': return { agents: await bus.listAgents() };
+    case 'bus_send': return bus.sendMessage({ from: args.agent, to: args.to ?? '*', body: args.body, channel: args.channel ?? 'general', threadId: args.threadId ?? null, token: args.token ?? null });
+    case 'bus_inbox': return { messages: await bus.inbox(args.agent, { unreadOnly: !!args.unreadOnly, limit: args.limit ?? 50, markRead: args.markRead !== false, token: args.token ?? null }) };
+    case 'bus_thread': return { messages: await bus.thread(args.id) };
+    case 'bus_create_task': return bus.createTask({ from: args.agent, title: args.title, body: args.body ?? '', assignee: args.assignee ?? null, priority: args.priority ?? 'normal', needsApproval: !!args.needsApproval, blockedBy: args.blockedBy ?? [], token: args.token ?? null });
+    case 'bus_list_tasks': return { tasks: await bus.listTasks({ status: args.status ?? null, assignee: args.assignee ?? null }) };
+    case 'bus_approve_task': return bus.approveTask(args.id, { by: args.agent, token: args.token ?? null });
+    case 'bus_claim_task': return bus.claimTask(args.id, { by: args.agent, token: args.token ?? null });
+    case 'bus_complete_task': return bus.completeTask(args.id, { by: args.agent, result: args.result ?? '', token: args.token ?? null });
+    case 'bus_cancel_task': return bus.cancelTask(args.id, { by: args.agent, token: args.token ?? null });
+    case 'workspace_put_file': return bus.putFile({ by: args.agent, path: args.path, text: args.text, token: args.token ?? null });
+    case 'workspace_get_file': return bus.getFile(args.path);
+    case 'workspace_list_files': return { files: await bus.listFiles() };
+    case 'workspace_put_context': return bus.putContext({ by: args.agent, context: args.context, token: args.token ?? null });
+    case 'workspace_get_context': return bus.getContext();
+    case 'workspace_board': return { board: await bus.board() };
+    case 'bus_events': return { events: await bus.events({ limit: args.limit ?? 50 }) };
+    case 'bus_rotate_token': return bus.rotateAgentToken({ name: args.agent, token: args.token ?? null });
+    case 'bus_heartbeat': return bus.heartbeat({ name: args.agent, token: args.token ?? null });
+    case 'bus_search': return bus.search(args.query, { limit: args.limit ?? 20 });
+    case 'bus_channels': return { channels: await bus.listChannels() };
+    case 'bus_comment_task': return bus.addTaskComment(args.id, { by: args.agent, body: args.body, token: args.token ?? null });
+    case 'workspace_delete_file': return bus.deleteFile({ by: args.agent, path: args.path, token: args.token ?? null });
+    case 'bus_sync': return bus.sync({ sinceSeq: args.sinceSeq ?? 0, limit: args.limit ?? 500 });
+    case 'workspace_get_capsule': return bus.getCapsule(args.slug, { create: !!args.create, title: args.title ?? '', by: args.agent ?? null, token: args.token ?? null });
+    case 'workspace_update_capsule': return bus.updateCapsule(args.slug, { by: args.agent, section: args.section, text: args.text, token: args.token ?? null });
+    case 'workspace_file_history': return bus.fileHistory(args.path);
+    default: throw Object.assign(new Error(`unknown tool: ${name}`), { code: 'UNKNOWN_TOOL' });
+  }
+}