@unagents/messenger-broker 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -22,6 +22,11 @@ interface BrokerOptions {
     discoveryPort?: number;
     /** UDP bind address when pinned (`AGENT_MESSENGER_DISCOVERY_ADDR`, default `""` = all interfaces). */
     discoveryAddr?: string;
+    /**
+     * Explicit discovery send targets, `host:port` each (`AGENT_MESSENGER_DISCOVERY_TARGETS`, comma separated).
+     * When non-empty, probes and announces go to these instead of broadcast (tests; LAN without broadcast).
+     */
+    discoveryTargets?: string[];
     /**
      * Run as a local fallback broker (`AGENT_MESSENGER_FALLBACK=1`, set by the client when it spawns one).
      * A fallback probes for other brokers every `fallbackIntervalMs`; when it finds one it relays its
@@ -38,16 +43,16 @@ interface BrokerOptions {
      */
     mesh?: boolean;
     /**
-     * Mesh members to sync with. Empty (default) = the `brokers` list of the client
-     * config file (`AGENT_MESSENGER_CONFIG`, default `~/.agent-messenger/config.json`), re-read every round.
+     * Test-only: a fixed list of mesh members that replaces discovery. Empty (default) = members are
+     * found by UDP discovery (announce / probe reply, token-checked). Not documented for users.
      */
     meshBrokers?: string[];
+    /** Mesh announce interval in ms (`AGENT_MESSENGER_MESH_ANNOUNCE_MS`, default 10000). */
+    meshAnnounceMs?: number;
     /** Mesh sync interval in ms (`AGENT_MESSENGER_MESH_INTERVAL_MS`, default 5000). */
     meshIntervalMs?: number;
     /** Replicated peers disappear this long after their origin stopped syncing (`AGENT_MESSENGER_MESH_PEER_TTL_MS`, default 300000). */
     meshPeerTtlMs?: number;
-    /** Client config file read for the mesh member list (`AGENT_MESSENGER_CONFIG`). */
-    configFile?: string;
 }
 type BrokerConfig = Required<Omit<BrokerOptions, "onSupersede">> & Pick<BrokerOptions, "onSupersede">;
 /** Marks a broker as a local fallback. Broker-private (not in the protocol ENV table, which mirrors legacy). */

package/dist/index.d.ts

@@ -22,6 +22,11 @@ interface BrokerOptions {
     discoveryPort?: number;
     /** UDP bind address when pinned (`AGENT_MESSENGER_DISCOVERY_ADDR`, default `""` = all interfaces). */
     discoveryAddr?: string;
+    /**
+     * Explicit discovery send targets, `host:port` each (`AGENT_MESSENGER_DISCOVERY_TARGETS`, comma separated).
+     * When non-empty, probes and announces go to these instead of broadcast (tests; LAN without broadcast).
+     */
+    discoveryTargets?: string[];
     /**
      * Run as a local fallback broker (`AGENT_MESSENGER_FALLBACK=1`, set by the client when it spawns one).
      * A fallback probes for other brokers every `fallbackIntervalMs`; when it finds one it relays its
@@ -38,16 +43,16 @@ interface BrokerOptions {
      */
     mesh?: boolean;
     /**
-     * Mesh members to sync with. Empty (default) = the `brokers` list of the client
-     * config file (`AGENT_MESSENGER_CONFIG`, default `~/.agent-messenger/config.json`), re-read every round.
+     * Test-only: a fixed list of mesh members that replaces discovery. Empty (default) = members are
+     * found by UDP discovery (announce / probe reply, token-checked). Not documented for users.
      */
     meshBrokers?: string[];
+    /** Mesh announce interval in ms (`AGENT_MESSENGER_MESH_ANNOUNCE_MS`, default 10000). */
+    meshAnnounceMs?: number;
     /** Mesh sync interval in ms (`AGENT_MESSENGER_MESH_INTERVAL_MS`, default 5000). */
     meshIntervalMs?: number;
     /** Replicated peers disappear this long after their origin stopped syncing (`AGENT_MESSENGER_MESH_PEER_TTL_MS`, default 300000). */
     meshPeerTtlMs?: number;
-    /** Client config file read for the mesh member list (`AGENT_MESSENGER_CONFIG`). */
-    configFile?: string;
 }
 type BrokerConfig = Required<Omit<BrokerOptions, "onSupersede">> & Pick<BrokerOptions, "onSupersede">;
 /** Marks a broker as a local fallback. Broker-private (not in the protocol ENV table, which mirrors legacy). */

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import 'listhen';
 import 'h3';
 import '@unagents/messenger-protocol';
