agent-comm-hub 0.8.0 → 0.9.0

package/lib/index.js

@@ -422,7 +422,40 @@ 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"];
+var MAX_HOP = 5;
+var TERMINAL_TASK_STATUSES = ["rejected", "done", "failed", "timeout"];
+function ackToTaskStatus(ack) {
+  return ack;
+}
+function nextTaskStatus(current, ack) {
+  if (TERMINAL_TASK_STATUSES.includes(current)) return null;
+  const next = ackToTaskStatus(ack);
+  switch (current) {
+    case "pending":
+      return next;
+    case "accepted":
+      return next;
+    case "working":
+      if (next === "accepted") return "working";
+      return next;
+    default:
+      return null;
+  }
+}
+function aggregateTaskStatus(assignees) {
+  if (assignees.length === 0) return "pending";
+  const statuses = assignees.map((a) => a.status);
+  const active = statuses.filter((s) => s === "pending" || s === "accepted" || s === "working");
+  if (active.length > 0) {
+    if (active.some((s) => s === "working")) return "working";
+    if (active.some((s) => s === "accepted")) return "accepted";
+    return "pending";
+  }
+  if (statuses.every((s) => s === "done")) return "done";
+  if (statuses.some((s) => s === "failed")) return "failed";
+  if (statuses.some((s) => s === "timeout")) return "timeout";
+  return "rejected";
+}
 function encodeContent(payload) {
   return JSON.stringify(payload);
 }
