@unagents/messenger-broker 0.9.0 → 0.10.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Peer, Message, RelayedMessage } from '@unagents/messenger-protocol';
+import { Peer, Message, RelayedMessage, StoredProtocol } from '@unagents/messenger-protocol';
 
 /**
  * Broker configuration. Every field can be given to `startBroker(options)`;
@@ -78,6 +78,8 @@ interface BrokerStateFile {
     nextMsgId: number;
     /** Relayed messages waiting for their recipient to register (absent in files written before the fallback relay). */
     pending?: PendingRelay[];
+    /** Protocol definitions (absent in files written before the protocol registry, or when none is held). */
+    protocols?: StoredProtocol[];
 }
 /** A message relayed from a fallback broker whose recipient has not registered here yet. */
 interface PendingRelay extends RelayedMessage {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Peer, Message, RelayedMessage } from '@unagents/messenger-protocol';
+import { Peer, Message, RelayedMessage, StoredProtocol } from '@unagents/messenger-protocol';
 
 /**
  * Broker configuration. Every field can be given to `startBroker(options)`;
@@ -78,6 +78,8 @@ interface BrokerStateFile {
     nextMsgId: number;
     /** Relayed messages waiting for their recipient to register (absent in files written before the fallback relay). */
     pending?: PendingRelay[];
+    /** Protocol definitions (absent in files written before the protocol registry, or when none is held). */
+    protocols?: StoredProtocol[];
 }
 /** A message relayed from a fallback broker whose recipient has not registered here yet. */
 interface PendingRelay extends RelayedMessage {

package/dist/index.mjs

@@ -1,11 +1,12 @@
 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';
+export { D as DEFAULT_STATE_FILE, F as FALLBACK_ENV, a as FALLBACK_INTERVAL_ENV, M as MESH_ENV, S as STATE_DIR, V as VERSION, c as configFromEnv, r as resolveConfig, s as startBroker } from './shared/messenger-broker.B8W77sqB.mjs';
 import 'node:os';
 import 'node:path';
 import 'defu';
 import 'node:fs';
 import 'consola';
+import 'node:crypto';
 import 'node:http';
 import 'node:dgram';

package/dist/main.mjs

@@ -1,4 +1,4 @@
-import { s as startBroker, l as log } from './shared/messenger-broker.CY2SPlVR.mjs';
+import { s as startBroker, l as log } from './shared/messenger-broker.B8W77sqB.mjs';
 import 'listhen';
 import 'h3';
 import '@unagents/messenger-protocol';
@@ -7,6 +7,7 @@ import 'node:path';
 import 'defu';
 import 'node:fs';
 import 'consola';
+import 'node:crypto';
 import 'node:http';
 import 'node:dgram';
 

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

@@ -1,11 +1,12 @@
 import { listen } from 'listhen';
 import { createRouter, defineEventHandler, createApp, send, setResponseStatus, getRequestHeader, readRawBody, toNodeListener } from 'h3';
-import { DEFAULT_BIND, ENV, DEFAULT_DISCOVERY_PORT, DEFAULT_HTTP_PORT, 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 { 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';
 
@@ -54,6 +55,8 @@ class BrokerState {
   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;
@@ -68,7 +71,12 @@ class BrokerState {
       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))`);
+      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 {
     }
   }
@@ -93,7 +101,8 @@ class BrokerState {
         peers: [...this.peers.values()],
         messages: this.messages,
         nextMsgId: this.nextMsgId,
-        ...this.pending.length ? { pending: this.pending } : {}
+        ...this.pending.length ? { pending: this.pending } : {},
+        ...this.protocols.size ? { protocols: [...this.protocols.values()] } : {}
       };
       writeFileSync(tmp, JSON.stringify(snapshot, null, 1));
       renameSync(tmp, this.file);
@@ -107,6 +116,112 @@ class BrokerState {
   }
 }
 
+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;
@@ -116,6 +231,8 @@ class BrokerHandlers {
     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() {
@@ -158,6 +275,56 @@ class BrokerHandlers {
       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) {
@@ -206,7 +373,10 @@ class BrokerHandlers {
       registered_at: now,
       last_seen: now
     });
-    this.deliverPending(this.state.peers.get(id));
+    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 };
   }
@@ -214,8 +384,10 @@ class BrokerHandlers {
     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();
-    return { ok: true };
+    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);
@@ -247,6 +419,10 @@ class BrokerHandlers {
         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) {
@@ -255,6 +431,12 @@ class BrokerHandlers {
     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",
@@ -264,7 +446,8 @@ class BrokerHandlers {
       mode,
       sent_at: (/* @__PURE__ */ new Date()).toISOString(),
       delivered: 0,
-      acknowledged: 0
+      acknowledged: 0,
+      ...meta ? { meta } : {}
     };
     this.state.messages.push(msg);
     this.state.scheduleSave();
@@ -293,12 +476,99 @@ class BrokerHandlers {
   }
   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,
@@ -308,7 +578,8 @@ class BrokerHandlers {
       mode: m.mode ?? "pull",
       sent_at: m.sent_at,
       delivered: 0,
-      acknowledged: 0
+      acknowledged: 0,
+      ...meta ? { meta } : {}
     });
   }
   /** Give `peer` the relayed messages that were waiting for its name. */
@@ -384,8 +655,64 @@ class BrokerHandlers {
     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 = [];
@@ -409,8 +736,10 @@ class BrokerHandlers {
     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 ?? []);
-    return { id: this.opts.id ?? "", peers: this.meshLocalPeers(), accepted };
+    const protocols = this.meshLocalProtocols();
+    return { id: this.opts.id ?? "", peers: this.meshLocalPeers(), accepted, ...protocols.length ? { protocols } : {} };
   }
   /** Route table in `BROKER_POST_ROUTES` order. */
   routes() {
@@ -485,10 +814,12 @@ class Mesh {
     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) : []
+      messages: origin ? handlers.meshOutbox(origin) : [],
+      ...protocols.length ? { protocols } : {}
     };
     let res;
     try {
@@ -506,6 +837,7 @@ class Mesh {
     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");
@@ -552,6 +884,7 @@ function postJson(url, headers, body, timeoutMs) {
 
 function createBrokerApp(opts) {
   const routes = opts.handlers.routes();
+  const protocolRoutes = opts.handlers.protocolRoutes();
   const router = createRouter();
   router.get(HEALTH_ROUTE, defineEventHandler(() => ({
     status: "ok",
@@ -572,6 +905,7 @@ function createBrokerApp(opts) {
   }));
   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);
@@ -707,7 +1041,8 @@ async function relayUndelivered(state, url, token) {
       to_hostname: peer.hostname,
       text: m.text,
       mode: m.mode ?? "pull",
-      sent_at: m.sent_at
+      sent_at: m.sent_at,
+      ...m.meta ? { meta: m.meta } : {}
     });
   }
   let sent = 0;
@@ -719,7 +1054,7 @@ async function relayUndelivered(state, url, token) {
       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 });
+        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++;
       }
@@ -733,7 +1068,7 @@ async function relayUndelivered(state, url, token) {
   return { sent, dropped };
 }
 
-const version = "0.9.0";
+const version = "0.10.0";
 const pkg = {
 	version: version};
 

package/package.json

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