-export { D as DEFAULT_STATE_FILE, F as FALLBACK_ENV, a as FALLBACK_INTERVAL_ENV, M as MESH_ENV, S as STATE_DIR, V as VERSION, c as configFromEnv, r as resolveConfig, s as startBroker } from './shared/messenger-broker.B8W77sqB.mjs';
+export { D as DEFAULT_STATE_FILE, F as FALLBACK_ENV, a as FALLBACK_INTERVAL_ENV, M as MESH_ENV, S as STATE_DIR, V as VERSION, c as configFromEnv, r as resolveConfig, s as startBroker } from './shared/messenger-broker.Co46RRtX.mjs';
 import 'node:os';
 import 'node:path';
 import 'defu';

package/dist/main.mjs

@@ -1,4 +1,4 @@
-import { s as startBroker, l as log } from './shared/messenger-broker.B8W77sqB.mjs';
+import { s as startBroker, l as log } from './shared/messenger-broker.Co46RRtX.mjs';
 import 'listhen';
 import 'h3';
 import '@unagents/messenger-protocol';

package/dist/shared/{messenger-broker.B8W77sqB.mjs → messenger-broker.Co46RRtX.mjs}

@@ -1,12 +1,12 @@
 import { listen } from 'listhen';
 import { createRouter, defineEventHandler, createApp, send, setResponseStatus, getRequestHeader, readRawBody, toNodeListener } from 'h3';
