@unagents/messenger-broker 0.0.0-stage → 0.9.0

package/dist/index.d.mts

@@ -0,0 +1,109 @@
+import { Peer, Message, RelayedMessage } from '@unagents/messenger-protocol';
+
+/**
+ * Broker configuration. Every field can be given to `startBroker(options)`;
+ * anything left out falls back to the environment (`AGENT_MESSENGER_*`,
+ * same names and defaults as the JavaScript `legacy/src/config.js`).
+ */
+interface BrokerOptions {
+    /** HTTP listen port (`AGENT_MESSENGER_PORT`, default 7901). `0` = random free port. */
+    port?: number;
+    /** HTTP bind address (`AGENT_MESSENGER_BIND`, default `0.0.0.0`). */
+    bind?: string;
+    /** Bearer token; `""` disables auth (`AGENT_MESSENGER_TOKEN`, default `""`). */
+    token?: string;
+    /** Broker id shown in `/health` and discovery replies (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id?: string;
+    /** State file (`AGENT_MESSENGER_STATE`, default `~/.agent-messenger/broker.json`). */
+    stateFile?: string;
+    /** UDP discovery responder on/off (`AGENT_MESSENGER_DISCOVERY`, `"off"` disables; default on). */
+    discovery?: boolean;
+    /** UDP discovery port (`AGENT_MESSENGER_DISCOVERY_PORT`, default 7902). */
+    discoveryPort?: number;
+    /** UDP bind address when pinned (`AGENT_MESSENGER_DISCOVERY_ADDR`, default `""` = all interfaces). */
+    discoveryAddr?: 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
+     * undelivered messages there and exits. A permanent broker (default) never does this.
+     */
+    fallback?: boolean;
+    /** Fallback discovery interval in ms (`AGENT_MESSENGER_FALLBACK_INTERVAL_MS`, default 10000). */
+    fallbackIntervalMs?: number;
+    /** Called after a fallback broker has relayed its messages and closed itself (`main.ts` exits the process). */
+    onSupersede?: (url: string) => void;
+    /**
+     * Join the permanent-broker mesh (`AGENT_MESSENGER_MESH`, `"on"` enables; default off).
+     * Fallback brokers must leave this off: only brokers started with it take part.
+     */
+    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.
+     */
+    meshBrokers?: string[];
+    /** 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). */
+declare const FALLBACK_ENV = "AGENT_MESSENGER_FALLBACK";
+declare const FALLBACK_INTERVAL_ENV = "AGENT_MESSENGER_FALLBACK_INTERVAL_MS";
+/** Directory of the default state file (`~/.agent-messenger`). Not exported by protocol. */
+declare const STATE_DIR: string;
+/** Default state file path (`~/.agent-messenger/broker.json`). Not exported by protocol. */
+declare const DEFAULT_STATE_FILE: string;
+/** Mesh environment variables. Broker-private (not in the protocol's `ENV`, which mirrors the legacy names). */
+declare const MESH_ENV: {
+    readonly MESH: "AGENT_MESSENGER_MESH";
+    readonly INTERVAL_MS: "AGENT_MESSENGER_MESH_INTERVAL_MS";
+    readonly PEER_TTL_MS: "AGENT_MESSENGER_MESH_PEER_TTL_MS";
+};
+/** Read the broker-side environment exactly like `legacy/src/config.js`. */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): BrokerConfig;
+/** `options` over environment over built-in defaults. */
+declare function resolveConfig(options?: BrokerOptions): BrokerConfig;
+
+/**
+ * On-disk shape of `~/.agent-messenger/broker.json` (written by core 0.4.0
+ * `legacy/src/broker.js`). Not part of the protocol package — broker-private.
+ */
+interface BrokerStateFile {
+    peers: Peer[];
+    messages: Message[];
+    nextMsgId: number;
+    /** Relayed messages waiting for their recipient to register (absent in files written before the fallback relay). */
+    pending?: PendingRelay[];
+}
+/** A message relayed from a fallback broker whose recipient has not registered here yet. */
+interface PendingRelay extends RelayedMessage {
+    /** ISO 8601; pending items older than the TTL are dropped. */
+    queued_at: string;
+}
+
+/** Package version, reported by `/health` and discovery replies (inlined at build time). */
+declare const VERSION: string;
+interface BrokerHandle {
+    /** Stop HTTP + UDP, flush a pending state save. Idempotent. */
+    close(): Promise<void>;
+    /** Port the HTTP server listens on (actual port when `port: 0` was given). */
+    port: number;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+}
+/**
+ * Start the broker daemon: load state, sweep stale peers, listen on HTTP
+ * (h3 + listhen) and answer UDP discovery probes.
+ *
+ * Unlike the JavaScript `startBroker()`, this does not install SIGINT /
+ * SIGTERM handlers — callers own the lifecycle through `close()`
+ * (`src/main.ts` does that for the standalone entry).
+ */
+declare function startBroker(options?: BrokerOptions): Promise<BrokerHandle>;
+
+export { DEFAULT_STATE_FILE, FALLBACK_ENV, FALLBACK_INTERVAL_ENV, MESH_ENV, STATE_DIR, VERSION, configFromEnv, resolveConfig, startBroker };
+export type { BrokerConfig, BrokerHandle, BrokerOptions, BrokerStateFile };

