agent-comm-hub 0.5.0 → 0.6.0

package/lib/index.js

@@ -1,5 +1,7 @@
 // src/index.ts
 import { createServer } from "node:http";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
 
 // src/herdr-ctl.ts
 import { execFile } from "node:child_process";
@@ -433,6 +435,7 @@ function decodeContent(kind, content) {
 }
 
 // src/hub.ts
+var MAX_PROFILES = 512;
 var AgentHub = class {
   constructor(options) {
     this.options = options;
@@ -447,6 +450,8 @@ var AgentHub = class {
   waiters = /* @__PURE__ */ new Map();
   historyRing = [];
   lastSeen = /* @__PURE__ */ new Map();
+  /** Identity metadata keyed by peer id; outlives registration (see {@link PeerProfile}). */
+  profiles = /* @__PURE__ */ new Map();
   gcTimer;
   /** Stop the idle GC (call when the hub shuts down). */
   dispose() {
@@ -466,13 +471,25 @@ var AgentHub = class {
   peers() {
     return [...this.lastSeen.keys()];
   }
-  /** Register a peer; throws if the id is already taken. */
-  register(peerId) {
+  /** Register a peer; throws if the id is already taken. Client metadata
+   * (when provided) refreshes the profile — with same-name sessions sharing a
+   * peer, the freshest connect wins, which self-heals stale metadata. */
+  register(peerId, client) {
     if (this.lastSeen.has(peerId)) throw new Error(`peer already registered: ${peerId}`);
     this.lastSeen.set(peerId, Date.now());
+    const existing = this.profiles.get(peerId);
+    this.profiles.set(peerId, {
+      ...existing,
+      id: peerId,
+      registeredAt: existing?.registeredAt ?? Date.now(),
+      ...client?.name !== void 0 ? { clientName: client.name } : existing?.clientName !== void 0 ? { clientName: existing.clientName } : {},
+      ...client?.version !== void 0 ? { clientVersion: client.version } : existing?.clientVersion !== void 0 ? { clientVersion: existing.clientVersion } : {}
+    });
+    this.evictOverflowProfiles();
     this.options.onPeersChanged?.(this.peers());
   }
-  /** Remove a peer and its queued messages; pending waiters resolve as timeouts. */
+  /** Remove a peer and its queued messages; pending waiters resolve as
+   * timeouts. The profile is kept so a reconnecting peer keeps its alias. */
   unregister(peerId) {
     this.queues.delete(peerId);
     for (const waiter of this.waiters.get(peerId) ?? []) {
@@ -483,6 +500,110 @@ var AgentHub = class {
     this.lastSeen.delete(peerId);
     this.options.onPeersChanged?.(this.peers());
   }
+  /** Identity metadata for `peerId`, if the hub ever saw it. */
+  profileOf(peerId) {
+    return this.profiles.get(peerId);
+  }
+  /** Snapshot of every known profile (registered or not) for persistence. */
+  exportProfiles() {
+    return [...this.profiles.values()].map((profile) => ({ ...profile }));
+  }
+  /** Load persisted profiles at boot. Invalid entries are dropped; `null`-ish
+   * and non-finite fields are sanitized. Returns the imported count. Silent
+   * for roster observers — this runs before the server accepts requests. */
+  importProfiles(profiles) {
+    if (!Array.isArray(profiles)) return 0;
+    let count = 0;
+    for (const raw of profiles) {
+      if (typeof raw !== "object" || raw === null) continue;
+      const candidate = raw;
+      const id = candidate.id;
+      if (typeof id !== "string" || !PEER_ID_PATTERN.test(id) || id === BROADCAST) continue;
+      if (this.profiles.has(id)) continue;
+      const profile = {
+        id,
+        registeredAt: typeof candidate.registeredAt === "number" && Number.isFinite(candidate.registeredAt) ? candidate.registeredAt : Date.now()
+      };
+      if (typeof candidate.alias === "string" && candidate.alias !== "") profile.alias = candidate.alias;
+      if (typeof candidate.clientName === "string" && candidate.clientName !== "") profile.clientName = candidate.clientName;
+      if (typeof candidate.clientVersion === "string" && candidate.clientVersion !== "") profile.clientVersion = candidate.clientVersion;
+      this.profiles.set(id, profile);
+      count++;
+    }
+    this.evictOverflowProfiles();
+    return count;
+  }
+  /** Set (or clear with `undefined`) the display alias of a registered peer.
+   * Routing state is untouched — this only changes how the peer is shown. */
+  setAlias(peerId, alias) {
+    if (!this.lastSeen.has(peerId)) throw new Error(`unknown peer: ${peerId}`);
+    const profile = this.profiles.get(peerId);
+    if (profile !== void 0) {
+      this.profiles.set(peerId, alias === void 0 ? omit(profile, "alias") : { ...profile, alias });
+    }
+    this.options.onPeersChanged?.(this.peers());
+  }
+  /**
+   * Atomically re-key a registered peer: mailbox, waiters, last-seen,
+   * profile, session bindings (via the caller's registry), and history
+   * attribution move from `oldId` to `newId` in one step, so queued
+   * messages, pending waits, ack routing, and history continuity all
+   * survive the rename. All validation happens before the first mutation.
+   */
+  renamePeer(oldId, newId) {
+    if (oldId === newId) return;
+    if (!this.lastSeen.has(oldId)) throw new Error(`unknown peer: ${oldId}`);
+    if (newId === BROADCAST) throw new Error(`reserved peer id: ${newId}`);
+    if (!PEER_ID_PATTERN.test(newId)) throw new Error(`invalid peerId: ${newId} (expected [A-Za-z0-9._:-]{1,64})`);
+    if (this.lastSeen.has(newId)) throw new Error(`peer already registered: ${newId}`);
+    const queue = this.queues.get(oldId);
+    const waiters = this.waiters.get(oldId);
+    const seen = this.lastSeen.get(oldId) ?? Date.now();
+    const profile = this.profiles.get(oldId);
+    const stale = this.profiles.get(newId);
+    this.queues.delete(oldId);
+    this.waiters.delete(oldId);
+    this.lastSeen.delete(oldId);
+    this.profiles.delete(oldId);
+    if (queue !== void 0) this.queues.set(newId, queue);
+    if (waiters !== void 0) this.waiters.set(newId, waiters);
+    this.lastSeen.set(newId, seen);
+    if (profile !== void 0) {
+      const merged = {
+        ...stale,
+        ...profile,
+        id: newId,
+        registeredAt: stale !== void 0 && stale.registeredAt < profile.registeredAt ? stale.registeredAt : profile.registeredAt
+      };
+      this.profiles.set(newId, merged);
+    } else if (stale !== void 0) {
+      this.profiles.set(newId, stale);
+    } else {
+      this.profiles.set(newId, { id: newId, registeredAt: Date.now() });
+    }
+    for (const list of this.waiters.values()) {
+      for (const waiter of list) {
+        if (waiter.from === oldId) waiter.from = newId;
+      }
+    }
+    for (const message of this.historyRing) {
+      if (message.from === oldId) message.from = newId;
+      if (message.to === oldId) message.to = newId;
+    }
+    this.options.onPeersChanged?.(this.peers());
+  }
+  /** Keep the profile map bounded: drop the oldest profiles of peers that are
+   * NOT currently registered (live peers are never evicted). */
+  evictOverflowProfiles() {
+    if (this.profiles.size <= MAX_PROFILES) return;
+    const evictable = [...this.profiles.values()].filter((profile) => !this.lastSeen.has(profile.id)).sort((a, b) => a.registeredAt - b.registeredAt);
+    let overflow = this.profiles.size - MAX_PROFILES;
+    for (const profile of evictable) {
+      if (overflow <= 0) break;
+      this.profiles.delete(profile.id);
+      overflow--;
+    }
+  }
   /** Mark activity for `peer` (called on every tool call from that peer). */
   touch(peerId) {
     if (this.lastSeen.has(peerId)) this.lastSeen.set(peerId, Date.now());
@@ -529,13 +650,17 @@ var AgentHub = class {
     const now = Date.now();
     return {
       server: "agent-comm-hub",
-      peers: this.peers().map((peer) => ({
-        id: peer,
-        connected: this.isActive(peer) || livePeers?.has(peer) === true,
-        lastSeenMs: this.lastSeen.get(peer) ?? 0,
-        queued: (this.queues.get(peer) ?? []).length,
-        waiting: (this.waiters.get(peer) ?? []).length
-      })),
+      peers: this.peers().map((peer) => {
+        const alias = this.profiles.get(peer)?.alias;
+        return {
+          id: peer,
+          ...alias !== void 0 ? { alias } : {},
+          connected: this.isActive(peer) || livePeers?.has(peer) === true,
+          lastSeenMs: this.lastSeen.get(peer) ?? 0,
+          queued: (this.queues.get(peer) ?? []).length,
+          waiting: (this.waiters.get(peer) ?? []).length
+        };
+      }),
       historyLimit: this.options.historyLimit,
       maxQueue: this.options.maxQueue
     };
@@ -627,7 +752,7 @@ var AgentHub = class {
     if (queue.length >= this.options.maxQueue) queue.shift();
     queue.push(message);
     this.queues.set(target, queue);
-    this.options.onQueued?.(message);
+    this.options.onQueued?.(message, target);
   }
   /** Append a delivered message to the history ring. */
   remember(message) {
@@ -645,6 +770,10 @@ function drainFrom(queue, from) {
   queue.splice(0, queue.length, ...kept);
   return drained;
 }
+function omit(value, key) {
+  const { [key]: _dropped, ...rest } = value;
+  return rest;
+}
 
 // src/hub-tools.ts
 var DEFAULT_WAIT_MS = 3e4;
@@ -660,13 +789,25 @@ function sanitizePeerId(name) {
   const cleaned = name.toLowerCase().replace(/[^a-z0-9._:-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
   return cleaned === "" ? "agent" : cleaned;
 }
-function autoRegisterPeer(hub, registry, sessionId, clientName) {
+function sanitizeAlias(alias) {
+  const cleaned = alias.trim();
+  if (cleaned === "") throw new Error("alias must not be empty");
+  if (cleaned.length > 64) throw new Error(`alias too long: ${cleaned.length} chars (max 64)`);
+  if (/[\u0000-\u001f\u007f]/.test(cleaned)) throw new Error("alias must not contain control characters");
+  return cleaned;
+}
+function autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion) {
   if (sessionId === void 0) return void 0;
   const bound = registry.peerFor(sessionId);
   if (bound !== void 0) return bound;
   if (registry.isSuppressed(sessionId)) return void 0;
   const peerId = sanitizePeerId(clientName ?? "agent");
-  if (!hub.has(peerId)) hub.register(peerId);
+  if (!hub.has(peerId)) {
+    hub.register(peerId, {
+      ...clientName !== void 0 ? { name: clientName } : {},
+      ...clientVersion !== void 0 ? { version: clientVersion } : {}
+    });
+  }
   registry.bindPeer(sessionId, peerId);
   hub.touch(peerId);
   return peerId;
@@ -679,6 +820,23 @@ function livePeersFor(registry) {
   }
   return live;
 }
+function rosterFor(hub, registry) {
+  const status = hub.status(livePeersFor(registry));
+  return status.peers.map((peer) => {
+    const profile = hub.profileOf(peer.id);
+    const alias = profile?.alias;
+    const clientName = profile?.clientName;
+    const clientVersion = profile?.clientVersion;
+    return {
+      id: peer.id,
+      ...alias !== void 0 ? { alias } : {},
+      ...clientName !== void 0 ? { clientName } : {},
+      ...clientVersion !== void 0 ? { clientVersion } : {},
+      connected: peer.connected,
+      lastSeenMs: peer.lastSeenMs
+    };
+  });
+}
 function hubTools(hub, registry, options) {
   const schema = (properties, required = []) => ({
     type: "object",
@@ -722,6 +880,12 @@ function hubTools(hub, registry, options) {
     }
     return herdr;
   };
+  const requireManager = (peer, action) => {
+    const managers = options.managerPeers ?? "all";
+    if (managers !== "all" && !managers.has(peer)) {
+      throw new Error(`peer '${peer}' is not a hub manager \u2014 ${action} requires manager rights`);
+    }
+  };
   const asStatuses = (value) => {
     if (!Array.isArray(value)) return void 0;
     const statuses = value.map(String).filter((status) => AGENT_STATUSES.includes(status));
@@ -734,42 +898,108 @@ function hubTools(hub, registry, options) {
   return [
     {
       name: "bridge_register",
-      description: 'Claim or rename your identity on the hub. Sessions auto-share a peer id derived from the client name; call this to switch to a readable unique peerId such as "mavis" or "opencode:myproject". Rejects when the id is claimed by another connection. Returns the current peer list.',
-      inputSchema: schema({ peerId: str("Unique peer id: letters/digits/._:- , 1-64 chars.") }, ["peerId"]),
+      description: 'Claim or rename your identity on the hub. Sessions auto-share a peer id derived from the client name; call this to switch to a readable unique peerId such as "mavis" or "opencode:myproject". Optionally set your display alias (shown to other agents and the desktop roster; message routing keeps using the immutable peerId). Rejects when the id is claimed by another connection. Returns the current peer list.',
+      inputSchema: schema({
+        peerId: str("Unique peer id: letters/digits/._:- , 1-64 chars."),
+        alias: optStr("Optional display name (1-64 chars, spaces/CJK allowed). Routing still uses peerId.")
+      }, ["peerId"]),
       handler: async (args, sessionId) => {
         const peerId = String(args.peerId);
-        if (!/^[A-Za-z0-9._:-]{1,64}$/.test(peerId)) {
+        if (!PEER_ID_PATTERN.test(peerId)) {
           throw new Error(`invalid peerId: ${peerId} (expected [A-Za-z0-9._:-]{1,64})`);
         }
+        if (peerId === BROADCAST) {
+          throw new Error(`reserved peer id: ${peerId} (it is the broadcast address)`);
+        }
+        const alias = args.alias === void 0 ? void 0 : sanitizeAlias(String(args.alias));
         if (hub.has(peerId) && registry.peerFor(sessionId) !== peerId) {
           throw new Error(`peer already registered by another connection: ${peerId}`);
         }
         const current = registry.peerFor(sessionId);
         if (current !== void 0 && current !== peerId) {
-          registry.unbindPeer(sessionId);
-          if (registry.attachedCount(current) === 0) hub.unregister(current);
+          if (registry.attachedCount(current) === 1) {
+            hub.renamePeer(current, peerId);
+            registry.rebindPeerId(current, peerId);
+          } else {
+            registry.unbindPeer(sessionId);
+            if (registry.attachedCount(current) === 0) hub.unregister(current);
+          }
         }
-        registry.bindPeer(sessionId, peerId);
         if (!hub.has(peerId)) hub.register(peerId);
+        registry.bindPeer(sessionId, peerId);
         registry.clearSuppress(sessionId);
         hub.touch(peerId);
-        return { ok: true, peerId, peers: hub.peers() };
+        if (alias !== void 0) hub.setAlias(peerId, alias);
+        const finalAlias = hub.profileOf(peerId)?.alias;
+        return { ok: true, peerId, ...finalAlias !== void 0 ? { alias: finalAlias } : {}, peers: hub.peers() };
       }
     },
     {
       name: "bridge_unregister",
-      description: "Leave the hub: detaches your session (and drops the peer when no other session shares it); auto-registration stays off until an explicit bridge_register. Idempotent.",
-      inputSchema: schema({}),
-      handler: async (_args, sessionId) => {
-        const peer = registry.peerFor(sessionId);
-        if (peer !== void 0) {
-          registry.unbindPeer(sessionId);
-          if (registry.attachedCount(peer) === 0) hub.unregister(peer);
+      description: "Leave the hub: detaches your session (and drops the peer when no other session shares it); auto-registration stays off until an explicit bridge_register. With `peer`, a hub MANAGER can kick another peer: its queue is dropped and every session attached to it is detached and kept from auto-re-registering. Idempotent.",
+      inputSchema: schema({
+        peer: optStr("Kick this peer instead of yourself. Requires manager rights (hub managerPeers).")
+      }),
+      handler: async (args, sessionId) => {
+        if (args.peer === void 0) {
+          const peer = registry.peerFor(sessionId);
+          if (peer !== void 0) {
+            registry.unbindPeer(sessionId);
+            if (registry.attachedCount(peer) === 0) hub.unregister(peer);
+          }
+          registry.suppressAuto(sessionId);
+          return { ok: true, peerId: peer ?? null };
+        }
+        const caller = registry.peerFor(sessionId);
+        if (caller === void 0) throw new Error("not registered \u2014 call bridge_register(peerId) first");
+        const target = String(args.peer);
+        requireManager(caller, `kicking '${target}'`);
+        if (!hub.has(target)) {
+          return { ok: true, peerId: null, kicked: false };
         }
-        registry.suppressAuto(sessionId);
-        return { ok: true, peerId: peer ?? null };
+        hub.unregister(target);
+        const detached = registry.unbindPeerId(target, { suppress: true });
+        return { ok: true, peerId: target, kicked: true, detachedSessions: detached.length };
       }
     },
+    {
+      name: "bridge_rename",
+      description: "Rename on the hub, two layers: (1) `alias` sets a display name \u2014 cosmetic only, it shows up in bridge_peers / bridge_status and the desktop roster while routing, mailboxes, and history keep the immutable peer id; renaming yourself is open to everyone. (2) `peerId` truly re-keys another registered peer (manager rights required): mailbox, waiters, session bindings, and history attribution move atomically, so queued messages and acks stay continuous. Renaming ANOTHER peer (either layer) requires manager rights (hub managerPeers).",
+      inputSchema: schema({
+        alias: optStr("New display name (1-64 chars, spaces/CJK allowed; empty string clears back to no alias)."),
+        peerId: optStr("New routing id for `peer` \u2014 a true rename that moves all state (manager only). Target must be a registered peer."),
+        peer: optStr("Whose name/id to change; default yourself. Changing another peer requires manager rights.")
+      }),
+      handler: wrap(true, async (args, peer) => {
+        const hasAlias = args.alias !== void 0;
+        const hasPeerId = args.peerId !== void 0;
+        if (!hasAlias && !hasPeerId) {
+          throw new Error("nothing to rename: pass alias and/or peerId");
+        }
+        let target = args.peer === void 0 ? peer : String(args.peer);
+        if (target !== peer) requireManager(peer, `renaming '${target}'`);
+        let previousId;
+        if (hasPeerId) {
+          if (args.peer === void 0) {
+            throw new Error("peerId requires peer \u2014 to change your own id, call bridge_register(newId)");
+          }
+          const newId = String(args.peerId);
+          if (!PEER_ID_PATTERN.test(newId)) {
+            throw new Error(`invalid peerId: ${newId} (expected [A-Za-z0-9._:-]{1,64})`);
+          }
+          previousId = target;
+          hub.renamePeer(target, newId);
+          registry.rebindPeerId(target, newId);
+          target = newId;
+        }
+        if (hasAlias) {
+          const alias = String(args.alias).trim();
+          hub.setAlias(target, alias === "" ? void 0 : sanitizeAlias(alias));
+        }
+        const applied = hub.profileOf(target)?.alias;
+        return { ok: true, peerId: target, ...previousId !== void 0 ? { previousId } : {}, ...applied !== void 0 ? { alias: applied } : {} };
+      })
+    },
     {
       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.',
@@ -840,20 +1070,21 @@ function hubTools(hub, registry, options) {
     },
     {
       name: "bridge_peers",
-      description: "List registered peers and whether each is connected (recent activity or a live SSE channel).",
+      description: "List registered peers with their display identity and connection state: id (immutable routing name), optional alias (display name), client name/version reported at connect, whether connected (recent activity or a live SSE channel), and lastSeenMs.",
       inputSchema: schema({}),
-      handler: wrap(true, async () => {
-        const status = hub.status(livePeersFor(registry));
-        return { peers: hub.peers().map((id) => ({ id, connected: status.peers.find((peer) => peer.id === id)?.connected ?? false })) };
-      })
+      handler: wrap(true, async () => ({ peers: rosterFor(hub, registry) }))
     },
     {
       name: "bridge_history",
-      description: 'Recent messages involving you (newest first); pass `peer` to inspect another peer\'s conversation, or `peer: "all"` for the unfiltered tail across every peer. Use to refresh context after a reconnect.',
-      inputSchema: schema({ peer: optStr('PeerId whose conversation to inspect; "all" = every peer; default: yourself.'), limit: int("How many messages to return (default 20).") }),
+      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).") }),
       handler: wrap(true, async (args, peer) => {
         const limit = Math.min(args.limit === void 0 ? 20 : Number(args.limit), 1e3);
-        const messages = args.peer === "all" ? hub.historyAll(limit) : hub.history(args.peer === void 0 ? peer : String(args.peer), limit);
+        const target = args.peer === void 0 ? peer : String(args.peer);
+        if (target !== peer) {
+          requireManager(peer, `reading ${target === BROADCAST ? "the full history" : `peer '${target}' history`} requires manager rights`);
+        }
+        const messages = target === BROADCAST ? hub.historyAll(limit) : hub.history(target, limit);
         return { messages: messages.map(present) };
       })
     },
@@ -1099,15 +1330,23 @@ var SessionRegistry = class {
   }
   /** Client-reported name per session (from the initialize clientInfo). */
   clientNames = /* @__PURE__ */ new Map();
-  /** Remember the client name reported by a session (on initialize). */
-  noteClient(sessionId, name) {
+  /** Client-reported version per session (undefined when not reported). */
+  clientVersions = /* @__PURE__ */ new Map();
+  /** Remember the client name/version reported by a session (on initialize). */
+  noteClient(sessionId, name, version) {
     this.clientNames.set(sessionId, name);
+    if (version !== void 0) this.clientVersions.set(sessionId, version);
   }
   /** Client-reported name for a session, if any. */
   clientName(sessionId) {
     if (sessionId === void 0) return void 0;
     return this.clientNames.get(sessionId);
   }
+  /** Client-reported version for a session, if any. */
+  clientVersion(sessionId) {
+    if (sessionId === void 0) return void 0;
+    return this.clientVersions.get(sessionId);
+  }
   /** Sessions whose owner explicitly unregistered; auto-registration is
    * suppressed for them until an explicit `bridge_register`. */
   suppressedAuto = /* @__PURE__ */ new Set();
@@ -1137,11 +1376,39 @@ var SessionRegistry = class {
   liveSessions() {
     return this.liveStreams;
   }
-  /** Drop every binding that points at `peerId` (used by the idle GC). */
-  unbindPeerId(peerId) {
+  /** Drop every binding that points at `peerId` (used by the idle GC). With
+   * `suppress`, the detached sessions also stop auto-re-registering — the
+   * manager-kick path, so a kicked agent stays out until it explicitly
+   * `bridge_register`s or reconnects with a fresh session. */
+  unbindPeerId(peerId, options) {
+    const detached = [];
+    for (const [sessionId, bound] of this.peerBindings) {
+      if (bound === peerId) {
+        this.peerBindings.delete(sessionId);
+        detached.push(sessionId);
+        if (options?.suppress === true) this.suppressedAuto.add(sessionId);
+      }
+    }
+    return detached;
+  }
+  /** Session ids currently attached to `peerId` (any binding direction). */
+  sessionsForPeer(peerId) {
+    const sessions = [];
     for (const [sessionId, bound] of this.peerBindings) {
-      if (bound === peerId) this.peerBindings.delete(sessionId);
+      if (bound === peerId) sessions.push(sessionId);
     }
+    return sessions;
+  }
+  /** Re-point every session bound to `oldId` at `newId` (true rename). */
+  rebindPeerId(oldId, newId) {
+    let count = 0;
+    for (const [sessionId, bound] of this.peerBindings) {
+      if (bound === oldId) {
+        this.peerBindings.set(sessionId, newId);
+        count++;
+      }
+    }
+    return count;
   }
   /** How many sessions are currently attached to `peerId`. */
   attachedCount(peerId) {
@@ -1191,6 +1458,30 @@ var McpStreamableHttpServer = class {
     for (const stream of this.sseStreams.values()) stream.end();
     this.sseStreams.clear();
   }
+  /** Push a JSON-RPC notification to every open SSE stream (roster events are
+   * public — any peer could poll bridge_peers for the same information).
+   * Write failures drop the dead stream silently; SSE is best-effort and
+   * long-poll (bridge_wait) remains the reliable delivery path. */
+  notifyAll(method, params) {
+    this.notify([...this.sseStreams.keys()], method, params);
+  }
+  /** Push a JSON-RPC notification to the SSE streams of specific sessions. */
+  notify(sessionIds, method, params) {
+    const frame = `event: message
+data: ${JSON.stringify({ jsonrpc: "2.0", method, params })}
+
+`;
+    for (const sessionId of sessionIds) {
+      const stream = this.sseStreams.get(sessionId);
+      if (stream === void 0) continue;
+      try {
+        stream.write(frame);
+      } catch {
+        this.sseStreams.delete(sessionId);
+        this.registry.markSseClosed(sessionId);
+      }
+    }
+  }
   handleGet(req, res) {
     const sessionId = this.registry.ensureSession(this.registry.sessionIdFor(req));
     res.writeHead(200, {
@@ -1254,10 +1545,11 @@ var McpStreamableHttpServer = class {
         const newSessionId = this.registry.ensureSession(sessionId);
         const clientInfo = message.params?.clientInfo;
         const clientName = typeof clientInfo?.name === "string" && clientInfo.name !== "" ? clientInfo.name : void 0;
+        const clientVersion = typeof clientInfo?.version === "string" && clientInfo.version !== "" ? clientInfo.version : void 0;
         if (clientName !== void 0) {
-          this.registry.noteClient(newSessionId, clientName);
+          this.registry.noteClient(newSessionId, clientName, clientVersion);
         }
-        this.onInitialize(newSessionId, clientName);
+        this.onInitialize(newSessionId, clientName, clientVersion);
         const requested = message.params?.protocolVersion;
         const protocolVersion = typeof requested === "string" && SUPPORTED_VERSIONS.includes(requested) ? requested : LATEST_VERSION;
         return {
@@ -1347,7 +1639,7 @@ function readBody(req) {
 
 // src/index.ts
 var SERVER_NAME = "agent-comm-hub";
-var SERVER_VERSION = "0.5.0";
+var SERVER_VERSION = "0.6.0";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 18764;
 var DEFAULT_PATH = "/mcp";
@@ -1363,11 +1655,57 @@ var DEFAULT_CONFIG = {
   waitTimeoutMs: 6e4,
   defaultWaitMs: 3e4,
   connectedWindowMs: 3e4,
-  peerIdleTimeoutMs: 6e5
+  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"]
 };
+function writeRosterFile(file, profiles) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.tmp`;
+  writeFileSync(tmp, JSON.stringify({ version: 1, savedAt: Date.now(), profiles }), "utf8");
+  renameSync(tmp, file);
+}
 function startHub(config = {}, log = console) {
   const overrides = Object.fromEntries(Object.entries(config).filter(([, value]) => value !== void 0));
   const resolved = { ...DEFAULT_CONFIG, ...overrides };
+  let mcp;
+  const pushRoster = () => {
+    mcp.notifyAll("notifications/message", {
+      level: "info",
+      logger: "bridge",
+      data: { event: "peers_changed", peers: rosterFor(hub, registry) }
+    });
+  };
+  const pushQueued = (message, target) => {
+    mcp.notify(registry.sessionsForPeer(target), "notifications/message", {
+      level: "info",
+      logger: "bridge",
+      data: { event: "message", message: present(message) }
+    });
+  };
+  let saveTimer;
+  let rosterDirty = false;
+  const flushRoster = () => {
+    if (resolved.stateFile === void 0 || !rosterDirty) return;
+    rosterDirty = false;
+    try {
+      writeRosterFile(resolved.stateFile, hub.exportProfiles());
+    } catch (error) {
+      log.warn(`roster save failed: ${error.message}`);
+    }
+  };
+  const scheduleRosterSave = () => {
+    if (resolved.stateFile === void 0) return;
+    rosterDirty = true;
+    if (saveTimer !== void 0) return;
+    saveTimer = setTimeout(() => {
+      saveTimer = void 0;
+      flushRoster();
+    }, 500);
+    saveTimer.unref?.();
+  };
   const hub = new AgentHub({
     maxQueue: resolved.maxQueue,
     historyLimit: resolved.historyLimit,
@@ -1376,9 +1714,37 @@ function startHub(config = {}, log = console) {
     peerIdleTimeoutMs: resolved.peerIdleTimeoutMs,
     onPeerGc: (peerId) => registry.unbindPeerId(peerId),
     // The idle GC must never evict a peer whose session has a live SSE channel.
-    isPeerLive: (peerId) => livePeersFor(registry).has(peerId)
+    isPeerLive: (peerId) => livePeersFor(registry).has(peerId),
+    // SSE event push: roster changes and queued-mail hints. Best-effort — a
+    // notification failure must never break routing, so swallow and log.
+    onPeersChanged: () => {
+      try {
+        pushRoster();
+      } catch (error) {
+        log.warn(`peers_changed notification failed: ${error.message}`);
+      }
+      scheduleRosterSave();
+    },
+    onQueued: (message, target) => {
+      try {
+        pushQueued(message, target);
+      } catch (error) {
+        log.warn(`message notification failed: ${error.message}`);
+      }
+    }
   });
   const registry = new SessionRegistry();
+  if (resolved.stateFile !== void 0) {
+    try {
+      const parsed = JSON.parse(readFileSync(resolved.stateFile, "utf8"));
+      const imported = hub.importProfiles(parsed.profiles);
+      if (imported > 0) log.info(`roster restored: ${imported} profile(s) from ${resolved.stateFile}`);
+    } catch (error) {
+      if (error.code !== "ENOENT") {
+        log.warn(`roster load failed: ${error.message}`);
+      }
+    }
+  }
   const herdr = new HerdrCtl({
     bin: resolved.herdrBin,
     baseArgs: resolved.herdrBaseArgs,
@@ -1386,19 +1752,20 @@ function startHub(config = {}, log = console) {
     socketPath: resolved.herdrSocketPath,
     sendRequest: resolved.herdrSendRequest
   });
-  const mcp = new McpStreamableHttpServer(
+  mcp = new McpStreamableHttpServer(
     hubTools(hub, registry, {
       defaultWaitMs: resolved.defaultWaitMs,
       waitTimeoutMs: resolved.waitTimeoutMs,
       herdr,
-      herdrControlPeers: resolved.herdrControlPeers === "all" || resolved.herdrControlPeers === void 0 ? "all" : new Set(resolved.herdrControlPeers)
+      herdrControlPeers: resolved.herdrControlPeers === "all" || resolved.herdrControlPeers === void 0 ? "all" : new Set(resolved.herdrControlPeers),
+      managerPeers: resolved.managerPeers === "all" ? "all" : new Set(resolved.managerPeers ?? DEFAULT_CONFIG.managerPeers)
     }),
     { name: SERVER_NAME, version: SERVER_VERSION },
     registry,
     (message) => log.warn(message),
-    (sessionId, clientName) => {
+    (sessionId, clientName, clientVersion) => {
       try {
-        const peer = autoRegisterPeer(hub, registry, sessionId, clientName);
+        const peer = autoRegisterPeer(hub, registry, sessionId, clientName, clientVersion);
         if (peer !== void 0) log.info(`peer joined: ${peer}`);
       } catch (error) {
         log.warn(`auto-register failed: ${error.message}`);
@@ -1419,6 +1786,11 @@ function startHub(config = {}, log = console) {
     close: () => {
       hub.dispose();
       mcp.close();
+      if (saveTimer !== void 0) {
+        clearTimeout(saveTimer);
+        saveTimer = void 0;
+      }
+      flushRoster();
       server.closeAllConnections?.();
       server.close();
     }
@@ -1444,6 +1816,7 @@ export {
   encodeContent,
   hubTools,
   present,
+  sanitizeAlias,
   sanitizePeerId,
   startHub
 };