-import { DEFAULT_BIND, ENV, DEFAULT_DISCOVERY_PORT, DEFAULT_HTTP_PORT, PROTOCOL_NAME_PATTERN, PROTOCOL_META_MAX_LENGTH, PROTOCOL_MANIFEST_MAX_BYTES, PROTOCOL_DOC_MAX_BYTES, PROTOCOL_TOTAL_MAX_BYTES, canonicalJSON, HEARTBEAT_TIMEOUT_MS, PROTOCOL_MAX_STORED, MESH_SYNC_ROUTE, HEALTH_ROUTE, BROKER_POST_ROUTES, PROTOCOL_ROUTES, RELAY_ROUTE, DISCOVERY_KEY, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE } from '@unagents/messenger-protocol';
+import { DEFAULT_BIND, MESH_ANNOUNCE_ENV, DISCOVERY_TARGETS_ENV, ENV, DEFAULT_DISCOVERY_PORT, DEFAULT_HTTP_PORT, PROTOCOL_NAME_PATTERN, PROTOCOL_META_MAX_LENGTH, PROTOCOL_MANIFEST_MAX_BYTES, PROTOCOL_DOC_MAX_BYTES, PROTOCOL_TOTAL_MAX_BYTES, canonicalJSON, HEARTBEAT_TIMEOUT_MS, PROTOCOL_MAX_STORED, MESH_SYNC_ROUTE, DISCOVERY_KEY, DISCOVERY_ANNOUNCE_VALUE, MESH_ANNOUNCE_MAX_SKEW_MS, DISCOVERY_REPLY_VALUE, meshMacEqual, meshMac, HEALTH_ROUTE, BROKER_POST_ROUTES, PROTOCOL_ROUTES, RELAY_ROUTE, DISCOVERY_PROBE_VALUE } from '@unagents/messenger-protocol';
 import { homedir, hostname, networkInterfaces } from 'node:os';
 import { join, dirname } from 'node:path';
 import { defu } from 'defu';
 import { readFileSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
 import { createConsola } from 'consola';
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { request } from 'node:http';
 import { createSocket } from 'node:dgram';
 
@@ -30,13 +30,14 @@ function configFromEnv(env = process.env) {
     discovery: (env[ENV.DISCOVERY] ?? "on").toLowerCase() !== "off",
     discoveryPort: parseInt(env[ENV.DISCOVERY_PORT] ?? String(DEFAULT_DISCOVERY_PORT), 10),
     discoveryAddr: env[ENV.DISCOVERY_ADDR] ?? "",
+    discoveryTargets: (env[DISCOVERY_TARGETS_ENV] ?? "").split(",").map((s) => s.trim()).filter(Boolean),
     fallback: ["1", "true", "on", "yes"].includes((env[FALLBACK_ENV] ?? "").toLowerCase()),
     fallbackIntervalMs: parseInt(env[FALLBACK_INTERVAL_ENV] ?? String(DEFAULT_FALLBACK_INTERVAL_MS), 10),
     mesh: (env[MESH_ENV.MESH] ?? "off").toLowerCase() === "on",
     meshBrokers: [],
+    meshAnnounceMs: parseInt(env[MESH_ANNOUNCE_ENV] ?? "10000", 10),
     meshIntervalMs: parseInt(env[MESH_ENV.INTERVAL_MS] ?? "5000", 10),
-    meshPeerTtlMs: parseInt(env[MESH_ENV.PEER_TTL_MS] ?? "300000", 10),
-    configFile: env[ENV.CONFIG] ?? join(STATE_DIR, "config.json")
+    meshPeerTtlMs: parseInt(env[MESH_ENV.PEER_TTL_MS] ?? "300000", 10)
   };
 }
 function resolveConfig(options = {}) {
@@ -780,6 +781,15 @@ class Mesh {
     if (this.timer) clearInterval(this.timer);
     this.timer = null;
   }
+  /** True while the last sync with `url` succeeded. */
+  linkUp(url) {
+    return this.links.get(url) === "up";
+  }
+  /** Forget everything learned about `url` (its broker left or moved). */
+  forget(url) {
+    this.links.delete(url);
+    this.origins.delete(url);
+  }
   /** Sync soon (coalesced). */
   kick() {
     if (this.running) this.again = true;
@@ -843,24 +853,6 @@ class Mesh {
     this.setLink(url, "up");
   }
 }
-function readMeshBrokers(configFile) {
-  try {
-    const parsed = JSON.parse(readFileSync(configFile, "utf8"));
-    const list = Array.isArray(parsed.brokers) ? parsed.brokers : parsed.broker ? [parsed.broker] : [];
-    const out = [];
-    for (const s of list) {
-      if (typeof s !== "string" || !s.trim()) continue;
-      try {
-        out.push(normalizeBrokerUrl(s));
-      } catch {
-        log.warn(`mesh: ignoring unparsable broker entry "${s}"`);
-      }
-    }
-    return out;
-  } catch {
-    return [];
-  }
-}
 function normalizeBrokerUrl(s) {
   s = s.trim();
   if (!/^https?:\/\//.test(s)) s = `http://${s}`;
@@ -882,6 +874,81 @@ function postJson(url, headers, body, timeoutMs) {
   });
 }
 
+function meshExpireMs(announceMs) {
+  return announceMs * 3 + 5e3;
+}
+class MeshPeerTable {
+  constructor(opts) {
+    this.opts = opts;
+    this.now = opts.now ?? Date.now;
+  }
+  byId = /* @__PURE__ */ new Map();
+  mismatchLogged = /* @__PURE__ */ new Set();
+  now;
+  /** Current sync targets. */
+  urls() {
+    return [...this.byId.values()].map((e) => e.url);
+  }
+  entries() {
+    return [...this.byId.values()];
+  }
+  /** `announce` packet from `address` (UDP source). Returns true when accepted. */
+  handleAnnounce(m, address) {
+    if (m[DISCOVERY_KEY] !== DISCOVERY_ANNOUNCE_VALUE || m.mesh !== true) return false;
+    const ts = m.ts;
+    if (typeof ts !== "number" || !Number.isFinite(ts) || Math.abs(this.now() - ts) > MESH_ANNOUNCE_MAX_SKEW_MS) return false;
+    return this.accept(m, address, String(ts));
+  }
+  /** `broker` reply to our probe that carried `nonce`. Returns true when accepted. */
+  handleReply(m, address, nonce) {
+    if (m[DISCOVERY_KEY] !== DISCOVERY_REPLY_VALUE || m.mesh !== true) return false;
+    return this.accept(m, address, nonce);
+  }
+  accept(m, address, nonce) {
+    const { id, port, version, mac } = m;
+    if (typeof id !== "string" || !id || typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535) return false;
+    if (typeof mac !== "string") return false;
+    if (!meshMacEqual(meshMac(this.opts.token, nonce, id, port), mac)) {
+      const key = `${id}@${address}`;
+      if (!this.mismatchLogged.has(key)) {
+        this.mismatchLogged.add(key);
+        log.warn(`mesh: ignoring ${id}@${address} (token mismatch)`);
+      }
+      return false;
+    }
+    if (id === this.opts.selfId) return false;
+    const url = `http://${address}:${port}`;
+    const prev = this.byId.get(id);
+    const entry = { id, url, version: typeof version === "string" ? version : "", lastSeen: this.now() };
+    this.byId.set(id, entry);
+    if (!prev) {
+      log.info(`mesh: found ${id} at ${url}`);
+      this.opts.onJoin?.(entry);
+    } else if (prev.url !== url) {
+      log.info(`mesh: ${id} moved ${prev.url} -> ${url}`);
+      this.opts.onDrop?.(prev.url);
+      this.opts.onJoin?.(entry);
+    }
+    return true;
+  }
+  /**
+   * Drop entries not vouched for within `expireMs` whose last sync did not succeed (`linkUp`): a link that
+   * still syncs stays even when UDP is lost. Returns the removed entries.
+   */
+  sweep(linkUp) {
+    const gone = [];
+    const t = this.now();
+    for (const e of this.byId.values()) {
+      if (t - e.lastSeen <= this.opts.expireMs || linkUp(e.url)) continue;
+      this.byId.delete(e.id);
+      gone.push(e);
+      log.info(`mesh: ${e.url} left`);
+      this.opts.onDrop?.(e.url);
+    }
+    return gone;
+  }
+}
+
 function createBrokerApp(opts) {
   const routes = opts.handlers.routes();
   const protocolRoutes = opts.handlers.protocolRoutes();
@@ -892,7 +959,8 @@ function createBrokerApp(opts) {
     id: opts.id,
     port: opts.port(),
     peers: opts.handlers.alivePeerCount(),
-    ...opts.fallback ? { fallback: true } : {}
+    ...opts.fallback ? { fallback: true } : {},
+    ...opts.mesh ? { mesh: true } : {}
   })));
   const post = (route, run) => router.post(route, defineEventHandler(async (event) => {
     if (!authorized(event, opts.token)) return unauthorized(event);
@@ -936,12 +1004,16 @@ function startDiscoveryResponder(opts) {
   const disco = createSocket({ type: "udp4", reuseAddr: true });
   disco.on("error", (e) => log.warn(`discovery responder error: ${e.message}`));
   disco.on("message", (msg, rinfo) => {
+    let m;
     try {
-      if (JSON.parse(msg.toString())[DISCOVERY_KEY] !== DISCOVERY_PROBE_VALUE) return;
+      m = JSON.parse(msg.toString());
     } catch {
       return;
     }
-    const reply = Buffer.from(JSON.stringify(opts.reply()));
+    if (m[DISCOVERY_KEY] === DISCOVERY_ANNOUNCE_VALUE) return opts.onAnnounce?.(m, rinfo);
+    if (m[DISCOVERY_KEY] !== DISCOVERY_PROBE_VALUE) return;
+    const nonce = typeof m.n === "string" && m.n.length > 0 && m.n.length <= 128 ? m.n : void 0;
+    const reply = Buffer.from(JSON.stringify(opts.reply(nonce)));
     disco.send(reply, rinfo.port, rinfo.address, () => {
     });
   });
@@ -958,6 +1030,48 @@ function startDiscoveryResponder(opts) {
     });
   });
 }