package/dist/index.d.ts

@@ -0,0 +1,109 @@
+import { Peer, Message, RelayedMessage } from '@unagents/messenger-protocol';
+
+/**
+ * Broker configuration. Every field can be given to `startBroker(options)`;
+ * anything left out falls back to the environment (`AGENT_MESSENGER_*`,
+ * same names and defaults as the JavaScript `legacy/src/config.js`).
+ */
+interface BrokerOptions {
+    /** HTTP listen port (`AGENT_MESSENGER_PORT`, default 7901). `0` = random free port. */
+    port?: number;
+    /** HTTP bind address (`AGENT_MESSENGER_BIND`, default `0.0.0.0`). */
+    bind?: string;
+    /** Bearer token; `""` disables auth (`AGENT_MESSENGER_TOKEN`, default `""`). */
+    token?: string;
+    /** Broker id shown in `/health` and discovery replies (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id?: string;
+    /** State file (`AGENT_MESSENGER_STATE`, default `~/.agent-messenger/broker.json`). */
+    stateFile?: string;
+    /** UDP discovery responder on/off (`AGENT_MESSENGER_DISCOVERY`, `"off"` disables; default on). */
+    discovery?: boolean;
+    /** UDP discovery port (`AGENT_MESSENGER_DISCOVERY_PORT`, default 7902). */
+    discoveryPort?: number;
+    /** UDP bind address when pinned (`AGENT_MESSENGER_DISCOVERY_ADDR`, default `""` = all interfaces). */
+    discoveryAddr?: 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
+     * undelivered messages there and exits. A permanent broker (default) never does this.
+     */
+    fallback?: boolean;
+    /** Fallback discovery interval in ms (`AGENT_MESSENGER_FALLBACK_INTERVAL_MS`, default 10000). */
+    fallbackIntervalMs?: number;
+    /** Called after a fallback broker has relayed its messages and closed itself (`main.ts` exits the process). */
+    onSupersede?: (url: string) => void;
+    /**
+     * Join the permanent-broker mesh (`AGENT_MESSENGER_MESH`, `"on"` enables; default off).
+     * Fallback brokers must leave this off: only brokers started with it take part.
+     */
+    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.
+     */
+    meshBrokers?: string[];
+    /** 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). */
+declare const FALLBACK_ENV = "AGENT_MESSENGER_FALLBACK";
+declare const FALLBACK_INTERVAL_ENV = "AGENT_MESSENGER_FALLBACK_INTERVAL_MS";
+/** Directory of the default state file (`~/.agent-messenger`). Not exported by protocol. */
+declare const STATE_DIR: string;
+/** Default state file path (`~/.agent-messenger/broker.json`). Not exported by protocol. */
+declare const DEFAULT_STATE_FILE: string;
+/** Mesh environment variables. Broker-private (not in the protocol's `ENV`, which mirrors the legacy names). */
+declare const MESH_ENV: {
+    readonly MESH: "AGENT_MESSENGER_MESH";
+    readonly INTERVAL_MS: "AGENT_MESSENGER_MESH_INTERVAL_MS";
+    readonly PEER_TTL_MS: "AGENT_MESSENGER_MESH_PEER_TTL_MS";
+};
+/** Read the broker-side environment exactly like `legacy/src/config.js`. */
+declare function configFromEnv(env?: NodeJS.ProcessEnv): BrokerConfig;
+/** `options` over environment over built-in defaults. */
+declare function resolveConfig(options?: BrokerOptions): BrokerConfig;
+
+/**
+ * On-disk shape of `~/.agent-messenger/broker.json` (written by core 0.4.0
+ * `legacy/src/broker.js`). Not part of the protocol package — broker-private.
+ */
+interface BrokerStateFile {
+    peers: Peer[];
+    messages: Message[];
+    nextMsgId: number;
+    /** Relayed messages waiting for their recipient to register (absent in files written before the fallback relay). */
+    pending?: PendingRelay[];
+}
+/** A message relayed from a fallback broker whose recipient has not registered here yet. */
+interface PendingRelay extends RelayedMessage {
+    /** ISO 8601; pending items older than the TTL are dropped. */
+    queued_at: string;
+}
+
+/** Package version, reported by `/health` and discovery replies (inlined at build time). */
+declare const VERSION: string;
+interface BrokerHandle {
+    /** Stop HTTP + UDP, flush a pending state save. Idempotent. */
+    close(): Promise<void>;
+    /** Port the HTTP server listens on (actual port when `port: 0` was given). */
+    port: number;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+}
+/**
+ * Start the broker daemon: load state, sweep stale peers, listen on HTTP
+ * (h3 + listhen) and answer UDP discovery probes.
+ *
+ * Unlike the JavaScript `startBroker()`, this does not install SIGINT /
+ * SIGTERM handlers — callers own the lifecycle through `close()`
+ * (`src/main.ts` does that for the standalone entry).
+ */
+declare function startBroker(options?: BrokerOptions): Promise<BrokerHandle>;
+
+export { DEFAULT_STATE_FILE, FALLBACK_ENV, FALLBACK_INTERVAL_ENV, MESH_ENV, STATE_DIR, VERSION, configFromEnv, resolveConfig, startBroker };
+export type { BrokerConfig, BrokerHandle, BrokerOptions, BrokerStateFile };

package/dist/index.mjs

@@ -0,0 +1,11 @@
+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.CY2SPlVR.mjs';
+import 'node:os';
+import 'node:path';
+import 'defu';
+import 'node:fs';
+import 'consola';
+import 'node:http';
+import 'node:dgram';

package/dist/main.d.mts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+
+export { };

package/dist/main.mjs

@@ -0,0 +1,22 @@
+import { s as startBroker, l as log } from './shared/messenger-broker.CY2SPlVR.mjs';
+import 'listhen';
+import 'h3';
+import '@unagents/messenger-protocol';
+import 'node:os';
+import 'node:path';
+import 'defu';
+import 'node:fs';
+import 'consola';
+import 'node:http';
+import 'node:dgram';
+
+const broker = await startBroker({
+  // fallback only: messages are relayed and the broker is closed, nothing left to do
+  onSupersede: () => process.exit(0)
+});
+const shutdown = () => {
+  log.info("shutting down");
+  broker.close().finally(() => process.exit(0));
+};
+process.once("SIGINT", shutdown);
+process.once("SIGTERM", shutdown);

package/dist/shared/messenger-broker.CY2SPlVR.mjs

@@ -0,0 +1,842 @@
+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, HEARTBEAT_TIMEOUT_MS, MESH_SYNC_ROUTE, HEALTH_ROUTE, BROKER_POST_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 { 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 = [];
+  /** 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 ?? [];
+      log.info(`Loaded state from ${this.file} (${this.peers.size} peer(s), ${this.messages.length} message(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 } : {}
+      };
+      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 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();
+  // --- 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();
+    }
+  }
+  /** 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
+    });
+    this.deliverPending(this.state.peers.get(id));
+    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();
+    this.state.scheduleSave();
+    return { 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);
+    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)}` };
+    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
+    };
+    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.state.scheduleSave();
+    return { ok: true };
+  }
+  // --- relay from a fallback broker ---
+  /** Queue a message for `peerId` exactly like `sendMessage` does. */
+  enqueue(peerId, m) {
+    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
+    });
+  }
+  /** 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.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 ?? []);
+    const accepted = this.meshAccept(body.from, body.messages ?? []);
+    return { id: this.opts.id ?? "", peers: this.meshLocalPeers(), accepted };
+  }
+  /** 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 req = {
+      from: id,
+      peers: handlers.meshLocalPeers(),
+      messages: origin ? handlers.meshOutbox(origin) : []
+    };
+    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.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 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));
+  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
+    });
+  }
+  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 });
+        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.9.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 };

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@unagents/messenger-broker",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.9.0",
+  "description": "agent-messenger broker: HTTP daemon that tracks peers and routes messages between Claude Code sessions.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unagents/agent-messenger.git",
+    "directory": "packages/broker"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./main": "./dist/main.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "typecheck": "tsgo -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@unagents/messenger-protocol": "0.9.0",
+    "consola": "^3.4.2",
+    "defu": "^6.1.7",
+    "h3": "^1.15.11",
+    "listhen": "^1.10.1"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.