@@ -459,10 +492,14 @@ var AgentHub = class {
   groups = /* @__PURE__ */ new Map();
   /** Task ledger: task message id → record (status + ack timeline). */
   taskLedger = /* @__PURE__ */ new Map();
+  /** SLA timers keyed by task id (cleared when the task turns terminal). */
+  taskTimers = /* @__PURE__ */ new Map();
   gcTimer;
   /** Stop the idle GC (call when the hub shuts down). */
   dispose() {
     if (this.gcTimer !== void 0) clearInterval(this.gcTimer);
+    for (const timer of this.taskTimers.values()) clearTimeout(timer);
+    this.taskTimers.clear();
   }
   gcTick(idleTimeoutMs) {
     const now = Date.now();
@@ -626,29 +663,49 @@ var AgentHub = class {
     return last !== void 0 && Date.now() - last < (this.options.connectedWindowMs ?? 3e4);
   }
   /** Send a chat/notice text message to `to` (or {@link BROADCAST}). */
-  send(from, to, kind, content) {
-    return this.route(from, to, kind, content);
+  send(from, to, kind, content, opts) {
+    return this.route(from, to, kind, content, opts?.ref, opts?.threadId);
   }
-  /** Send a structured task message to `to` (or {@link BROADCAST}). Records
-   * a ledger entry so the sender can later query status / wait for acks. */
+  /** Send a structured task message to `to` (peer, {@link BROADCAST}, or a
+   * group id). Records a ledger entry so the sender can later query status /
+   * wait for acks. */
   sendTask(from, to, task) {
-    const message = this.route(from, to, "task", JSON.stringify(task));
+    const threadId = task.threadId;
+    const message = this.route(from, to, "task", JSON.stringify(task), void 0, threadId);
     this.recordTask(message, task);
     return message;
   }
   /** Send an acknowledgement back to the sender of `ref`. Updates the task
-   * ledger when `ref` is a known task; chat/notice refs still route. */
+   * ledger when `ref` is a known task (looked up in the ledger first, so acks
+   * survive history-ring eviction); chat/notice refs still route via history. */
   sendAck(from, ref, ack) {
-    const original = this.historyRing.findLast((message2) => message2.id === ref);
-    if (!original) throw new Error(`cannot ack unknown message: ${ref}`);
-    const message = this.route(from, original.from, "ack", JSON.stringify(ack), ref);
+    const task = this.taskLedger.get(ref);
+    let target;
+    if (task !== void 0) {
+      target = task.from;
+    } else {
+      const original = this.historyRing.findLast((message2) => message2.id === ref);
+      if (!original) throw new Error(`cannot ack unknown message: ${ref}`);
+      target = original.from;
+    }
+    const message = this.route(from, target, "ack", JSON.stringify(ack), ref);
     this.applyAckToLedger(message, from, ref, ack);
     return message;
   }
+  /** Resolve the peer ids a task is assigned to (broadcast / group fan-out). */
+  resolveAssignees(from, to) {
+    if (to === BROADCAST) return this.peers().filter((peer) => peer !== from);
+    const group = this.groups.get(to);
+    if (group !== void 0) return group.members.filter((member) => member !== from);
+    return [to];
+  }
   /** Create or refresh the ledger row for a newly sent task. */
   recordTask(message, task) {
     const now = message.ts;
-    this.taskLedger.set(message.id, {
+    const assigneeIds = this.resolveAssignees(message.from, message.to);
+    const assignees = assigneeIds.map((peerId) => ({ peerId, status: "pending", acks: [] }));
+    const timeoutMs = typeof task.timeoutMs === "number" && Number.isFinite(task.timeoutMs) && task.timeoutMs > 0 ? Math.floor(task.timeoutMs) : void 0;
+    const record = {
       id: message.id,
       from: message.from,
       to: message.to,
@@ -657,25 +714,105 @@ var AgentHub = class {
       ...task.deliverable !== void 0 ? { deliverable: task.deliverable } : {},
       status: "pending",
       acks: [],
+      assignees,
+      ...timeoutMs !== void 0 ? { timeoutMs, deadlineAt: now + timeoutMs } : {},
+      ...message.threadId !== void 0 ? { threadId: message.threadId } : {},
       createdAt: now,
       updatedAt: now
-    });
+    };
+    this.taskLedger.set(message.id, record);
+    this.scheduleTaskTimeout(record);
     this.evictOverflowTasks();
+    this.options.onTaskChanged?.(this.taskOf(record.id));
+  }
+  /** Arm the SLA timer for a task that supplied `timeoutMs`. */
+  scheduleTaskTimeout(record) {
+    if (record.deadlineAt === void 0) return;
+    const delay = Math.max(0, record.deadlineAt - Date.now());
+    const timer = setTimeout(() => this.fireTaskTimeout(record.id), delay);
+    timer.unref?.();
+    this.taskTimers.set(record.id, timer);
+  }
+  /** Mark a non-terminal task `timeout` and leave a system timeline event. */
+  fireTaskTimeout(taskId) {
+    this.taskTimers.delete(taskId);
+    const record = this.taskLedger.get(taskId);
+    if (record === void 0) return;
+    if (TERMINAL_TASK_STATUSES.includes(record.status)) return;
+    const now = Date.now();
+    const event = {
+      from: record.to,
+      status: "failed",
+      note: `task timed out after ${record.timeoutMs ?? 0}ms without a terminal ack`,
+      ts: now,
+      messageId: `timeout-${record.id}`,
+      applied: true,
+      system: true
+    };
+    record.acks.push(event);
+    for (const assignee of record.assignees) {
+      if (!TERMINAL_TASK_STATUSES.includes(assignee.status)) {
+        assignee.status = "timeout";
+        assignee.acks.push({ ...event });
+      }
+    }
+    record.status = "timeout";
+    record.updatedAt = now;
+    this.clearTaskTimer(taskId);
+    this.options.onTaskChanged?.(this.taskOf(taskId));
   }
-  /** 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). */
+  clearTaskTimer(taskId) {
+    const timer = this.taskTimers.get(taskId);
+    if (timer !== void 0) {
+      clearTimeout(timer);
+      this.taskTimers.delete(taskId);
+    }
+  }
+  /** Note that `target` has taken delivery of a task (waiter handoff / queue). */
+  markTaskDelivered(taskId, target, ts) {
+    const record = this.taskLedger.get(taskId);
+    if (record === void 0) return;
+    const assignee = record.assignees.find((a) => a.peerId === target);
+    if (assignee === void 0 || assignee.deliveredMs !== void 0) return;
+    assignee.deliveredMs = ts;
+    record.updatedAt = ts;
+    this.options.onTaskChanged?.(this.taskOf(taskId));
+  }
+  /**
+   * Fold an ack into the task's timeline and (when legal) its status.
+   * - Unknown refs are a no-op (chat/notice can be acked for routing without a ledger row).
+   * - Terminal tasks keep the event on the timeline with `applied: false`.
+   * - Broadcast / group tasks update the acking assignee first, then re-aggregate.
+   */
   applyAckToLedger(message, from, ref, ack) {
     const record = this.taskLedger.get(ref);
     if (record === void 0) return;
-    record.acks.push({
+    const next = nextTaskStatus(record.status, ack.status);
+    const assignee = record.assignees.find((a) => a.peerId === from);
+    const assigneeNext = assignee === void 0 ? null : nextTaskStatus(assignee.status, ack.status);
+    const applied = record.assignees.length <= 1 ? next !== null : assigneeNext !== null;
+    const event = {
       from,
       status: ack.status,
       ...ack.note !== void 0 ? { note: ack.note } : {},
+      ...typeof ack.progress === "number" && Number.isFinite(ack.progress) ? { progress: Math.max(0, Math.min(100, ack.progress)) } : {},
       ts: message.ts,
-      messageId: message.id
-    });
-    record.status = ack.status;
+      messageId: message.id,
+      applied
+    };
+    record.acks.push(event);
+    if (assignee !== void 0 && assigneeNext !== null) {
+      assignee.status = assigneeNext;
+      assignee.acks.push({ ...event });
+    }
+    if (record.assignees.length <= 1) {
+      if (next !== null) record.status = next;
+    } else {
+      record.status = aggregateTaskStatus(record.assignees);
+    }
     record.updatedAt = message.ts;
+    if (TERMINAL_TASK_STATUSES.includes(record.status)) this.clearTaskTimer(record.id);
+    this.options.onTaskChanged?.(this.taskOf(record.id));
   }
   /** Keep the ledger bounded: drop oldest terminal tasks first. */
   evictOverflowTasks() {
@@ -684,19 +821,25 @@ var AgentHub = class {
     let overflow = this.taskLedger.size - MAX_TASKS;
     for (const record of evictable) {
       if (overflow <= 0) break;
+      this.clearTaskTimer(record.id);
       this.taskLedger.delete(record.id);
       overflow--;
     }
   }
-  /** One task by message id (the ack `ref`). */
+  /** Deep-ish copy of 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 })) };
+    if (record === void 0) return void 0;
+    return {
+      ...record,
+      acks: record.acks.map((a) => ({ ...a })),
+      assignees: record.assignees.map((a) => ({ ...a, acks: a.acks.map((e) => ({ ...e })) }))
+    };
   }
   /**
    * Tasks involving `peer`. `role`:
    * - `sent` — tasks this peer delegated (`from`)
-   * - `received` — tasks addressed to this peer (or broadcast)
+   * - `received` — tasks addressed to this peer, a group they are in, or broadcast
    * - `all` (default) — either side
    * Optional `status` filter matches the ledger's current status.
    */
@@ -705,17 +848,94 @@ var AgentHub = class {
     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 (peerId !== "all") {
+        const isSent = record.from === peerId;
+        const isReceived = record.to === peerId || record.to === BROADCAST || record.assignees.some((a) => a.peerId === peerId) || (this.groups.get(record.to)?.members.includes(peerId) ?? false);
+        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 })) });
+      const copy = this.taskOf(record.id);
+      if (copy !== void 0) out.push(copy);
     }
     out.sort((a, b) => b.updatedAt - a.updatedAt);
     return out.slice(0, limit);
   }