+function parseDiscoveryTargets(list) {
+  const out = [];
+  for (const s of list) {
+    const i = s.lastIndexOf(":");
+    const port = Number(s.slice(i + 1));
+    if (i <= 0 || !Number.isInteger(port) || port < 1 || port > 65535) {
+      log.warn(`discovery: ignoring invalid target "${s}" (want host:port)`);
+      continue;
+    }
+    out.push({ host: s.slice(0, i), port });
+  }
+  return out;
+}
+function sendTargets(opts) {
+  const explicit = parseDiscoveryTargets(opts.targets ?? []);
+  if (explicit.length) return explicit;
+  return probeTargets(opts.addr).map((host) => ({ host, port: opts.port }));
+}
+function buildAnnounce(a) {
+  return {
+    [DISCOVERY_KEY]: DISCOVERY_ANNOUNCE_VALUE,
+    id: a.id,
+    port: a.port,
+    version: a.version,
+    mesh: true,
+    ts: a.ts,
+    mac: meshMac(a.token, String(a.ts), a.id, a.port)
+  };
+}
+function sendAnnounce(sock, packet, targets) {
+  const buf = Buffer.from(JSON.stringify(packet));
+  for (const t of targets) {
+    try {
+      sock.send(buf, t.port, t.host, () => {
+      });
+    } catch {
+    }
+  }
+}
+function newNonce() {
+  return randomBytes(16).toString("hex");
+}
 function probeTargets(addr) {
   if (addr) return [addr];
   const targets = /* @__PURE__ */ new Set(["255.255.255.255"]);
@@ -1001,7 +1115,16 @@ function probeBrokers(opts) {
         if (m[DISCOVERY_KEY] !== DISCOVERY_REPLY_VALUE || !m.port) return;
         const url = `http://${rinfo.address}:${m.port}`;
         if (!found.has(url)) {
-          found.set(url, { url, host: rinfo.address, port: m.port, id: m.id ?? rinfo.address, version: m.version ?? "", fallback: m.fallback === true });
+          found.set(url, {
+            url,
+            host: rinfo.address,
+            port: m.port,
+            id: m.id ?? rinfo.address,
+            version: m.version ?? "",
+            fallback: m.fallback === true,
+            mesh: m.mesh === true,
+            ...typeof m.mac === "string" ? { mac: m.mac } : {}
+          });
         }
       } catch {
       }
@@ -1011,8 +1134,8 @@ function probeBrokers(opts) {
         sock.setBroadcast(true);
       } catch {
       }
-      const probe = Buffer.from(JSON.stringify({ [DISCOVERY_KEY]: DISCOVERY_PROBE_VALUE }));
-      for (const t of probeTargets(opts.addr)) sock.send(probe, opts.port, t, () => {
+      const probe = Buffer.from(JSON.stringify({ [DISCOVERY_KEY]: DISCOVERY_PROBE_VALUE, ...opts.nonce ? { n: opts.nonce } : {} }));
+      for (const t of sendTargets(opts)) sock.send(probe, t.port, t.host, () => {
       });
     });
   });
