agent-comm-hub 0.7.0 → 0.8.0

package/lib/cli.js

@@ -424,6 +424,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 decodeContent(kind, content) {
   if (kind !== "task" && kind !== "ack") return content;
   try {
@@ -436,6 +437,7 @@ function decodeContent(kind, content) {
 
 // src/hub.ts
 var MAX_PROFILES = 512;
+var MAX_TASKS = 1024;
 var AgentHub = class {
   constructor(options) {
     this.options = options;
@@ -454,6 +456,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() {
@@ -624,15 +628,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. */
@@ -855,11 +936,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;
@@ -888,7 +987,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);
     });
   }
@@ -918,7 +1023,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);
@@ -1356,7 +1465,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.'),
@@ -1374,7 +1483,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."),
@@ -1392,14 +1501,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",
@@ -1422,7 +1578,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);
@@ -1730,6 +1890,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`. */
@@ -1875,7 +2036,7 @@ var SessionRegistry = class {
 var McpStreamableHttpServer = class {
   constructor(tools, info, registry, log2 = () => {
   }, onInitialize = () => {
-  }, authenticate, adminApi) {
+  }, authenticate, adminApi, heartbeatMs) {
     this.tools = tools;
     this.info = info;
     this.registry = registry;
@@ -1883,10 +2044,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") {
@@ -1894,6 +2066,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;
@@ -1919,6 +2096,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();
   }
@@ -2239,7 +2417,7 @@ var SQLiteStateStore = class {
         id TEXT PRIMARY KEY, name TEXT, members TEXT NOT NULL, created_by TEXT NOT NULL, created_at INTEGER NOT NULL
       );
     `);
-    log2.warn(`sqlite state open: ${file}`);
+    log2.info(`sqlite state open: ${file}`);
   }
   db;
   buffer = [];
@@ -2334,7 +2512,7 @@ var SQLiteStateStore = class {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.7.0";
+var SERVER_VERSION = "0.8.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -2352,9 +2530,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;
@@ -2604,7 +2783,8 @@ function startHub(config = {}, log2 = console) {
       }
     },
     auth,
-    authTokensAdmin(resolved.authTokens, authReload)
+    authTokensAdmin(resolved.authTokens, authReload),
+    resolved.heartbeatMs
   );
   const server = createServer();
   mcp.attach(server, resolved.path);
@@ -3131,6 +3311,7 @@ function runUpdate() {
     const out = execFileSync2(process.execPath, ["--input-type=module", "-e", script], { encoding: "utf8", windowsHide: true });
     messages.push(out.trim());
     messages.push("restart the hub (agent-comm-hub) to pick up the new version");
+    messages.push("refresh installed agent skills: agent-comm-hub setup  (copies the packaged SKILL.md into each agent; npm update alone does not rewrite skill dirs)");
     return { ok: true, messages };
   } catch (error) {
     return { ok: false, messages: [`update failed: ${error.message}`] };
@@ -3306,7 +3487,7 @@ var DEFAULT_DB = join4(homedir4(), ".agent-comm-hub", "state.db");
 var DEFAULT_AUTH_FILE = join4(homedir4(), ".agent-comm-hub", "tokens.json");
 function parseArgs(argv) {
   const args = {};
-  const numeric = /* @__PURE__ */ new Set(["--port", "--max-queue", "--history-limit", "--wait-timeout-ms", "--default-wait-ms", "--connected-window-ms", "--peer-idle-timeout-ms", "--herdr-timeout-ms"]);
+  const numeric = /* @__PURE__ */ new Set(["--port", "--max-queue", "--history-limit", "--wait-timeout-ms", "--default-wait-ms", "--connected-window-ms", "--peer-idle-timeout-ms", "--herdr-timeout-ms", "--heartbeat-ms"]);
   const string = /* @__PURE__ */ new Set(["--host", "--path", "--url", "--server-name", "--agent", "--herdr-bin", "--manager-peers", "--state-file", "--auth-tokens", "--db", "--file", "--role", "--owner", "--token"]);
   for (let i = 0; i < argv.length; i++) {
     const flag = argv[i];
@@ -3364,6 +3545,7 @@ Hub options:
   --path <p>               MCP endpoint path (default /mcp)
   --max-queue <n>          Queued messages per peer before dropping oldest (default 200)
   --history-limit <n>      Retained history messages (default 1000)
+  --heartbeat-ms <n>       SSE heartbeat cadence in ms (default 20000)
   --wait-timeout-ms <n>    Long-poll ceiling for bridge_wait (default 60000)
   --default-wait-ms <n>    bridge_wait default budget (default 30000)
   --connected-window-ms <n>  Peer counts as active within this window (default 30000)
@@ -3593,7 +3775,8 @@ try {
     stateFile: args["--state-file"] === void 0 ? DEFAULT_STATE_FILE : args["--state-file"] === "off" ? void 0 : String(args["--state-file"]),
     authTokens: args["--auth-tokens"] === void 0 ? void 0 : String(args["--auth-tokens"]),
     allowJoin: args["--allow-join"] === true,
-    db: args["--db"] === void 0 ? DEFAULT_DB : args["--db"] === "off" ? void 0 : String(args["--db"])
+    db: args["--db"] === void 0 ? DEFAULT_DB : args["--db"] === "off" ? void 0 : String(args["--db"]),
+    heartbeatMs: args["--heartbeat-ms"]
   }, log);
   const shutdown = () => {
     log.info("agent-comm-hub shutting down");