+  /** Snapshot of every task (persistence). */
+  exportTasks() {
+    return [...this.taskLedger.values()].map((record) => this.taskOf(record.id)).filter(Boolean);
+  }
+  /** Restore the task ledger at boot (and re-arm SLA timers). */
+  importTasks(tasks) {
+    if (!Array.isArray(tasks)) return 0;
+    let count = 0;
+    for (const raw of tasks) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const t = raw;
+      if (typeof t.id !== "string" || typeof t.from !== "string" || typeof t.to !== "string" || typeof t.prompt !== "string") continue;
+      if (typeof t.status !== "string" || !TERMINAL_TASK_STATUSES.includes(t.status) && t.status !== "pending" && t.status !== "accepted" && t.status !== "working") continue;
+      const acks = Array.isArray(t.acks) ? t.acks.flatMap((rawAck) => {
+        if (typeof rawAck !== "object" || rawAck === null) return [];
+        const a = rawAck;
+        if (typeof a.from !== "string" || typeof a.status !== "string" || typeof a.ts !== "number" || typeof a.messageId !== "string") return [];
+        return [{
+          from: a.from,
+          status: a.status,
+          ...typeof a.note === "string" ? { note: a.note } : {},
+          ...typeof a.progress === "number" ? { progress: a.progress } : {},
+          ts: a.ts,
+          messageId: a.messageId,
+          applied: a.applied !== false,
+          ...a.system === true ? { system: true } : {}
+        }];
+      }) : [];
+      const assignees = Array.isArray(t.assignees) && t.assignees.length > 0 ? t.assignees.flatMap((rawA) => {
+        if (typeof rawA !== "object" || rawA === null) return [];
+        const a = rawA;
+        if (typeof a.peerId !== "string" || typeof a.status !== "string") return [];
+        return [{
+          peerId: a.peerId,
+          status: a.status,
+          ...typeof a.deliveredMs === "number" ? { deliveredMs: a.deliveredMs } : {},
+          acks: Array.isArray(a.acks) ? a.acks.flatMap((rawE) => {
+            if (typeof rawE !== "object" || rawE === null) return [];
+            const e = rawE;
+            if (typeof e.from !== "string" || typeof e.status !== "string" || typeof e.ts !== "number" || typeof e.messageId !== "string") return [];
+            return [{
+              from: e.from,
+              status: e.status,
+              ...typeof e.note === "string" ? { note: e.note } : {},
+              ts: e.ts,
+              messageId: e.messageId,
+              applied: e.applied !== false
+            }];
+          }) : []
+        }];
+      }) : [{ peerId: t.to, status: t.status, acks: [] }];
+      const record = {
+        id: t.id,
+        from: t.from,
+        to: t.to,
+        prompt: t.prompt,
+        ...typeof t.context === "string" ? { context: t.context } : {},
+        ...typeof t.deliverable === "string" ? { deliverable: t.deliverable } : {},
+        status: t.status,
+        acks,
+        assignees,
+        ...typeof t.timeoutMs === "number" ? { timeoutMs: t.timeoutMs } : {},
+        ...typeof t.deadlineAt === "number" ? { deadlineAt: t.deadlineAt } : {},
+        ...typeof t.threadId === "string" ? { threadId: t.threadId } : {},
+        createdAt: typeof t.createdAt === "number" ? t.createdAt : Date.now(),
+        updatedAt: typeof t.updatedAt === "number" ? t.updatedAt : Date.now()
+      };
+      this.taskLedger.set(record.id, record);
+      this.scheduleTaskTimeout(record);
+      count++;
+    }
+    this.evictOverflowTasks();
+    return count;
+  }
   /** Recent messages involving `peer` (inbound and outbound, plus group
    * channels the peer belongs to), newest first. */
   history(peerId, limit) {
@@ -799,20 +1019,7 @@ var AgentHub = class {
     const group = this.groups.get(groupId);
     if (group === void 0) throw new Error(`unknown group: ${groupId}`);
     if (!group.members.includes(from)) throw new Error(`peer '${from}' is not a member of group '${groupId}'`);
-    const message = {
-      id: randomUUID(),
-      from,
-      to: groupId,
-      kind: "chat",
-      content,
-      channel: groupId,
-      ts: Date.now()
-    };
-    this.lastSeen.set(from, message.ts);
-    for (const member of group.members) {
-      if (member !== from && this.lastSeen.has(member)) this.deliver(member, message);
-    }
-    return message;
+    return this.route(from, groupId, "chat", content);
   }
   /** Snapshot of every group for persistence. */
   exportGroups() {
@@ -860,6 +1067,7 @@ var AgentHub = class {
         content: m.content,
         ...typeof m.ref === "string" ? { ref: m.ref } : {},
         ...typeof m.channel === "string" ? { channel: m.channel } : {},
+        ...typeof m.threadId === "string" ? { threadId: m.threadId } : {},
         ts: m.ts
       });
     }