@@ -1068,7 +1191,7 @@ async function relayUndelivered(state, url, token) {
   return { sent, dropped };
 }
 
-const version = "0.10.0";
+const version = "0.11.0";
 const pkg = {
 	version: version};
 
@@ -1114,21 +1237,61 @@ async function startBroker(options = {}) {
     throw e;
   }
   port = listener.address.port;
-  const reply = () => ({ [DISCOVERY_KEY]: DISCOVERY_REPLY_VALUE, id: cfg.id, port, version: VERSION, ...cfg.fallback ? { fallback: true } : {} });
+  const reply = (nonce) => ({
+    [DISCOVERY_KEY]: DISCOVERY_REPLY_VALUE,
+    id: cfg.id,
+    port,
+    version: VERSION,
+    ...cfg.fallback ? { fallback: true } : {},
+    ...cfg.mesh ? { mesh: true, ...nonce ? { mac: meshMac(cfg.token, nonce, cfg.id, port) } : {} } : {}
+  });
+  const fixed = cfg.meshBrokers.map(normalizeBrokerUrl);
+  const peerTable = cfg.mesh ? new MeshPeerTable({
+    selfId: cfg.id,
+    token: cfg.token,
+    expireMs: meshExpireMs(cfg.meshAnnounceMs),
+    onDrop: (url) => mesh?.forget(url),
+    onJoin: () => mesh?.kick()
+  }) : null;
   let disco = null;
   if (cfg.discovery) {
-    disco = await startDiscoveryResponder({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, reply });
+    disco = await startDiscoveryResponder({
+      port: cfg.discoveryPort,
+      addr: cfg.discoveryAddr,
+      reply,
+      ...peerTable ? { onAnnounce: (m, rinfo) => void peerTable.handleAnnounce(m, rinfo.address) } : {}
+    });
   }
