bantou 0.1.0 → 0.2.0

package/.output/server/node_modules/@unagents/messenger-broker/dist/shared/messenger-broker.B8W77sqB.mjs

@@ -0,0 +1,1177 @@
+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 { 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 { request } from 'node:http';
+import { createSocket } from 'node:dgram';
+
+const FALLBACK_ENV = "AGENT_MESSENGER_FALLBACK";
+const FALLBACK_INTERVAL_ENV = "AGENT_MESSENGER_FALLBACK_INTERVAL_MS";
+const DEFAULT_FALLBACK_INTERVAL_MS = 1e4;
+const STATE_DIR = join(homedir(), ".agent-messenger");
+const DEFAULT_STATE_FILE = join(STATE_DIR, "broker.json");
+const MESH_ENV = {
+  MESH: "AGENT_MESSENGER_MESH",
+  INTERVAL_MS: "AGENT_MESSENGER_MESH_INTERVAL_MS",
+  PEER_TTL_MS: "AGENT_MESSENGER_MESH_PEER_TTL_MS"
+};
+function configFromEnv(env = process.env) {
+  return {
+    port: parseInt(env[ENV.PORT] ?? String(DEFAULT_HTTP_PORT), 10),
+    bind: env[ENV.BIND] ?? DEFAULT_BIND,
+    token: env[ENV.TOKEN] ?? "",
+    id: env[ENV.BROKER_ID] ?? hostname(),
+    stateFile: env[ENV.STATE] ?? DEFAULT_STATE_FILE,
+    discovery: (env[ENV.DISCOVERY] ?? "on").toLowerCase() !== "off",
+    discoveryPort: parseInt(env[ENV.DISCOVERY_PORT] ?? String(DEFAULT_DISCOVERY_PORT), 10),
+    discoveryAddr: env[ENV.DISCOVERY_ADDR] ?? "",
+    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: [],
+    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")
+  };
+}
+function resolveConfig(options = {}) {
+  return defu(options, configFromEnv());
+}
+
+const log = createConsola({ stdout: process.stderr, stderr: process.stderr }).withTag(
+  "agent-messenger broker"
+);
+
+class BrokerState {
+  constructor(file) {
+    this.file = file;
+  }
+  peers = /* @__PURE__ */ new Map();
+  messages = [];
+  nextMsgId = 1;
+  pending = [];
+  /** Protocol definitions by `"name@version"`. Kept while at least one alive peer declares them (see `BrokerHandlers.gcProtocols`). */
+  protocols = /* @__PURE__ */ new Map();
+  /** Mesh: when each origin broker last synced with us (ms epoch, memory only). Replicated peers live as long as this is fresh. */
+  originSeen = /* @__PURE__ */ new Map();
+  saveTimer = null;
+  /** Read the snapshot if present. A missing or unreadable file starts empty. */
+  load() {
+    try {
+      const raw = JSON.parse(readFileSync(this.file, "utf8"));
+      for (const p of raw.peers ?? []) {
+        this.peers.set(p.id, p);
+        if (p.origin) this.originSeen.set(p.origin, Date.now());
+      }
+      this.messages = raw.messages ?? [];
+      this.nextMsgId = raw.nextMsgId ?? 1;
+      this.pending = raw.pending ?? [];
+      for (const sp of raw.protocols ?? []) {
+        if (sp && typeof sp.name === "string" && typeof sp.version === "string") this.protocols.set(`${sp.name}@${sp.version}`, sp);
+      }
+      log.info(
+        `Loaded state from ${this.file} (${this.peers.size} peer(s), ${this.messages.length} message(s)${this.protocols.size ? `, ${this.protocols.size} protocol(s)` : ""})`
+      );
+    } catch {
+    }
+  }
+  /** Snapshot to disk after 200 ms; repeated calls inside the window coalesce. */
+  scheduleSave() {
+    if (this.saveTimer) return;
+    this.saveTimer = setTimeout(() => {
+      this.saveTimer = null;
+      this.saveNow();
+    }, 200);
+  }
+  /** Write the snapshot immediately (also cancels a pending debounced save). */
+  saveNow() {
+    if (this.saveTimer) {
+      clearTimeout(this.saveTimer);
+      this.saveTimer = null;
+    }
+    try {
+      mkdirSync(dirname(this.file), { recursive: true });
+      const tmp = `${this.file}.tmp`;
+      const snapshot = {
+        peers: [...this.peers.values()],
+        messages: this.messages,
+        nextMsgId: this.nextMsgId,
+        ...this.pending.length ? { pending: this.pending } : {},
+        ...this.protocols.size ? { protocols: [...this.protocols.values()] } : {}
+      };
+      writeFileSync(tmp, JSON.stringify(snapshot, null, 1));
+      renameSync(tmp, this.file);
+    } catch (e) {
+      log.warn(`Save failed: ${e.message}`);
+    }
+  }
+  /** True when a debounced save is still pending. */
+  get savePending() {
+    return this.saveTimer !== null;
+  }
+}
+
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+const MAX_FIELD_LENGTH = 1024;
+function protocolHash(manifest, doc) {
+  return createHash("sha256").update(canonicalJSON({ manifest, doc })).digest("hex");
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function checkDefinition(name, version, def) {
+  const bad = (error) => ({ ok: false, code: "INVALID_DEFINITION", error });
+  if (typeof name !== "string" || !PROTOCOL_NAME_PATTERN.test(name)) {
+    return bad(`invalid protocol name (expected ${String(PROTOCOL_NAME_PATTERN)})`);
+  }
+  if (typeof version !== "string" || version.length > MAX_FIELD_LENGTH || !VERSION_PATTERN.test(version)) {
+    return bad("invalid version (expected semver, e.g. 1.2.0 or 0.0.0+abc1234)");
+  }
+  if (!isPlainObject(def)) return bad("missing definition");
+  const { manifest, doc, source, ref } = def;
+  if (!isPlainObject(manifest)) return bad("definition.manifest must be an object");
+  if (typeof doc !== "string") return bad("definition.doc must be a string");
+  if (typeof source !== "string" || !source || source.length > MAX_FIELD_LENGTH) return bad("definition.source must be a non-empty string");
+  if (typeof ref !== "string" || !ref || ref.length > MAX_FIELD_LENGTH) return bad("definition.ref must be a non-empty string");
+  if (manifest.name !== name) return bad(`protocol.json "name" must equal "${name}"`);
+  if (manifest.description !== void 0 && typeof manifest.description !== "string") return bad('protocol.json "description" must be a string');
+  if (manifest.messages !== void 0) {
+    if (!isPlainObject(manifest.messages)) return bad('protocol.json "messages" must be an object');
+    for (const [k, schema] of Object.entries(manifest.messages)) {
+      if (!isPlainObject(schema)) return bad(`protocol.json messages.${k} must be an object (JSON Schema)`);
+    }
+  }
+  const manifestBytes = Buffer.byteLength(JSON.stringify(manifest));
+  const docBytes = Buffer.byteLength(doc);
+  if (manifestBytes > PROTOCOL_MANIFEST_MAX_BYTES) {
+    return { ok: false, code: "TOO_LARGE", error: `protocol.json is ${manifestBytes} bytes (limit ${PROTOCOL_MANIFEST_MAX_BYTES})` };
+  }
+  if (docBytes > PROTOCOL_DOC_MAX_BYTES) {
+    return { ok: false, code: "TOO_LARGE", error: `PROTOCOL.md is ${docBytes} bytes (limit ${PROTOCOL_DOC_MAX_BYTES})` };
+  }
+  if (manifestBytes + docBytes > PROTOCOL_TOTAL_MAX_BYTES) {
+    return { ok: false, code: "TOO_LARGE", error: `definition is ${manifestBytes + docBytes} bytes (limit ${PROTOCOL_TOTAL_MAX_BYTES})` };
+  }
+  return { ok: true };
+}
+function sanitizeDecls(list) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const d of list) {
+    if (!isPlainObject(d)) continue;
+    const { name, version, hash } = d;
+    if (typeof name !== "string" || !PROTOCOL_NAME_PATTERN.test(name)) continue;
+    if (typeof version !== "string" || version.length > MAX_FIELD_LENGTH || !VERSION_PATTERN.test(version)) continue;
+    if (typeof hash !== "string" || !HASH_PATTERN.test(hash)) continue;
+    if (out.some((o) => o.name === name)) continue;
+    out.push({ name, version, hash });
+  }
+  return out;
+}
+function checkMeta(meta) {
+  if (!isPlainObject(meta)) return null;
+  const { protocol, version } = meta;
+  if (typeof protocol !== "string" || typeof version !== "string") return null;
+  if (protocol.length > PROTOCOL_META_MAX_LENGTH || version.length > PROTOCOL_META_MAX_LENGTH) return null;
+  return { protocol, version };
+}
+function isTagless(v) {
+  return v.startsWith("0.0.0+");
+}
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/;
+function compareVersions(a, b) {
+  const ta = isTagless(a);
+  const tb = isTagless(b);
+  if (ta || tb) return ta && tb ? 0 : ta ? -1 : 1;
+  const ma = SEMVER.exec(a);
+  const mb = SEMVER.exec(b);
+  if (!ma || !mb) return a < b ? -1 : a > b ? 1 : 0;
+  for (let i = 1; i <= 3; i++) {
+    const x = BigInt(ma[i]);
+    const y = BigInt(mb[i]);
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  const pa = ma[4];
+  const pb = mb[4];
+  if (pa === void 0 && pb === void 0) return 0;
+  if (pa === void 0) return 1;
+  if (pb === void 0) return -1;
+  const ia = pa.split(".");
+  const ib = pb.split(".");
+  for (let i = 0; i < Math.min(ia.length, ib.length); i++) {
+    const x = ia[i];
+    const y = ib[i];
+    const nx = /^\d+$/.test(x);
+    const ny = /^\d+$/.test(y);
+    if (nx && ny) {
+      const dx = BigInt(x);
+      const dy = BigInt(y);
+      if (dx !== dy) return dx < dy ? -1 : 1;
+    } else if (nx !== ny) {
+      return nx ? -1 : 1;
+    } else if (x !== y) {
+      return x < y ? -1 : 1;
+    }
+  }
+  return ia.length === ib.length ? 0 : ia.length < ib.length ? -1 : 1;
+}
+
+const PENDING_RELAY_TTL_MS = 60 * 60 * 1e3;
+const DEFAULT_MESH_PEER_TTL_MS = 3e5;
+const MESH_KEY_MEMORY = 2e3;
+class BrokerHandlers {
+  constructor(state, opts = {}) {
+    this.state = state;
+    this.opts = opts;
+  }
+  recentMeshKeys = /* @__PURE__ */ new Set();
+  /** Mesh protocol conflicts already logged (`name@version:hash`), so a standing conflict warns once, not every round. */
+  warnedProtocolConflicts = /* @__PURE__ */ new Set();
+  // --- peer bookkeeping ---
+  /** Cutoff `last_seen` (ISO) below which a peer counts as stale. */
+  static cutoff() {
+    return new Date(Date.now() - HEARTBEAT_TIMEOUT_MS).toISOString();
+  }
+  /**
+   * Direct peers: `last_seen` within the heartbeat timeout. Replicated peers
+   * (mesh): their origin broker synced within `meshPeerTtlMs`; `last_seen` is
+   * the origin's clock and is not compared.
+   */
+  isAlive(p, cutoff) {
+    if (p.origin) {
+      const seen = this.state.originSeen.get(p.origin) ?? 0;
+      return Date.now() - seen < (this.opts.meshPeerTtlMs ?? DEFAULT_MESH_PEER_TTL_MS);
+    }
+    return p.last_seen >= cutoff;
+  }
+  /** Number of peers seen within `HEARTBEAT_TIMEOUT_MS` (for `/health`). */
+  alivePeerCount() {
+    const cutoff = BrokerHandlers.cutoff();
+    return [...this.state.peers.values()].filter((p) => this.isAlive(p, cutoff)).length;
+  }
+  cleanStalePeers() {
+    const cutoff = BrokerHandlers.cutoff();
+    let removed = 0;
+    for (const p of [...this.state.peers.values()]) {
+      if (!this.isAlive(p, cutoff)) {
+        this.removePeer(p.id);
+        removed++;
+      }
+    }
+    if (removed) {
+      log.info(`Cleaned ${removed} stale peer(s)`);
+      this.state.scheduleSave();
+    }
+    const expiry = new Date(Date.now() - PENDING_RELAY_TTL_MS).toISOString();
+    const kept = this.state.pending.filter((r) => r.queued_at >= expiry);
+    if (kept.length !== this.state.pending.length) {
+      log.info(`Dropped ${this.state.pending.length - kept.length} expired relayed message(s)`);
+      this.state.pending = kept;
+      this.state.scheduleSave();
+    }
+    this.gcProtocols();
+  }
+  // --- protocol store ---
+  /** Alive peers (replicas included) that declare `name@version`. */
+  serversOf(name, version) {
+    const cutoff = BrokerHandlers.cutoff();
+    return [...this.state.peers.values()].filter(
+      (p) => this.isAlive(p, cutoff) && p.protocols?.some((d) => d.name === name && d.version === version)
+    );
+  }
+  /**
+   * Drop stored definitions that no alive peer (replicas included) declares by `(name, version)` any more.
+   * Runs after `cleanStalePeers`, `register`, `unregister`, `/set-protocol`, `/unset-protocol`, `meshApplyPeers`
+   * and before `/get-protocol` answers.
+   */
+  gcProtocols() {
+    if (this.state.protocols.size === 0) return;
+    const cutoff = BrokerHandlers.cutoff();
+    const live = /* @__PURE__ */ new Set();
+    for (const p of this.state.peers.values()) {
+      if (!this.isAlive(p, cutoff)) continue;
+      for (const d of p.protocols ?? []) live.add(`${d.name}@${d.version}`);
+    }
+    let removed = 0;
+    for (const key of [...this.state.protocols.keys()]) {
+      if (!live.has(key)) {
+        this.state.protocols.delete(key);
+        removed++;
+      }
+    }
+    if (removed) {
+      log.info(`Dropped ${removed} protocol definition(s) without a declaring peer`);
+      this.state.scheduleSave();
+    }
+  }
+  /**
+   * Record `decls` on `peer` (hash only). A name the peer already declares is left alone (only `/set-protocol`
+   * changes a declaration, so a heartbeat that raced a change cannot undo it), and so is a declaration whose hash
+   * differs from the definition stored for the same `(name, version)`.
+   */
+  mergeDecls(peer, decls) {
+    let changed = false;
+    for (const d of decls) {
+      if (peer.protocols?.some((x) => x.name === d.name)) continue;
+      const stored = this.state.protocols.get(`${d.name}@${d.version}`);
+      if (stored && stored.hash !== d.hash) continue;
+      peer.protocols = [...peer.protocols ?? [], d];
+      changed = true;
+    }
+    return changed;
+  }
+  /** A peer that registered here (not a mesh replica). Only those can heartbeat / rename. */
+  localPeer(id) {
+    const p = this.state.peers.get(id);
+    return p && !p.origin ? p : void 0;
+  }
+  removePeer(id) {
+    this.state.peers.delete(id);
+    this.state.messages = this.state.messages.filter((m) => !(m.to_id === id && m.delivered === 0));
+  }
+  /** Resolve a peer by id or unique name. */
+  resolvePeer(to) {
+    const byId = this.state.peers.get(to);
+    if (byId) return { peer: byId };
+    const byName = [...this.state.peers.values()].filter((p) => p.name && p.name === to);
+    if (byName.length === 1) return { peer: byName[0] };
+    if (byName.length > 1) {
+      return {
+        error: `Name "${to}" is ambiguous: ${byName.map((p) => `${p.id}@${p.hostname}`).join(", ")}`
+      };
+    }
+    return { error: `Peer "${to}" not found (no id or name matches)` };
+  }
+  static generateId() {
+    const chars = "abcdefghijklmnopqrstuvwxyz0123456789";
+    let id = "";
+    for (let i = 0; i < 8; i++) id += chars[Math.floor(Math.random() * chars.length)];
+    return id;
+  }
+  // --- routes ---
+  register(body) {
+    for (const p of [...this.state.peers.values()]) {
+      if (p.pid === body.pid && p.hostname === body.hostname) this.removePeer(p.id);
+    }
+    const id = BrokerHandlers.generateId();
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.state.peers.set(id, {
+      id,
+      name: body.name ?? "",
+      pid: body.pid,
+      hostname: body.hostname ?? "",
+      cwd: body.cwd ?? "",
+      git_root: body.git_root ?? null,
+      tty: body.tty ?? null,
+      summary: body.summary ?? "",
+      registered_at: now,
+      last_seen: now
+    });
+    const peer = this.state.peers.get(id);
+    if (body.protocols !== void 0) this.mergeDecls(peer, sanitizeDecls(body.protocols));
+    this.deliverPending(peer);
+    this.gcProtocols();
+    this.state.scheduleSave();
+    return { id };
+  }
+  heartbeat(body) {
+    const p = this.localPeer(body.id);
+    if (!p) return { ok: false, error: "unknown peer (re-register)" };
+    p.last_seen = (/* @__PURE__ */ new Date()).toISOString();
+    if (body.protocols !== void 0) this.mergeDecls(p, sanitizeDecls(body.protocols));
+    this.state.scheduleSave();
+    const resend = (p.protocols ?? []).filter((d) => !this.state.protocols.has(`${d.name}@${d.version}`)).map((d) => `${d.name}@${d.version}`);
+    return resend.length ? { ok: true, resend } : { ok: true };
+  }
+  setSummary(body) {
+    const p = this.localPeer(body.id);
+    if (!p) return { ok: false, error: "unknown peer" };
+    p.summary = body.summary ?? "";
+    this.state.scheduleSave();
+    return { ok: true };
+  }
+  setName(body) {
+    const p = this.localPeer(body.id);
+    if (!p) return { ok: false, error: "unknown peer" };
+    p.name = body.name ?? "";
+    this.deliverPending(p);
+    this.state.scheduleSave();
+    return { ok: true };
+  }
+  listPeers(body) {
+    const cutoff = BrokerHandlers.cutoff();
+    let list = [...this.state.peers.values()].filter((p) => this.isAlive(p, cutoff));
+    switch (body.scope) {
+      case "host":
+        if (body.hostname) list = list.filter((p) => p.hostname === body.hostname);
+        break;
+      case "directory":
+        list = list.filter((p) => p.cwd === body.cwd);
+        break;
+      case "repo":
+        list = body.git_root ? list.filter((p) => p.git_root === body.git_root) : list.filter((p) => p.cwd === body.cwd);
+        break;
+    }
+    if (body.exclude_id) list = list.filter((p) => p.id !== body.exclude_id);
+    if (body.protocol) {
+      const { protocol, version } = body;
+      list = list.filter((p) => p.protocols?.some((d) => d.name === protocol && (!version || d.version === version)));
+    }
+    return list.map(({ origin: _origin, ...p }) => p);
+  }
+  sendMessage(body) {
+    const resolved = this.resolvePeer(body.to);
+    if (resolved.error !== void 0) return { ok: false, error: resolved.error };
+    const { peer } = resolved;
+    const mode = body.mode ?? "pull";
+    if (mode !== "pull" && mode !== "push" && mode !== "ping") return { ok: false, error: `invalid mode: ${String(mode)}` };
+    let meta;
+    if (body.meta !== void 0) {
+      const checked = checkMeta(body.meta);
+      if (!checked) return { ok: false, error: "invalid meta: expected {protocol: string, version: string}, each at most 128 characters" };
+      meta = checked;
+    }
+    const msg = {
+      id: this.state.nextMsgId++,
+      from_id: body.from_id ?? "cli",
+      from_name: body.from_name ?? "",
+      to_id: peer.id,
+      text: body.text ?? "",
+      mode,
+      sent_at: (/* @__PURE__ */ new Date()).toISOString(),
+      delivered: 0,
+      acknowledged: 0,
+      ...meta ? { meta } : {}
+    };
+    this.state.messages.push(msg);
+    this.state.scheduleSave();
+    if (peer.origin) this.opts.onRemoteMessage?.();
+    return { ok: true, to_id: peer.id, to_name: peer.name, message_id: msg.id };
+  }
+  pollMessages(body) {
+    const out = this.state.messages.filter((m) => m.to_id === body.id && m.delivered === 0);
+    for (const m of out) m.delivered = 1;
+    if (out.length) this.state.scheduleSave();
+    return { messages: out };
+  }
+  acknowledgeMessages(body) {
+    const ids = new Set(body.message_ids ?? []);
+    const before = this.state.messages.length;
+    this.state.messages = this.state.messages.filter((m) => !(m.to_id === body.id && ids.has(m.id)));
+    if (this.state.messages.length !== before) this.state.scheduleSave();
+    return { ok: true };
+  }
+  getBufferedMessages(body) {
+    return {
+      messages: this.state.messages.filter(
+        (m) => m.to_id === body.id && m.delivered === 1 && m.acknowledged === 0
+      )
+    };
+  }
+  unregister(body) {
+    this.removePeer(body.id);
+    this.gcProtocols();
+    this.state.scheduleSave();
+    return { ok: true };
+  }
+  // --- protocol registry ---
+  protocolError(code, error, extra = {}) {
+    return { ok: false, error, code, ...extra };
+  }
+  /**
+   * `/set-protocol`. Order: unknown peer, definition shape / size (INVALID_DEFINITION, TOO_LARGE), hash
+   * re-computation (HASH_MISMATCH), different hash for the same `(name, version)` (PROTOCOL_CONFLICT), held
+   * definitions limit (LIMIT). The same hash again is a no-op success, so a client may re-send at will.
+   */
+  setProtocol(body) {
+    const peer = this.localPeer(body.id);
+    if (!peer) return { ok: false, error: "unknown peer" };
+    const checked = checkDefinition(body.name, body.version, body.definition);
+    if (!checked.ok) return this.protocolError(checked.code, checked.error);
+    const { name, version, definition } = body;
+    const hash = protocolHash(definition.manifest, definition.doc);
+    if (body.hash !== hash) {
+      return this.protocolError("HASH_MISMATCH", `hash mismatch for ${name}@${version}: sent ${String(body.hash)}, computed ${hash}`);
+    }
+    this.gcProtocols();
+    const key = `${name}@${version}`;
+    const existing = this.state.protocols.get(key);
+    if (existing && existing.hash !== hash) {
+      const servers = this.serversOf(name, version).map((p) => `${p.name || p.id}@${p.hostname}`);
+      return this.protocolError(
+        "PROTOCOL_CONFLICT",
+        `${key} is already registered with a different definition (hash ${existing.hash}, held by ${servers.join(", ") || "no server"}); every server of it must unset_protocol first`,
+        { existing_hash: existing.hash, servers }
+      );
+    }
+    if (!existing) {
+      if (this.state.protocols.size >= PROTOCOL_MAX_STORED) {
+        return this.protocolError("LIMIT", `this broker already holds ${PROTOCOL_MAX_STORED} protocol definitions (limit)`);
+      }
+      this.state.protocols.set(key, {
+        name,
+        version,
+        hash,
+        definition: { manifest: definition.manifest, doc: definition.doc, source: definition.source, ref: definition.ref },
+        registered_at: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    peer.protocols = [...(peer.protocols ?? []).filter((d) => d.name !== name), { name, version, hash }];
+    this.gcProtocols();
+    this.state.scheduleSave();
+    return { ok: true };
+  }
+  /** `/unset-protocol`: drop one declaration by `name`, or all of the peer's. Succeeds with `removed: 0` when there was none. */
+  unsetProtocol(body) {
+    const peer = this.localPeer(body.id);
+    if (!peer) return { ok: false, error: "unknown peer" };
+    if (body.name !== void 0 && typeof body.name !== "string") return { ok: false, error: "invalid name" };
+    const before = peer.protocols ?? [];
+    const kept = body.name === void 0 ? [] : before.filter((d) => d.name !== body.name);
+    const removed = before.length - kept.length;
+    if (kept.length) peer.protocols = kept;
+    else delete peer.protocols;
+    if (removed) {
+      this.gcProtocols();
+      this.state.scheduleSave();
+    }
+    return { ok: true, removed };
+  }
+  /** `/get-protocol`: the stored definition of `name` at `version`, or at the highest held version. No round trip to any server. */
+  getProtocol(body) {
+    if (typeof body.name !== "string" || !body.name) return this.protocolError("PROTOCOL_NOT_FOUND", "protocol name is required", { versions: [] });
+    this.gcProtocols();
+    const held = [...this.state.protocols.values()].filter((sp) => sp.name === body.name);
+    held.sort((a, b) => compareVersions(b.version, a.version) || (a.registered_at < b.registered_at ? 1 : -1));
+    const versions = held.map((sp) => sp.version);
+    const found = body.version === void 0 ? held[0] : held.find((sp) => sp.version === body.version);
+    if (!found) {
+      const what = body.version === void 0 ? `"${body.name}"` : `"${body.name}" version "${body.version}"`;
+      return this.protocolError("PROTOCOL_NOT_FOUND", `Protocol ${what} not found (registered versions: ${versions.join(", ") || "none"})`, { versions });
+    }
+    return { ok: true, protocol: found, servers: this.serversOf(found.name, found.version).length };
+  }
+  /** Route table of the protocol registry in `PROTOCOL_ROUTES` order. */
+  protocolRoutes() {
+    return {
+      "/set-protocol": (b) => this.setProtocol(b),
+      "/unset-protocol": (b) => this.unsetProtocol(b),
+      "/get-protocol": (b) => this.getProtocol(b)
+    };
+  }
+  // --- relay from a fallback broker ---
+  /** Queue a message for `peerId` exactly like `sendMessage` does. */
+  enqueue(peerId, m) {
+    const meta = m.meta === void 0 ? null : checkMeta(m.meta);
+    this.state.messages.push({
+      id: this.state.nextMsgId++,
+      from_id: m.from_id,
+      from_name: m.from_name,
+      to_id: peerId,
+      text: m.text,
+      mode: m.mode ?? "pull",
+      sent_at: m.sent_at,
+      delivered: 0,
+      acknowledged: 0,
+      ...meta ? { meta } : {}
+    });
+  }
+  /** Give `peer` the relayed messages that were waiting for its name. */
+  deliverPending(peer) {
+    if (!peer.name || this.state.pending.length === 0) return;
+    const mine = (r) => r.to_name === peer.name && (!r.to_hostname || r.to_hostname === peer.hostname);
+    const hits = this.state.pending.filter(mine);
+    if (hits.length === 0) return;
+    for (const r of hits) this.enqueue(peer.id, r);
+    this.state.pending = this.state.pending.filter((r) => !mine(r));
+    log.info(`Delivered ${hits.length} relayed message(s) to ${peer.name} (${peer.id})`);
+  }
+  /**
+   * `/relay-messages`: undelivered messages of a fallback broker. Peer ids are broker-local, so the
+   * recipient is addressed by name (and hostname). A recipient that is not registered yet (its client
+   * moves over only after the fallback exits) gets the message when it registers.
+   */
+  relayMessages(body) {
+    const res = { ok: true, delivered: 0, queued: 0, dropped: 0 };
+    const cutoff = BrokerHandlers.cutoff();
+    for (const m of body.messages ?? []) {
+      if (!m.to_name) {
+        res.dropped++;
+        continue;
+      }
+      let cands = [...this.state.peers.values()].filter((p) => p.name === m.to_name && this.isAlive(p, cutoff));
+      if (m.to_hostname && cands.some((p) => p.hostname === m.to_hostname)) cands = cands.filter((p) => p.hostname === m.to_hostname);
+      if (cands.length === 1) {
+        this.enqueue(cands[0].id, m);
+        res.delivered++;
+      } else {
+        this.state.pending.push({ ...m, queued_at: (/* @__PURE__ */ new Date()).toISOString() });
+        res.queued++;
+      }
+    }
+    this.state.scheduleSave();
+    log.info(`Relay: ${res.delivered} delivered, ${res.queued} queued, ${res.dropped} dropped`);
+    return res;
+  }
+  // --- mesh (permanent broker sync) ---
+  /** Live peers that registered with this broker directly. */
+  meshLocalPeers() {
+    const cutoff = BrokerHandlers.cutoff();
+    return [...this.state.peers.values()].filter((p) => !p.origin && this.isAlive(p, cutoff));
+  }
+  /** Undelivered messages addressed to peers replicated from `origin` (to be forwarded there). */
+  meshOutbox(origin) {
+    return this.state.messages.filter((m) => {
+      if (m.delivered !== 0) return false;
+      return this.state.peers.get(m.to_id)?.origin === origin;
+    });
+  }
+  /** Drop messages the other broker took over. */
+  meshDrop(ids) {
+    if (!ids.length) return;
+    const gone = new Set(ids);
+    this.state.messages = this.state.messages.filter((m) => !gone.has(m.id));
+    this.state.scheduleSave();
+  }
+  /** Replace everything held for `origin` by `peers` and note that `origin` is alive. */
+  meshApplyPeers(origin, peers) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.state.originSeen.set(origin, Date.now());
+    const incoming = /* @__PURE__ */ new Set();
+    for (const p of peers) {
+      const local = this.state.peers.get(p.id);
+      if (local && !local.origin) continue;
+      const moved = [...this.state.peers.values()].some((q) => !q.origin && q.pid === p.pid && q.hostname === p.hostname);
+      if (moved) continue;
+      incoming.add(p.id);
+      this.state.peers.set(p.id, { ...p, origin, last_seen: now });
+    }
+    for (const p of [...this.state.peers.values()]) {
+      if (p.origin === origin && !incoming.has(p.id)) this.removePeer(p.id);
+    }
+    this.gcProtocols();
+    this.state.scheduleSave();
+  }
+  /** Definitions declared by this broker's direct, alive peers (what a mesh sync sends). */
+  meshLocalProtocols() {
+    const out = /* @__PURE__ */ new Map();
+    for (const p of this.meshLocalPeers()) {
+      for (const d of p.protocols ?? []) {
+        const key = `${d.name}@${d.version}`;
+        const sp = this.state.protocols.get(key);
+        if (sp && sp.hash === d.hash) out.set(key, sp);
+      }
+    }
+    return [...out.values()];
+  }
+  /**
+   * Take over definitions another broker's direct peers declare. Only a definition that a peer we now hold
+   * declares with the same hash is stored (the rest would be collected at once). A `(name, version)` we already
+   * hold with another hash stays as it is (ours wins) and the received one is dropped with a warning.
+   */
+  meshApplyProtocols(from, protocols) {
+    let added = false;
+    for (const sp of protocols) {
+      const checked = checkDefinition(sp?.name, sp?.version, sp?.definition);
+      if (!checked.ok) {
+        log.warn(`mesh: dropped protocol from ${from}: ${checked.error}`);
+        continue;
+      }
+      const hash = protocolHash(sp.definition.manifest, sp.definition.doc);
+      if (hash !== sp.hash) {
+        log.warn(`mesh: dropped protocol ${sp.name}@${sp.version} from ${from}: hash mismatch`);
+        continue;
+      }
+      const key = `${sp.name}@${sp.version}`;
+      const mine = this.state.protocols.get(key);
+      if (mine) {
+        if (mine.hash !== hash && !this.warnedProtocolConflicts.has(`${key}:${hash}`)) {
+          this.warnedProtocolConflicts.add(`${key}:${hash}`);
+          log.warn(`mesh: protocol ${key} from ${from} differs from the one held here (${hash} vs ${mine.hash}); keeping ours`);
+        }
+        continue;
+      }
+      if (this.state.protocols.size >= PROTOCOL_MAX_STORED) {
+        log.warn(`mesh: dropped protocol ${key} from ${from}: ${PROTOCOL_MAX_STORED} definitions held (limit)`);
+        continue;
+      }
+      if (!this.serversOf(sp.name, sp.version).some((p) => p.protocols?.some((d) => d.name === sp.name && d.version === sp.version && d.hash === hash))) continue;
+      this.state.protocols.set(key, {
+        name: sp.name,
+        version: sp.version,
+        hash,
+        definition: { manifest: sp.definition.manifest, doc: sp.definition.doc, source: sp.definition.source, ref: sp.definition.ref },
+        registered_at: typeof sp.registered_at === "string" ? sp.registered_at : (/* @__PURE__ */ new Date()).toISOString()
+      });
+      added = true;
+    }
+    if (added) this.state.scheduleSave();
+  }
+  /** Take over messages forwarded by broker `from`; returns the sender-side ids to drop (duplicates count as taken). */
+  meshAccept(from, messages) {
+    const accepted = [];
+    for (const m of messages) {
+      const target = this.state.peers.get(m.to_id);
+      if (!target || target.origin) continue;
+      const key = `${from}:${m.id}`;
+      const dup = this.recentMeshKeys.has(key) || this.state.messages.some((x) => x.mesh_key === key);
+      if (!dup) {
+        this.state.messages.push({ ...m, id: this.state.nextMsgId++, delivered: 0, acknowledged: 0, mesh_key: key });
+        this.recentMeshKeys.add(key);
+        if (this.recentMeshKeys.size > MESH_KEY_MEMORY) this.recentMeshKeys.delete(this.recentMeshKeys.values().next().value);
+      }
+      accepted.push(m.id);
+    }
+    if (accepted.length) this.state.scheduleSave();
+    return accepted;
+  }
+  /** Inbound `/mesh/sync`. */
+  meshSync(body) {
+    if (!body.from) throw new Error("mesh sync: missing from");
+    if (body.from === this.opts.id) return { id: body.from, peers: [], accepted: [] };
+    this.meshApplyPeers(body.from, body.peers ?? []);
+    this.meshApplyProtocols(body.from, body.protocols ?? []);
+    const accepted = this.meshAccept(body.from, body.messages ?? []);
+    const protocols = this.meshLocalProtocols();
+    return { id: this.opts.id ?? "", peers: this.meshLocalPeers(), accepted, ...protocols.length ? { protocols } : {} };
+  }
+  /** Route table in `BROKER_POST_ROUTES` order. */
+  routes() {
+    return {
+      "/register": (b) => this.register(b),
+      "/heartbeat": (b) => this.heartbeat(b),
+      "/set-summary": (b) => this.setSummary(b),
+      "/set-name": (b) => this.setName(b),
+      "/list-peers": (b) => this.listPeers(b),
+      "/send-message": (b) => this.sendMessage(b),
+      "/poll-messages": (b) => this.pollMessages(b),
+      "/acknowledge-messages": (b) => this.acknowledgeMessages(b),
+      "/get-buffered-messages": (b) => this.getBufferedMessages(b),
+      "/unregister": (b) => this.unregister(b)
+    };
+  }
+}
+
+class Mesh {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  timer = null;
+  running = false;
+  again = false;
+  stopped = false;
+  links = /* @__PURE__ */ new Map();
+  /** url -> id of the broker that answered there */
+  origins = /* @__PURE__ */ new Map();
+  start() {
+    log.info(`mesh on (id ${this.opts.id}, every ${this.opts.intervalMs}ms)`);
+    this.timer = setInterval(() => void this.syncOnce(), this.opts.intervalMs);
+    this.timer.unref();
+    void this.syncOnce();
+  }
+  stop() {
+    this.stopped = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+  }
+  /** Sync soon (coalesced). */
+  kick() {
+    if (this.running) this.again = true;
+    else setImmediate(() => void this.syncOnce());
+  }
+  /** One round against every listed broker. Never throws. */
+  async syncOnce() {
+    if (this.running) {
+      this.again = true;
+      return;
+    }
+    this.running = true;
+    try {
+      do {
+        this.again = false;
+        await Promise.all(this.opts.urls().map((url) => this.syncWith(url)));
+      } while (this.again && !this.stopped);
+    } finally {
+      this.running = false;
+    }
+  }
+  setLink(url, state, detail = "") {
+    const prev = this.links.get(url);
+    this.links.set(url, state);
+    if (prev === state) return;
+    if (state === "up") log.info(`mesh: ${url} ${prev === "down" ? "is back, synced" : "joined"}`);
+    else if (state === "down") log.warn(`mesh: ${url} unreachable${detail ? ` (${detail})` : ""}; will keep retrying`);
+    else if (state === "unsupported") log.warn(`mesh: ${url} does not take part in the mesh (${detail})`);
+    else if (state === "self") log.info(`mesh: ${url} is this broker, skipped`);
+  }
+  async syncWith(url) {
+    if (this.links.get(url) === "self" || this.stopped) return;
+    const { handlers, id } = this.opts;
+    const origin = this.origins.get(url);
+    const protocols = handlers.meshLocalProtocols();
+    const req = {
+      from: id,
+      peers: handlers.meshLocalPeers(),
+      messages: origin ? handlers.meshOutbox(origin) : [],
+      ...protocols.length ? { protocols } : {}
+    };
+    let res;
+    try {
+      const headers = { "Content-Type": "application/json" };
+      if (this.opts.token) headers.Authorization = `Bearer ${this.opts.token}`;
+      const r = await postJson(`${url}${MESH_SYNC_ROUTE}`, headers, JSON.stringify(req), this.opts.timeoutMs ?? 3e3);
+      if (r.status === 404) return this.setLink(url, "unsupported", "HTTP 404");
+      if (r.status < 200 || r.status >= 300) return this.setLink(url, "down", `HTTP ${r.status}`);
+      res = JSON.parse(r.body);
+    } catch (e) {
+      return this.setLink(url, "down", e.message);
+    }
+    if (!res.id) return this.setLink(url, "unsupported", "no broker id in answer");
+    if (res.id === id) return this.setLink(url, "self");
+    const learned = this.origins.get(url) !== res.id;
+    this.origins.set(url, res.id);
+    handlers.meshApplyPeers(res.id, res.peers ?? []);
+    handlers.meshApplyProtocols(res.id, res.protocols ?? []);
+    handlers.meshDrop(res.accepted ?? []);
+    if (learned && handlers.meshOutbox(res.id).length) this.again = true;
+    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}`;
+  const u = new URL(s);
+  if (!u.port) u.port = String(DEFAULT_HTTP_PORT);
+  return u.origin;
+}
+function postJson(url, headers, body, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const req = request(url, { method: "POST", agent: false, headers: { ...headers, "Content-Length": Buffer.byteLength(body) }, timeout: timeoutMs }, (res) => {
+      const chunks = [];
+      res.on("data", (d) => chunks.push(d));
+      res.on("end", () => resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString("utf8") }));
+      res.on("error", reject);
+    });
+    req.on("timeout", () => req.destroy(new Error(`timeout after ${timeoutMs}ms`)));
+    req.on("error", reject);
+    req.end(body);
+  });
+}
+
+function createBrokerApp(opts) {
+  const routes = opts.handlers.routes();
+  const protocolRoutes = opts.handlers.protocolRoutes();
+  const router = createRouter();
+  router.get(HEALTH_ROUTE, defineEventHandler(() => ({
+    status: "ok",
+    version: opts.version,
+    id: opts.id,
+    port: opts.port(),
+    peers: opts.handlers.alivePeerCount(),
+    ...opts.fallback ? { fallback: true } : {}
+  })));
+  const post = (route, run) => router.post(route, defineEventHandler(async (event) => {
+    if (!authorized(event, opts.token)) return unauthorized(event);
+    try {
+      return run(await readJson(event));
+    } catch (e) {
+      setResponseStatus(event, 500);
+      return { error: e.message };
+    }
+  }));
+  for (const route of BROKER_POST_ROUTES) post(route, (body) => routes[route](body));
+  post(RELAY_ROUTE, (body) => opts.handlers.relayMessages(body));
+  for (const route of PROTOCOL_ROUTES) post(route, (body) => protocolRoutes[route](body));
+  if (opts.mesh) post(MESH_SYNC_ROUTE, (body) => opts.handlers.meshSync(body));
+  const app = createApp();
+  app.use(router);
+  app.use(defineEventHandler(async (event) => {
+    if (event.method !== "POST") {
+      return send(event, `agent-messenger broker ${opts.version}
+`, "text/plain");
+    }
+    if (!authorized(event, opts.token)) return unauthorized(event);
+    setResponseStatus(event, 404);
+    return { error: "not found" };
+  }));
+  return app;
+}
+function authorized(event, token) {
+  return !token || getRequestHeader(event, "authorization") === `Bearer ${token}`;
+}
+function unauthorized(event) {
+  setResponseStatus(event, 401);
+  return { error: "unauthorized" };
+}
+async function readJson(event) {
+  const raw = await readRawBody(event, "utf8");
+  return raw ? JSON.parse(raw) : {};
+}
+
+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) => {
+    try {
+      if (JSON.parse(msg.toString())[DISCOVERY_KEY] !== DISCOVERY_PROBE_VALUE) return;
+    } catch {
+      return;
+    }
+    const reply = Buffer.from(JSON.stringify(opts.reply()));
+    disco.send(reply, rinfo.port, rinfo.address, () => {
+    });
+  });
+  const bindAddr = opts.addr && !opts.addr.endsWith(".255") ? opts.addr : "0.0.0.0";
+  return new Promise((resolve) => {
+    disco.once("error", () => resolve(disco));
+    disco.bind(opts.port, bindAddr, () => {
+      try {
+        disco.setBroadcast(true);
+      } catch {
+      }
+      log.info(`discovery responder on udp ${bindAddr}:${opts.port} (id: ${opts.reply().id})`);
+      resolve(disco);
+    });
+  });
+}
+function probeTargets(addr) {
+  if (addr) return [addr];
+  const targets = /* @__PURE__ */ new Set(["255.255.255.255"]);
+  for (const list of Object.values(networkInterfaces())) {
+    for (const i of list ?? []) {
+      if (i.family !== "IPv4" || i.internal || !i.netmask) continue;
+      const ip = i.address.split(".").map(Number);
+      const mask = i.netmask.split(".").map(Number);
+      targets.add(ip.map((o, k) => o & mask[k] | ~mask[k] & 255).join("."));
+    }
+  }
+  return [...targets];
+}
+function localAddresses() {
+  const out = /* @__PURE__ */ new Set(["127.0.0.1"]);
+  for (const list of Object.values(networkInterfaces())) {
+    for (const i of list ?? []) if (i.family === "IPv4") out.add(i.address);
+  }
+  return out;
+}
+function probeBrokers(opts) {
+  return new Promise((resolve) => {
+    const sock = createSocket({ type: "udp4" });
+    const found = /* @__PURE__ */ new Map();
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        sock.close();
+      } catch {
+      }
+      resolve([...found.values()]);
+    };
+    const timer = setTimeout(finish, opts.timeoutMs);
+    sock.on("error", finish);
+    sock.on("message", (msg, rinfo) => {
+      try {
+        const m = JSON.parse(msg.toString());
+        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 });
+        }
+      } catch {
+      }
+    });
+    sock.bind(0, () => {
+      try {
+        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 TIMEOUT_MS = 5e3;
+async function post(url, path, token, body) {
+  const headers = { "Content-Type": "application/json" };
+  if (token) headers.Authorization = `Bearer ${token}`;
+  return fetch(`${url}${path}`, { method: "POST", headers, body: JSON.stringify(body), signal: AbortSignal.timeout(TIMEOUT_MS) });
+}
+async function relayUndelivered(state, url, token) {
+  const items = [];
+  let dropped = 0;
+  for (const m of state.messages) {
+    if (m.delivered !== 0) continue;
+    const peer = state.peers.get(m.to_id);
+    if (!peer?.name) {
+      dropped++;
+      continue;
+    }
+    items.push({
+      from_id: m.from_id,
+      from_name: m.from_name,
+      to_name: peer.name,
+      to_hostname: peer.hostname,
+      text: m.text,
+      mode: m.mode ?? "pull",
+      sent_at: m.sent_at,
+      ...m.meta ? { meta: m.meta } : {}
+    });
+  }
+  let sent = 0;
+  if (items.length) {
+    const res = await post(url, RELAY_ROUTE, token, { messages: items });
+    if (res.ok) {
+      const r = await res.json();
+      sent = r.delivered + r.queued;
+      dropped += r.dropped;
+    } else if (res.status === 404) {
+      for (const it of items) {
+        const r = await post(url, "/send-message", token, { to: it.to_name, from_id: it.from_id, from_name: it.from_name, text: it.text, mode: it.mode, meta: it.meta });
+        if (r.ok && (await r.json()).ok) sent++;
+        else dropped++;
+      }
+    } else {
+      throw new Error(`relay to ${url} failed: ${res.status} ${await res.text()}`);
+    }
+  }
+  state.messages = state.messages.filter((m) => m.delivered !== 0);
+  state.scheduleSave();
+  log.info(`relayed ${sent} message(s) to ${url} (${dropped} dropped: recipient without name or refused)`);
+  return { sent, dropped };
+}
+
+const version = "0.10.0";
+const pkg = {
+	version: version};
+
+const VERSION = pkg.version;
+const CLEAN_INTERVAL_MS = 3e4;
+async function startBroker(options = {}) {
+  const { onSupersede, ...rest } = options;
+  const cfg = resolveConfig(rest);
+  const state = new BrokerState(cfg.stateFile);
+  state.load();
+  let mesh = null;
+  const handlers = new BrokerHandlers(state, {
+    id: cfg.id,
+    meshPeerTtlMs: cfg.meshPeerTtlMs,
+    onRemoteMessage: () => mesh?.kick()
+  });
+  handlers.cleanStalePeers();
+  const cleaner = setInterval(() => handlers.cleanStalePeers(), CLEAN_INTERVAL_MS);
+  cleaner.unref();
+  let port = cfg.port;
+  const app = createBrokerApp({
+    handlers,
+    version: VERSION,
+    id: cfg.id,
+    port: () => port,
+    token: cfg.token,
+    fallback: cfg.fallback,
+    mesh: cfg.mesh
+  });
+  let listener;
+  try {
+    listener = await listen(toNodeListener(app), {
+      port: cfg.port,
+      hostname: cfg.bind,
+      showURL: false,
+      autoClose: false,
+      // `isProd` makes listhen fail on a busy port instead of silently picking another one.
+      // For port 0 we need listhen's random-port path, which `isProd` would disable.
+      isProd: cfg.port !== 0
+    });
+  } catch (e) {
+    clearInterval(cleaner);
+    throw e;
+  }
+  port = listener.address.port;
+  const reply = () => ({ [DISCOVERY_KEY]: DISCOVERY_REPLY_VALUE, id: cfg.id, port, version: VERSION, ...cfg.fallback ? { fallback: true } : {} });
+  let disco = null;
+  if (cfg.discovery) {
+    disco = await startDiscoveryResponder({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, reply });
+  }
+  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),
+      intervalMs: cfg.meshIntervalMs
+    });
+    mesh.start();
+  }
+  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"})`);
+  log.info(cfg.token ? "token auth enabled" : "WARNING: no AGENT_MESSENGER_TOKEN set \u2014 broker is open");
+  let closed = false;
+  let fallbackTimer = null;
+  const close = async () => {
+    if (closed) return;
+    closed = true;
+    clearInterval(cleaner);
+    if (fallbackTimer) clearInterval(fallbackTimer);
+    mesh?.stop();
+    if (disco) {
+      await new Promise((resolve) => disco.close(() => resolve()));
+    }
+    await listener.close();
+    if (state.savePending) state.saveNow();
+  };
+  if (cfg.fallback && cfg.discovery) {
+    const mine = localAddresses();
+    let busy = false;
+    const lookForBroker = async () => {
+      if (busy || closed) return;
+      busy = true;
+      try {
+        const found = await probeBrokers({ port: cfg.discoveryPort, addr: cfg.discoveryAddr, 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`);
+        await relayUndelivered(state, other.url, cfg.token);
+        await close();
+        log.info("fallback: done");
+        onSupersede?.(other.url);
+      } catch (e) {
+        log.warn(`fallback: ${e.message} \u2014 will retry`);
+      } finally {
+        busy = false;
+      }
+    };
+    fallbackTimer = setInterval(() => void lookForBroker(), cfg.fallbackIntervalMs);
+    fallbackTimer.unref();
+  }
+  return { close, port, id: cfg.id };
+}
+
+export { DEFAULT_STATE_FILE as D, FALLBACK_ENV as F, MESH_ENV as M, STATE_DIR as S, VERSION as V, FALLBACK_INTERVAL_ENV as a, configFromEnv as c, log as l, resolveConfig as r, startBroker as s };