@@ -893,6 +1101,7 @@ var AgentHub = class {
           content: m.content,
           ...typeof m.ref === "string" ? { ref: m.ref } : {},
           ...typeof m.channel === "string" ? { channel: m.channel } : {},
+          ...typeof m.threadId === "string" ? { threadId: m.threadId } : {},
           ts: m.ts
         });
       }
@@ -944,11 +1153,12 @@ var AgentHub = class {
    * 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, ref) {
+  wait(peerId, timeoutMs, from, signal, ref, threadId) {
     const startedAt = Date.now();
     const matches = (message) => {
       if (from !== void 0 && message.from !== from) return false;
       if (ref !== void 0 && !(message.kind === "ack" && message.ref === ref)) return false;
+      if (threadId !== void 0 && message.threadId !== threadId) return false;
       return true;
     };
     const queue = this.queues.get(peerId);
@@ -993,15 +1203,28 @@ var AgentHub = class {
         timer,
         onAbort,
         ...from !== void 0 ? { from } : {},
-        ...ref !== void 0 ? { ref } : {}
+        ...ref !== void 0 ? { ref } : {},
+        ...threadId !== void 0 ? { threadId } : {}
       });
       this.waiters.set(peerId, list);
     });
   }
-  /** Create a message from `from` addressed to `to` and deliver it. */
-  route(from, to, kind, content, ref) {
+  /** Create a message from `from` addressed to `to` and deliver it. `to` may
+   *  be a peer id, {@link BROADCAST}, or a group id. */
+  route(from, to, kind, content, ref, threadId) {
     if (!this.lastSeen.has(from)) throw new Error(`sender not registered: ${from}`);
-    if (to !== BROADCAST && !this.lastSeen.has(to)) throw new Error(`unknown recipient: ${to} (registered peers: ${this.peers().join(", ") || "none"})`);
+    const group = this.groups.get(to);
+    if (to !== BROADCAST && group === void 0 && !this.lastSeen.has(to)) {
+      throw new Error(`unknown recipient: ${to} (registered peers: ${this.peers().join(", ") || "none"})`);
+    }
+    let hop = 0;
+    if (ref !== void 0) {
+      const parent = this.historyRing.findLast((m) => m.id === ref);
+      hop = (parent?.hop ?? 0) + 1;
+      if (hop > MAX_HOP) {
+        throw new Error(`hop limit exceeded (max ${MAX_HOP}): start a new task/thread instead of extending this chain`);
+      }
+    }
     const message = {
       id: randomUUID(),
       from,
@@ -1009,31 +1232,42 @@ var AgentHub = class {
       kind,
       content,
       ...ref !== void 0 ? { ref } : {},
+      ...threadId !== void 0 ? { threadId } : {},
+      ...group !== void 0 ? { channel: group.id } : {},
+      ...hop > 0 ? { hop } : {},
       ts: Date.now()
     };
     this.lastSeen.set(from, message.ts);
+    this.remember(message);
     if (to === BROADCAST) {
       for (const peer of this.peers()) {
         if (peer !== from) this.deliver(peer, message);
       }
+    } else if (group !== void 0) {
+      for (const member of group.members) {
+        if (member !== from) this.deliver(member, message);
+      }
     } else {
       this.deliver(to, message);
     }
     return message;
   }
-  /** Queue or hand off a message; wake the first matching waiter for its target. */
+  /** Queue or hand off a message; wake the first matching waiter for its target.
+   *  History / onMessage are recorded by the caller (route / sendToGroup) —
+   *  exactly once per message, never per fan-out target. */
   deliver(target, message) {
     const list = this.waiters.get(target) ?? [];
     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;
+      if (waiter.threadId !== void 0 && message.threadId !== waiter.threadId) return false;
       return true;
     });
+    if (message.kind === "task") this.markTaskDelivered(message.id, target, message.ts);
     if (index >= 0) {
       const [waiter] = list.splice(index, 1);
       this.waiters.set(target, list);
       clearTimeout(waiter.timer);
-      this.remember(message);
       waiter.resolve({ type: "message", message });
       return;
     }
@@ -1041,11 +1275,10 @@ var AgentHub = class {
     if (queue.length >= this.options.maxQueue) queue.shift();
     queue.push(message);
     this.queues.set(target, queue);
-    this.remember(message);
     this.options.onQueued?.(message, target);
   }
-  /** Append a delivered message to the history ring (and fire the
-   * persistence hook — one call per message, delivered or queued). */
+  /** Append a sent message to the history ring (and fire the persistence /
+   * relay hooks). Exactly one call per message — see route() / sendToGroup(). */
   remember(message) {
     this.historyRing.push(message);
     if (this.historyRing.length > this.options.historyLimit) this.historyRing.splice(0, this.historyRing.length - this.options.historyLimit);
@@ -1215,11 +1448,13 @@ function loadTokenFileVoid(rows) {
 // src/hub-tools.ts
 var DEFAULT_WAIT_MS = 3e4;
 function present(message) {
-  const { ref, channel, ...rest } = message;
+  const { ref, channel, threadId, hop, ...rest } = message;
   return {
     ...rest,
     ...ref !== void 0 ? { ref } : {},
     ...channel !== void 0 ? { channel } : {},
+    ...threadId !== void 0 ? { threadId } : {},
+    ...hop !== void 0 ? { hop } : {},
     content: decodeContent(message.kind, message.content)
   };
 }
@@ -1320,7 +1555,10 @@ function hubTools(hub, registry, options) {
     from: message.from,
     to: message.to,
     kind: message.kind,
+    ...message.ref !== void 0 ? { ref: message.ref } : {},
     ...message.channel !== void 0 ? { channel: message.channel } : {},
+    ...message.threadId !== void 0 ? { threadId: message.threadId } : {},
+    ...message.hop !== void 0 ? { hop: message.hop } : {},
     ts: message.ts
   });
   const presentWait = (result) => result.type === "timeout" ? result : { type: "message", message: present(result.message) };
@@ -1462,70 +1700,93 @@ function hubTools(hub, registry, options) {
     },
     {
       name: "bridge_chat",
-      description: 'Send a chat message to another agent on the hub. Use bridge_wait (long-poll) or bridge_poll to receive replies. `to` is the target peerId, or "all" to broadcast.',
+      description: 'Send a chat message to another agent on the hub. Use bridge_wait (long-poll) or bridge_poll to receive replies. `to` is the target peerId, a group id, or "all" to broadcast. Optional `threadId` groups multi-turn dialogs; optional `ref` marks a reply-to.',
       inputSchema: schema(
-        { to: str('Target peerId, or "all" to broadcast.'), message: str("The message text.") },
+        {
+          to: str('Target peerId, group id, or "all" to broadcast.'),
+          message: str("The message text."),
+          threadId: optStr("Optional conversation / workflow thread id."),
+          ref: optStr("Optional reply-to message id.")
+        },
         ["to", "message"]
       ),
-      handler: wrap(true, async (args, peer) => receipt(hub.send(peer, String(args.to), "chat", String(args.message))))
+      handler: wrap(true, async (args, peer) => receipt(hub.send(peer, String(args.to), "chat", String(args.message), {
+        ...args.threadId !== void 0 ? { threadId: String(args.threadId) } : {},
+        ...args.ref !== void 0 ? { ref: String(args.ref) } : {}
+      })))
     },
     {
       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. Track progress with bridge_task_status(ref) or bridge_tasks; wait specifically for the ack with bridge_wait({ ref }).",
+      description: 'Delegate a structured task to another agent (peer, group, or "all"). The assignee acks with accepted | working | rejected | done | failed (bridge_ack). Track with bridge_task_status(ref) / bridge_tasks; wait for the ack with bridge_wait({ ref }). Optional timeoutMs marks the task `timeout` when the SLA expires without a terminal ack.',
       inputSchema: schema(
         {
-          to: str('Target peerId, or "all" to broadcast.'),
+          to: str('Target peerId, group id, or "all" to broadcast.'),
           prompt: str("What the receiving agent should do."),
           context: optStr("Optional background information for the task."),
-          deliverable: optStr("Optional expected deliverable description.")
+          deliverable: optStr("Optional expected deliverable description."),
+          timeoutMs: int("Optional soft SLA in ms; hub marks the task timeout when it expires."),
+          threadId: optStr("Optional conversation / workflow thread id.")
         },
         ["to", "prompt"]
       ),
       handler: wrap(true, async (args, peer) => receipt(hub.sendTask(peer, String(args.to), {
         prompt: String(args.prompt),
         ...args.context !== void 0 ? { context: String(args.context) } : {},
-        ...args.deliverable !== void 0 ? { deliverable: String(args.deliverable) } : {}
+        ...args.deliverable !== void 0 ? { deliverable: String(args.deliverable) } : {},
+        ...args.timeoutMs !== void 0 ? { timeoutMs: Number(args.timeoutMs) } : {},
+        ...args.threadId !== void 0 ? { threadId: String(args.threadId) } : {}
       })))
     },
     {
       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` and updates the hub task ledger (see bridge_task_status / bridge_tasks).",
+      description: "Acknowledge a message received from another agent (usually a delegated task): accepted | working | 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). `working` + `progress` (0-100) report intermediate state without finishing the task. Terminal statuses lock the task; later acks are recorded but do not reopen it.",
       inputSchema: schema(
         {
           ref: str("The id of the message being acknowledged."),
-          status: { type: "string", enum: ["accepted", "rejected", "done", "failed"], description: "acknowledgement status." },
-          note: optStr("Optional explanation for the acknowledgement.")
+          status: { type: "string", enum: ["accepted", "working", "rejected", "done", "failed"], description: "acknowledgement status." },
+          note: optStr("Optional explanation for the acknowledgement."),
+          progress: int("Optional 0-100 progress (meaningful with status=working).")
         },
         ["ref", "status"]
       ),
       handler: wrap(true, async (args, peer) => {
         const status = String(args.status);
-        const valid = ["accepted", "rejected", "done", "failed"];
+        const valid = ["accepted", "working", "rejected", "done", "failed"];
         if (!valid.includes(status)) {
           throw new Error(`invalid ack status: ${status} (expected ${valid.join(" | ")})`);
         }
-        return receipt(hub.sendAck(peer, String(args.ref), { status, ...args.note !== void 0 ? { note: String(args.note) } : {} }));
+        return receipt(hub.sendAck(peer, String(args.ref), {
+          status,
+          ...args.note !== void 0 ? { note: String(args.note) } : {},
+          ...args.progress !== void 0 ? { progress: Number(args.progress) } : {}
+        }));
       })
     },
     {
       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.",
+      description: "List delegated tasks involving you, newest first. role=sent = tasks you assigned; role=received = tasks assigned to you (or broadcast/group); status filters the ledger state (pending/accepted/working/rejected/done/failed/timeout). Each row carries the full ack timeline and per-assignee state.",
       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." },
+        status: { type: "string", enum: ["pending", "accepted", "working", "rejected", "done", "failed", "timeout"], description: "Only tasks whose current ledger status matches." },
+        peer: optStr('Manager only: "all" or another peerId for the admin board.'),
         limit: int("How many tasks to return (default 50).")
       }),
-      handler: wrap(true, async (args, peer) => {
+      handler: wrap(true, async (args, peer, sessionId) => {
         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"];
+        const validStatus = ["pending", "accepted", "working", "rejected", "done", "failed", "timeout"];
         if (status !== void 0 && !validStatus.includes(status)) {
           throw new Error(`invalid status: ${status} (expected ${validStatus.join(" | ")})`);
         }
-        const tasks = hub.listTasks(peer, {
+        let target = peer;
+        if (args.peer !== void 0) {
+          target = String(args.peer);
+          if (target !== peer) requireManager(peer, `listing tasks of '${target}'`, sessionId);
+        }
+        const tasks = hub.listTasks(target === "all" ? "all" : target, {
           ...role !== void 0 ? { role } : {},
           ...status !== void 0 ? { status } : {},
           ...args.limit !== void 0 ? { limit: Number(args.limit) } : {}
@@ -1535,7 +1796,7 @@ function hubTools(hub, registry, options) {
     },
     {
       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).",
+      description: "Status of one delegated task: current ledger state (pending \u2192 accepted/working \u2192 done/failed/timeout, or rejected), the original prompt/context/deliverable, per-assignee state, and every ack event (who, status, note, progress, 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);
@@ -1549,10 +1810,11 @@ function hubTools(hub, registry, options) {
     },
     {
       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. `ref` waits specifically for the ack of that task id. 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. `threadId` narrows to one conversation thread. 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)."),
+        threadId: optStr("Only wait for messages carrying this threadId."),
         timeoutMs: int(`Max wait in milliseconds (default ${DEFAULT_WAIT_MS}, ceiling is server waitTimeoutMs).`)
       }),
       handler: wrap(true, async (args, peer) => presentWait(await hub.wait(
@@ -1560,7 +1822,8 @@ function hubTools(hub, registry, options) {
         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)
+        args.ref === void 0 ? void 0 : String(args.ref),
+        args.threadId === void 0 ? void 0 : String(args.threadId)
       )))
     },
     {
@@ -2380,7 +2643,7 @@ function readBody(req) {
 import { DatabaseSync } from "node:sqlite";
 var KIND_NAMES = ["chat", "task", "notice", "ack"];
 function messageToRow(message) {
-  return [message.id, message.from, message.to, message.kind, message.content, message.ref ?? null, message.channel ?? null, message.ts];
+  return [message.id, message.from, message.to, message.kind, message.content, message.ref ?? null, message.channel ?? null, message.threadId ?? null, message.ts];
 }
 function rowToMessage(row) {
   const id = row.id;
@@ -2399,6 +2662,7 @@ function rowToMessage(row) {
     content,
     ...typeof row.ref === "string" && row.ref !== "" ? { ref: row.ref } : {},
     ...typeof row.channel === "string" && row.channel !== "" ? { channel: row.channel } : {},
+    ...typeof row.thread_id === "string" && row.thread_id !== "" ? { threadId: row.thread_id } : {},
     ts
   };
 }
@@ -2413,16 +2677,25 @@ var SQLiteStateStore = class {
       );
       CREATE TABLE IF NOT EXISTS messages (
         seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL, from_peer TEXT NOT NULL,
-        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, ts INTEGER NOT NULL
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, thread_id TEXT, ts INTEGER NOT NULL
       );
       CREATE TABLE IF NOT EXISTS mailboxes (
         peer TEXT NOT NULL, seq INTEGER PRIMARY KEY AUTOINCREMENT, id TEXT NOT NULL, from_peer TEXT NOT NULL,
-        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, ts INTEGER NOT NULL
+        to_peer TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL, ref TEXT, channel TEXT, thread_id TEXT, ts INTEGER NOT NULL
       );
       CREATE TABLE IF NOT EXISTS groups (
         id TEXT PRIMARY KEY, name TEXT, members TEXT NOT NULL, created_by TEXT NOT NULL, created_at INTEGER NOT NULL
       );
+      CREATE TABLE IF NOT EXISTS tasks (
+        id TEXT PRIMARY KEY, body TEXT NOT NULL, updated_at INTEGER NOT NULL
+      );
     `);
+    for (const table of ["messages", "mailboxes"]) {
+      try {
+        this.db.exec(`ALTER TABLE ${table} ADD COLUMN thread_id TEXT`);
+      } catch {
+      }
+    }
     log.info(`sqlite state open: ${file}`);
   }
   db;
@@ -2431,17 +2704,17 @@ var SQLiteStateStore = class {
   appendMessage(message) {
     this.buffer.push(message);
   }
-  /** Insert buffered messages and re-snapshot mailboxes/profiles/groups. */
+  /** Insert buffered messages and re-snapshot mailboxes/profiles/groups/tasks. */
   flush(snapshot) {
     const insert = this.db.prepare(
-      "INSERT INTO messages (id, from_peer, to_peer, kind, content, ref, channel, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+      "INSERT INTO messages (id, from_peer, to_peer, kind, content, ref, channel, thread_id, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
     );
     for (const message of this.buffer.splice(0, this.buffer.length)) {
       insert.run(...messageToRow(message));
     }
     this.db.exec("DELETE FROM mailboxes");
     const insertMail = this.db.prepare(
-      "INSERT INTO mailboxes (peer, id, from_peer, to_peer, kind, content, ref, channel, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)"
+      "INSERT INTO mailboxes (peer, id, from_peer, to_peer, kind, content, ref, channel, thread_id, ts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
     );
     for (const [peer, queue] of Object.entries(snapshot.mailboxes)) {
       for (const message of queue) insertMail.run(peer, ...messageToRow(message));
@@ -2460,6 +2733,13 @@ var SQLiteStateStore = class {
     for (const group of snapshot.groups) {
       insertGroup.run(group.id, group.name ?? null, JSON.stringify(group.members), group.createdBy, group.createdAt);
     }
+    this.db.exec("DELETE FROM tasks");
+    const insertTask = this.db.prepare(
+      "INSERT INTO tasks (id, body, updated_at) VALUES (?, ?, ?)"
+    );
+    for (const task of snapshot.tasks) {
+      insertTask.run(task.id, JSON.stringify(task), task.updatedAt);
+    }
     const row = this.db.prepare("SELECT COUNT(*) AS n FROM messages").get();
     const total = Number(row.n);
     if (total > this.historyLimit * 2) {
@@ -2507,7 +2787,16 @@ var SQLiteStateStore = class {
       } catch {
       }
     }
-    return { profiles, messages, mailboxes, groups };
+    const tasks = [];
+    for (const row of this.db.prepare("SELECT * FROM tasks").all()) {
+      if (typeof row.body !== "string") continue;
+      try {
+        const parsed = JSON.parse(row.body);
+        if (typeof parsed === "object" && parsed !== null) tasks.push(parsed);
+      } catch {
+      }
+    }
+    return { profiles, messages, mailboxes, groups, tasks };
   }
   /** Final flush + close (hub shutdown). */
   close(snapshot) {
@@ -2518,7 +2807,7 @@ var SQLiteStateStore = class {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.8.0";
+var SERVER_VERSION = "0.9.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -2621,7 +2910,7 @@ function startHub(config = {}, log = console) {
     if (dbDirty && dbStore !== void 0) {
       dbDirty = false;
       try {
-        dbStore.flush({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups() });
+        dbStore.flush({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups(), tasks: hub.exportTasks() });
       } catch (error) {
         log.warn(`sqlite flush failed: ${error.message}`);
       }
@@ -2651,6 +2940,7 @@ function startHub(config = {}, log = console) {
       if (dbStore !== void 0) {
         dbStore.appendMessage(message);
         dbDirty = true;
+        scheduleSave();
       }
       try {
         pushRelay(message);
@@ -2661,6 +2951,15 @@ function startHub(config = {}, log = console) {
     onMailboxesChanged: () => {
       if (dbStore === void 0) return;
       dbDirty = true;
+      scheduleSave();
+    },
+    // Task ledger transitions (ack folding, SLA timeout, first delivery) are
+    // their own persistence trigger: without it a crash between two roster
+    // events loses the ledger state the admin board reads back.
+    onTaskChanged: () => {
+      if (dbStore === void 0) return;
+      dbDirty = true;
+      scheduleSave();
     },
     onGroupsChanged: () => {
       if (dbStore === void 0) return;
@@ -2711,6 +3010,7 @@ function startHub(config = {}, log = console) {
       const restoredMessages = hub.importHistory(state.messages);
       const restoredQueued = hub.importMailboxes(state.mailboxes);
       const restoredGroups = hub.importGroups(state.groups);
+      const restoredTasks = hub.importTasks(state.tasks);
       if (restoredMessages + restoredQueued + restoredGroups > 0) {
         log.info(`state restored from ${resolved.db}: ${restoredMessages} message(s), ${restoredQueued} queued, ${restoredGroups} group(s)`);
         dbDirty = true;
@@ -2813,7 +3113,7 @@ function startHub(config = {}, log = console) {
       flushSaves();
       if (dbStore !== void 0) {
         try {
-          dbStore.close({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups() });
+          dbStore.close({ mailboxes: hub.exportMailboxes(), profiles: hub.exportProfiles(), groups: hub.exportGroups(), tasks: hub.exportTasks() });
         } catch (error) {
           log.warn(`sqlite close failed: ${error.message}`);
         }
@@ -2834,6 +3134,7 @@ export {
   DEFAULT_PORT,
   HerdrCtl,
   KINDS,
+  MAX_HOP,
   McpStreamableHttpServer,
   PEER_ID_PATTERN,
   SERVER_NAME,
@@ -2841,13 +3142,16 @@ export {
   SQLiteStateStore,
   SessionRegistry,
   TERMINAL_TASK_STATUSES,
+  ackToTaskStatus,
   addToken,
+  aggregateTaskStatus,
   autoRegisterPeer,
   decodeContent,
   encodeContent,
   generateToken,
   hubTools,
   loadTokenFile,
+  nextTaskStatus,
   present,
   readTokens,
   removeToken,