+  let announceTimer = null;
   if (cfg.mesh) {
-    const fixed = cfg.meshBrokers.map(normalizeBrokerUrl);
     mesh = new Mesh({
       id: cfg.id,
       token: cfg.token,
       handlers,
-      urls: () => fixed.length ? fixed : readMeshBrokers(cfg.configFile),
+      urls: () => fixed.length ? fixed : peerTable.urls(),
       intervalMs: cfg.meshIntervalMs
     });
     mesh.start();
+    if (!cfg.discovery && !fixed.length) {
+      log.warn("mesh: AGENT_MESSENGER_MESH=on but AGENT_MESSENGER_DISCOVERY=off; no other mesh broker can be found");
+    }
+    if (cfg.discovery && disco && !fixed.length) {
+      const sock = disco;
+      const targets = sendTargets({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, targets: cfg.discoveryTargets });
+      const announceAndSweep = () => {
+        sendAnnounce(sock, buildAnnounce({ token: cfg.token, id: cfg.id, port, version: VERSION, ts: Date.now() }), targets);
+        peerTable.sweep((url) => mesh?.linkUp(url) ?? false);
+      };
+      announceAndSweep();
+      announceTimer = setInterval(announceAndSweep, cfg.meshAnnounceMs);
+      announceTimer.unref();
+      const nonce = newNonce();
+      void probeBrokers({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, targets: cfg.discoveryTargets, nonce, timeoutMs: 1e3 }).then((found) => {
+        for (const b of found) {
+          peerTable.handleReply({ [DISCOVERY_KEY]: DISCOVERY_REPLY_VALUE, id: b.id, port: b.port, version: b.version, mesh: b.mesh, mac: b.mac }, b.host, nonce);
+        }
+      });
+    }
   }
   log.info(`v${VERSION} id=${cfg.id} listening on ${cfg.bind}:${port} (state: ${cfg.stateFile})`);
   if (cfg.fallback) log.info(`FALLBACK mode: looking for another broker every ${cfg.fallbackIntervalMs} ms (discovery ${cfg.discovery ? "on" : "off"})`);
@@ -1140,6 +1303,7 @@ async function startBroker(options = {}) {
     closed = true;
     clearInterval(cleaner);
     if (fallbackTimer) clearInterval(fallbackTimer);
+    if (announceTimer) clearInterval(announceTimer);
     mesh?.stop();
     if (disco) {
       await new Promise((resolve) => disco.close(() => resolve()));
@@ -1154,7 +1318,7 @@ async function startBroker(options = {}) {
       if (busy || closed) return;
       busy = true;
       try {
-        const found = await probeBrokers({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, timeoutMs: 1e3 });
+        const found = await probeBrokers({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, targets: cfg.discoveryTargets, timeoutMs: 1e3 });
         const other = found.find((b) => !b.fallback && !(b.port === port && mine.has(b.host)));
         if (!other || closed) return;
         log.info(`fallback: found broker ${other.id} at ${other.url} \u2014 relaying messages and exiting`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unagents/messenger-broker",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "agent-messenger broker: HTTP daemon that tracks peers and routes messages between Claude Code sessions.",
   "type": "module",
   "license": "MIT",
@@ -28,7 +28,7 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@unagents/messenger-protocol": "0.10.0",
+    "@unagents/messenger-protocol": "0.11.0",
     "consola": "^3.4.2",
     "defu": "^6.1.7",
     "h3": "^1.15.11",