agent-comm-hub 0.7.1 → 0.8.0

package/lib/index.js

@@ -422,6 +422,7 @@ import { randomUUID } from "node:crypto";
 var KINDS = ["chat", "task", "notice", "ack"];
 var PEER_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
 var BROADCAST = "all";
+var TERMINAL_TASK_STATUSES = ["rejected", "done", "failed"];
 function encodeContent(payload) {
   return JSON.stringify(payload);
 }
@@ -437,6 +438,7 @@ function decodeContent(kind, content) {
 
 // src/hub.ts
 var MAX_PROFILES = 512;
+var MAX_TASKS = 1024;
 var AgentHub = class {
   constructor(options) {
     this.options = options;
@@ -455,6 +457,8 @@ var AgentHub = class {
   profiles = /* @__PURE__ */ new Map();
   /** Named channels (group channel), keyed by group id. */
   groups = /* @__PURE__ */ new Map();
+  /** Task ledger: task message id → record (status + ack timeline). */
+  taskLedger = /* @__PURE__ */ new Map();
   gcTimer;
   /** Stop the idle GC (call when the hub shuts down). */
   dispose() {
@@ -625,15 +629,92 @@ var AgentHub = class {
   send(from, to, kind, content) {
     return this.route(from, to, kind, content);
   }
-  /** Send a structured task message to `to` (or {@link BROADCAST}). */
+  /** Send a structured task message to `to` (or {@link BROADCAST}). Records
+   * a ledger entry so the sender can later query status / wait for acks. */
   sendTask(from, to, task) {
-    return this.route(from, to, "task", JSON.stringify(task));
+    const message = this.route(from, to, "task", JSON.stringify(task));
+    this.recordTask(message, task);
+    return message;
   }
-  /** Send an acknowledgement back to the sender of `ref`. */
+  /** Send an acknowledgement back to the sender of `ref`. Updates the task
+   * ledger when `ref` is a known task; chat/notice refs still route. */
   sendAck(from, ref, ack) {
-    const original = this.historyRing.findLast((message) => message.id === ref);
+    const original = this.historyRing.findLast((message2) => message2.id === ref);
     if (!original) throw new Error(`cannot ack unknown message: ${ref}`);
-    return this.route(from, original.from, "ack", JSON.stringify(ack), ref);
+    const message = this.route(from, original.from, "ack", JSON.stringify(ack), ref);
+    this.applyAckToLedger(message, from, ref, ack);
+    return message;
+  }
+  /** Create or refresh the ledger row for a newly sent task. */
+  recordTask(message, task) {
+    const now = message.ts;
+    this.taskLedger.set(message.id, {
+      id: message.id,
+      from: message.from,
+      to: message.to,
+      prompt: task.prompt,
+      ...task.context !== void 0 ? { context: task.context } : {},
+      ...task.deliverable !== void 0 ? { deliverable: task.deliverable } : {},
+      status: "pending",
+      acks: [],
+      createdAt: now,
+      updatedAt: now
+    });
+    this.evictOverflowTasks();
+  }
+  /** Fold an ack into the task's timeline and status. Unknown refs are a
+   * no-op (chat/notice can be acked for routing without a ledger row). */
+  applyAckToLedger(message, from, ref, ack) {
+    const record = this.taskLedger.get(ref);
+    if (record === void 0) return;
+    record.acks.push({
+      from,
+      status: ack.status,
+      ...ack.note !== void 0 ? { note: ack.note } : {},
+      ts: message.ts,
+      messageId: message.id
+    });
+    record.status = ack.status;
+    record.updatedAt = message.ts;
+  }
+  /** Keep the ledger bounded: drop oldest terminal tasks first. */
+  evictOverflowTasks() {
+    if (this.taskLedger.size <= MAX_TASKS) return;
+    const evictable = [...this.taskLedger.values()].filter((t) => TERMINAL_TASK_STATUSES.includes(t.status)).sort((a, b) => a.updatedAt - b.updatedAt);
+    let overflow = this.taskLedger.size - MAX_TASKS;
+    for (const record of evictable) {
+      if (overflow <= 0) break;
+      this.taskLedger.delete(record.id);
+      overflow--;
+    }
+  }
+  /** One task by message id (the ack `ref`). */
+  taskOf(ref) {
+    const record = this.taskLedger.get(ref);
+    return record === void 0 ? void 0 : { ...record, acks: record.acks.map((a) => ({ ...a })) };
+  }
+  /**
+   * Tasks involving `peer`. `role`:
+   * - `sent` — tasks this peer delegated (`from`)
+   * - `received` — tasks addressed to this peer (or broadcast)
+   * - `all` (default) — either side
+   * Optional `status` filter matches the ledger's current status.
+   */
+  listTasks(peerId, options) {
+    const role = options?.role ?? "all";
+    const limit = Math.max(1, options?.limit ?? 50);
+    const out = [];
+    for (const record of this.taskLedger.values()) {
+      const isSent = record.from === peerId;
+      const isReceived = record.to === peerId || record.to === BROADCAST;
+      if (role === "sent" && !isSent) continue;
+      if (role === "received" && !isReceived) continue;
+      if (role === "all" && !isSent && !isReceived) continue;
+      if (options?.status !== void 0 && record.status !== options.status) continue;
+      out.push({ ...record, acks: record.acks.map((a) => ({ ...a })) });
+    }
+    out.sort((a, b) => b.updatedAt - a.updatedAt);
+    return out.slice(0, limit);
   }
   /** Recent messages involving `peer` (inbound and outbound, plus group
    * channels the peer belongs to), newest first. */
@@ -856,11 +937,29 @@ var AgentHub = class {
    * Long-poll for the next message addressed to `peer`: resolves immediately
    * when a matching one is queued, otherwise waits up to `timeoutMs` (capped
    * by `waitTimeoutMs`) or until `signal` aborts. `from` narrows to one sender.
+   * `ref` narrows to the ack of a specific task message id.
+   *
+   * Takes ONLY the first matching queued message. Calling poll() here would
+   * drain the whole mailbox and discard every message after the first —
+   * a multi-message burst (or a reconnect with a full queue) would silently
+   * lose messages that never reach wait/poll again.
    */
-  wait(peerId, timeoutMs, from, signal) {
+  wait(peerId, timeoutMs, from, signal, ref) {
     const startedAt = Date.now();
-    const queued = this.poll(peerId, from)[0];
-    if (queued) return Promise.resolve({ type: "message", message: queued });
+    const matches = (message) => {
+      if (from !== void 0 && message.from !== from) return false;
+      if (ref !== void 0 && !(message.kind === "ack" && message.ref === ref)) return false;
+      return true;
+    };
+    const queue = this.queues.get(peerId);
+    if (queue !== void 0 && queue.length > 0) {
+      const index = queue.findIndex(matches);
+      if (index >= 0) {
+        const [queued] = queue.splice(index, 1);
+        this.options.onMailboxesChanged?.();
+        return Promise.resolve({ type: "message", message: queued });
+      }
+    }
     const budget = Math.max(1, Math.min(Math.floor(timeoutMs), this.options.waitTimeoutMs));
     return new Promise((resolve) => {
       let settled = false;
@@ -889,7 +988,13 @@ var AgentHub = class {
       }
       signal?.addEventListener("abort", onAbort, { once: true });
       const list = this.waiters.get(peerId) ?? [];
-      list.push({ resolve: settle, timer, onAbort, ...from !== void 0 ? { from } : {} });
+      list.push({
+        resolve: settle,
+        timer,
+        onAbort,
+        ...from !== void 0 ? { from } : {},
+        ...ref !== void 0 ? { ref } : {}
+      });
       this.waiters.set(peerId, list);
     });
   }
@@ -919,7 +1024,11 @@ var AgentHub = class {
   /** Queue or hand off a message; wake the first matching waiter for its target. */
   deliver(target, message) {
     const list = this.waiters.get(target) ?? [];
-    const index = list.findIndex((waiter) => waiter.from === void 0 || waiter.from === message.from);
+    const index = list.findIndex((waiter) => {
+      if (waiter.from !== void 0 && waiter.from !== message.from) return false;
+      if (waiter.ref !== void 0 && !(message.kind === "ack" && message.ref === waiter.ref)) return false;
+      return true;
+    });
     if (index >= 0) {
       const [waiter] = list.splice(index, 1);
       this.waiters.set(target, list);
@@ -1362,7 +1471,7 @@ function hubTools(hub, registry, options) {
     },
     {
       name: "bridge_task",
-      description: "Delegate a structured task to another agent. The receiving agent decides whether to accept; expect an ack (accepted/rejected/done/failed) via bridge_wait / bridge_poll.",
+      description: "Delegate a structured task to another agent. The receiving agent decides whether to accept; expect an ack (accepted/rejected/done/failed) via bridge_wait / bridge_poll. Track progress with bridge_task_status(ref) or bridge_tasks; wait specifically for the ack with bridge_wait({ ref }).",
       inputSchema: schema(
         {
           to: str('Target peerId, or "all" to broadcast.'),
@@ -1380,7 +1489,7 @@ function hubTools(hub, registry, options) {
     },
     {
       name: "bridge_ack",
-      description: "Acknowledge a message received from another agent (usually a delegated task): accepted | rejected | done | failed. The ack is routed back to the original sender of `ref`.",
+      description: "Acknowledge a message received from another agent (usually a delegated task): accepted | rejected | done | failed. The ack is routed back to the original sender of `ref` and updates the hub task ledger (see bridge_task_status / bridge_tasks).",
       inputSchema: schema(
         {
           ref: str("The id of the message being acknowledged."),
@@ -1398,14 +1507,61 @@ function hubTools(hub, registry, options) {
         return receipt(hub.sendAck(peer, String(args.ref), { status, ...args.note !== void 0 ? { note: String(args.note) } : {} }));
       })
     },
+    {
+      name: "bridge_tasks",
+      description: "List delegated tasks involving you, newest first. role=sent = tasks you assigned; role=received = tasks assigned to you (or broadcast); status filters the ledger state (pending/accepted/rejected/done/failed). Each row carries the full ack timeline.",
+      inputSchema: schema({
+        role: { type: "string", enum: ["sent", "received", "all"], description: "Which side of the task to list (default all)." },
+        status: { type: "string", enum: ["pending", "accepted", "rejected", "done", "failed"], description: "Only tasks whose current ledger status matches." },
+        limit: int("How many tasks to return (default 50).")
+      }),
+      handler: wrap(true, async (args, peer) => {
+        const role = args.role === void 0 ? void 0 : String(args.role);
+        if (role !== void 0 && role !== "sent" && role !== "received" && role !== "all") {
+          throw new Error(`invalid role: ${role} (expected sent | received | all)`);
+        }
+        const status = args.status === void 0 ? void 0 : String(args.status);
+        const validStatus = ["pending", "accepted", "rejected", "done", "failed"];
+        if (status !== void 0 && !validStatus.includes(status)) {
+          throw new Error(`invalid status: ${status} (expected ${validStatus.join(" | ")})`);
+        }
+        const tasks = hub.listTasks(peer, {
+          ...role !== void 0 ? { role } : {},
+          ...status !== void 0 ? { status } : {},
+          ...args.limit !== void 0 ? { limit: Number(args.limit) } : {}
+        });
+        return { tasks };
+      })
+    },
+    {
+      name: "bridge_task_status",
+      description: "Status of one delegated task: current ledger state (pending \u2192 accepted \u2192 done/failed, or rejected), the original prompt/context/deliverable, and every ack event (who, status, note, when). Use the task message id (the same id you pass as bridge_ack ref).",
+      inputSchema: schema({ ref: str("Task message id (the id returned by bridge_task, also used as ack ref).") }, ["ref"]),
+      handler: wrap(true, async (args, peer, sessionId) => {
+        const ref = String(args.ref);
+        const task = hub.taskOf(ref);
+        if (task === void 0) throw new Error(`unknown task: ${ref}`);
+        if (task.from !== peer && task.to !== peer && task.to !== BROADCAST) {
+          requireManager(peer, `reading task '${ref}'`, sessionId);
+        }
+        return { task };
+      })
+    },
     {
       name: "bridge_wait",
-      description: "Wait (long-poll) for the next message addressed to you. Resolves immediately when one is queued; otherwise blocks until one arrives or the timeout fires. `from` narrows to one sender. Loop this tool to hold a real-time conversation.",
+      description: "Wait (long-poll) for the next message addressed to you. Resolves immediately when one is queued; otherwise blocks until one arrives or the timeout fires. `from` narrows to one sender. `ref` waits specifically for the ack of that task id. Loop this tool to hold a real-time conversation.",
       inputSchema: schema({
         from: optStr("Only wait for messages from this peerId."),
+        ref: optStr("Only wait for the ack of this task message id (bridge_task id)."),
         timeoutMs: int(`Max wait in milliseconds (default ${DEFAULT_WAIT_MS}, ceiling is server waitTimeoutMs).`)
       }),
-      handler: wrap(true, async (args, peer) => presentWait(await hub.wait(peer, args.timeoutMs === void 0 ? options.defaultWaitMs ?? DEFAULT_WAIT_MS : Number(args.timeoutMs), args.from === void 0 ? void 0 : String(args.from))))
+      handler: wrap(true, async (args, peer) => presentWait(await hub.wait(
+        peer,
+        args.timeoutMs === void 0 ? options.defaultWaitMs ?? DEFAULT_WAIT_MS : Number(args.timeoutMs),
+        args.from === void 0 ? void 0 : String(args.from),
+        void 0,
+        args.ref === void 0 ? void 0 : String(args.ref)
+      )))
     },
     {
       name: "bridge_poll",
@@ -1428,7 +1584,11 @@ function hubTools(hub, registry, options) {
     {
       name: "bridge_history",
       description: 'Recent messages involving you (newest first). Use to refresh context after a reconnect. Reading ANOTHER peer\'s conversation \u2014 or `peer: "all"` for the unfiltered tail \u2014 requires manager rights (hub managerPeers).',
-      inputSchema: schema({ peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself. Other peers / "all" require manager rights.'), limit: int("How many messages to return (default 20).") }),
+      inputSchema: schema({
+        peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself. Other peers / "all" require manager rights.'),
+        channel: optStr("Read a group channel history instead of a peer conversation (you must be a member, or a manager)."),
+        limit: int("How many messages to return (default 20).")
+      }),
       handler: wrap(true, async (args, peer, sessionId) => {
         const limit = Math.min(args.limit === void 0 ? 20 : Number(args.limit), 1e3);
         const target = args.peer === void 0 ? peer : String(args.peer);
@@ -1736,6 +1896,7 @@ function adminPage() {
 var SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
 var LATEST_VERSION = SUPPORTED_VERSIONS[0];
 var MAX_BODY_BYTES = 1048576;
+var HEARTBEAT_MS = 2e4;
 var SessionRegistry = class {
   sessions = /* @__PURE__ */ new Set();
   /** sessionId → peerId claimed via `bridge_register`. */
@@ -1881,7 +2042,7 @@ var SessionRegistry = class {
 var McpStreamableHttpServer = class {
   constructor(tools, info, registry, log = () => {
   }, onInitialize = () => {
-  }, authenticate, adminApi) {
+  }, authenticate, adminApi, heartbeatMs) {
     this.tools = tools;
     this.info = info;
     this.registry = registry;
@@ -1889,10 +2050,21 @@ var McpStreamableHttpServer = class {
     this.onInitialize = onInitialize;
     this.authenticate = authenticate;
     this.adminApi = adminApi;
+    this.heartbeatMs = heartbeatMs;
   }
   sseStreams = /* @__PURE__ */ new Map();
+  heartbeatTimer;
   /** Attach request handling for `path` (e.g. `/mcp`) to an http server. */
   attach(server, path2) {
+    this.heartbeatTimer = setInterval(() => {
+      if (this.sseStreams.size === 0) return;
+      this.notifyAll("notifications/message", {
+        level: "debug",
+        logger: "bridge",
+        data: { event: "heartbeat", ts: Date.now() }
+      });
+    }, this.heartbeatMs ?? HEARTBEAT_MS);
+    this.heartbeatTimer.unref?.();
     server.on("request", (req, res) => {
       const url = new URL(req.url ?? "/", "http://localhost");
       if (url.pathname === ADMIN_PATH && req.method === "GET") {
@@ -1900,6 +2072,11 @@ var McpStreamableHttpServer = class {
         res.end(adminPage());
         return;
       }
+      if (url.pathname === "/healthz") {
+        res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", ...corsHeaders() });
+        res.end(JSON.stringify({ ok: true, ts: Date.now() }));
+        return;
+      }
       if (url.pathname.startsWith(ADMIN_API_PATH) && this.adminApi !== void 0) {
         void this.handleAdminApi(req, res, url);
         return;
@@ -1925,6 +2102,7 @@ var McpStreamableHttpServer = class {
   }
   /** Close all open SSE streams (called on server shutdown). */
   close() {
+    if (this.heartbeatTimer !== void 0) clearInterval(this.heartbeatTimer);
     for (const stream of this.sseStreams.values()) stream.end();
     this.sseStreams.clear();
   }
@@ -2340,7 +2518,7 @@ var SQLiteStateStore = class {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.7.1";
+var SERVER_VERSION = "0.8.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -2358,9 +2536,10 @@ var DEFAULT_CONFIG = {
   connectedWindowMs: 3e4,
   peerIdleTimeoutMs: 6e5,
   // The companion desktop app (and `agent-comm-hub status` probe) registers
-  // as `agent-hub-cli`; it is the natural roster manager. Agents themselves
-  // are NOT managers — they keep chatting, a GUI manages.
-  managerPeers: ["agent-hub-cli"]
+  // as `agent-hub-cli`; the web admin console registers as `hub-admin`.
+  // Both are roster managers. Agents themselves are NOT managers — they
+  // keep chatting, a GUI manages.
+  managerPeers: ["agent-hub-cli", "hub-admin"]
 };
 function authTokensAdmin(file, reloadAuth) {
   if (file === void 0) return void 0;
@@ -2610,7 +2789,8 @@ function startHub(config = {}, log = console) {
       }
     },
     auth,
-    authTokensAdmin(resolved.authTokens, authReload)
+    authTokensAdmin(resolved.authTokens, authReload),
+    resolved.heartbeatMs
   );
   const server = createServer();
   mcp.attach(server, resolved.path);
@@ -2660,6 +2840,7 @@ export {
   SERVER_VERSION,
   SQLiteStateStore,
   SessionRegistry,
+  TERMINAL_TASK_STATUSES,
   addToken,
   autoRegisterPeer,
   decodeContent,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-comm-hub",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Generic multi-peer MCP hub: any MCP-capable agent (MiniMax Code, Claude Code, opencode, Codex, Gemini CLI, DSH, ...) connects to one local streamable-http endpoint and they chat, delegate tasks, and acknowledge in real time",
   "keywords": [
     "mcp",
@@ -38,7 +38,7 @@
     "build": "esbuild src/cli.ts --bundle --platform=node --format=esm --outfile=lib/cli.js && esbuild src/index.ts --bundle --platform=node --format=esm --outfile=lib/index.js && esbuild src/setup.ts --bundle --platform=node --format=esm --outfile=lib/setup.js",
     "build:test": "esbuild test/entry.ts --bundle --platform=node --format=esm --outfile=test/entry.mjs && esbuild test/setup-entry.ts --bundle --platform=node --format=esm --outfile=test/setup-entry.mjs && esbuild test/ops-entry.ts --bundle --platform=node --format=esm --outfile=test/ops-entry.mjs && esbuild test/herdr-entry.ts --bundle --platform=node --format=esm --outfile=test/herdr-entry.mjs && esbuild test/discover-entry.ts --bundle --platform=node --format=esm --outfile=test/discover-entry.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "pnpm run build:test && node test/smoke.mjs && node test/setup.mjs && node test/ops.mjs && node test/herdr.mjs && node test/discover.mjs",
+    "test": "pnpm run build:test && pnpm run build && node test/smoke.mjs && node test/setup.mjs && node test/ops.mjs && node test/herdr.mjs && node test/discover.mjs && node test/e2e.mjs",
     "pack": "pnpm run build && pnpm pack"
   }
 }