@unagents/messenger-protocol 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -56,6 +56,37 @@ declare const ENV: {
     readonly DELIVERY: "AGENT_MESSENGER_DELIVERY";
 };
 type EnvName = (typeof ENV)[keyof typeof ENV];
+/**
+ * Extra POST routes of the protocol registry. Like `RELAY_ROUTE`, not part of `BROKER_POST_ROUTES`
+ * (that table mirrors the legacy broker); request / response shapes are `ProtocolRouteMap` in `http.ts`.
+ */
+declare const PROTOCOL_ROUTES: readonly ["/set-protocol", "/unset-protocol", "/get-protocol"];
+type ProtocolRoute = (typeof PROTOCOL_ROUTES)[number];
+/** Max size of `protocol.json` (UTF-8 bytes). */
+declare const PROTOCOL_MANIFEST_MAX_BYTES: number;
+/** Max size of `PROTOCOL.md` (UTF-8 bytes). */
+declare const PROTOCOL_DOC_MAX_BYTES: number;
+/** Max size of manifest + doc together (UTF-8 bytes). */
+declare const PROTOCOL_TOTAL_MAX_BYTES: number;
+/** Max number of `(name, version)` definitions one broker holds; more is `LIMIT`. */
+declare const PROTOCOL_MAX_STORED = 256;
+/** Max length (characters) of each of `meta.protocol` and `meta.version`. */
+declare const PROTOCOL_META_MAX_LENGTH = 128;
+/** Valid protocol `name`. */
+declare const PROTOCOL_NAME_PATTERN: RegExp;
+/**
+ * Error `code`s of the protocol feature (design 7.2). `NO_TAG` is not listed: a repo without tags is
+ * not an error (`0.0.0+<sha7>`). Raised by the broker: HASH_MISMATCH, PROTOCOL_CONFLICT, LIMIT,
+ * PROTOCOL_NOT_FOUND, and TOO_LARGE / INVALID_DEFINITION on re-check. The rest are raised by the client.
+ */
+declare const PROTOCOL_ERROR_CODES: readonly ["REPO_UNREACHABLE", "UNSUPPORTED_REPO", "VERSION_NOT_FOUND", "INVALID_DEFINITION", "VERSION_MISMATCH", "TOO_LARGE", "HASH_MISMATCH", "PROTOCOL_CONFLICT", "LIMIT", "PROTOCOL_NOT_FOUND", "BROKER_UNSUPPORTED", "INVALID_META"];
+type ProtocolErrorCode = (typeof PROTOCOL_ERROR_CODES)[number];
+/** Discovery send targets (`host:port`, comma separated). When set, probes / announces go there instead of broadcast. */
+declare const DISCOVERY_TARGETS_ENV = "AGENT_MESSENGER_DISCOVERY_TARGETS";
+/** Client state file with the saved broker (default `~/.agent-messenger/client.json`). */
+declare const CLIENT_STATE_ENV = "AGENT_MESSENGER_CLIENT_STATE";
+/** Mesh announce interval in ms (default 10000). */
+declare const MESH_ANNOUNCE_ENV = "AGENT_MESSENGER_MESH_ANNOUNCE_MS";
 
 /**
  * Broker HTTP API — request / response JSON shapes.
@@ -72,6 +103,7 @@ type EnvName = (typeof ENV)[keyof typeof ENV];
  * - Unknown POST path: `404 {"error":"not found"}`. Handler exception: `500 {"error":<message>}`.
  * - Any other method: `200 text/plain` `agent-messenger broker <version>\n`.
  */
+
 /** A registered session as stored and returned by the broker. */
 interface Peer {
     /** 8-char broker-generated id (`[a-z0-9]`). */
@@ -95,6 +127,42 @@ interface Peer {
      * registered directly. Never returned by `/list-peers`.
      */
     origin?: string;
+    /**
+     * Protocols this peer serves (`/set-protocol`, re-sent on `/register` and `/heartbeat`). Hash only; the
+     * definition body lives in the broker's protocol store. Absent when none (and from 0.9.x brokers).
+     */
+    protocols?: ProtocolDecl[];
+}
+/** A protocol a peer declares: identity (`name` + `version`) and the hash of its definition body. */
+interface ProtocolDecl {
+    /** `^[a-z0-9][a-z0-9._-]{0,63}$` (`PROTOCOL_NAME_PATTERN`). */
+    name: string;
+    /** semver, or `0.0.0+<sha7>` for a repo without tags. */
+    version: string;
+    /** `sha256(canonicalJSON({manifest, doc}))` as lower-case hex. */
+    hash: string;
+}
+/** The definition body a server fetched from its protocol repo. */
+interface ProtocolDefinition {
+    /** Parsed `protocol.json`. */
+    manifest: object;
+    /** `PROTOCOL.md` text; `""` when the repo has none. */
+    doc: string;
+    /** Normalized repo notation (`github:o/r`, `gitea:<base>/o/r`, `file:<abs path>`). Not part of the hash. */
+    source: string;
+    /** tag or sha the body was read at (`local` for a local path). Not part of the hash. */
+    ref: string;
+}
+/** What the broker keeps per `(name, version)`. */
+interface StoredProtocol extends ProtocolDecl {
+    definition: ProtocolDefinition;
+    /** ISO 8601 timestamp of the first successful `/set-protocol` for this `(name, version)`. */
+    registered_at: string;
+}
+/** Protocol tag of a message: which protocol (and version) the sender spoke. Both fields are required when present. */
+interface MessageMeta {
+    protocol: string;
+    version: string;
 }
 type MessageMode = "pull" | "push" | "ping";
 /** A message as stored and returned by the broker. */
@@ -120,6 +188,8 @@ interface Message {
     acknowledged: 0 | 1;
     /** Mesh only: `<sender broker id>:<id there>` of a message forwarded by another broker (duplicate guard). */
     mesh_key?: string;
+    /** Protocol tag given to `/send-message`; returned by `/poll-messages` and kept across relay / mesh forwarding. */
+    meta?: MessageMeta;
 }
 /** `/list-peers` scope filter. Unknown values behave as `"all"`. */
 type PeerScope = "all" | "host" | "directory" | "repo";
@@ -146,6 +216,8 @@ interface HealthResponse {
     peers: number;
     /** Present (`true`) only when the broker was started as a local fallback (`AGENT_MESSENGER_FALLBACK=1`). */
     fallback?: true;
+    /** Present (`true`) only when the broker takes part in the mesh (0.11.0). */
+    mesh?: true;
 }
 interface RegisterRequest {
     pid: number;
@@ -155,15 +227,29 @@ interface RegisterRequest {
     tty?: string | null;
     summary?: string;
     name?: string;
+    /** Protocols to declare right away (hash only; bodies follow via `/set-protocol`). */
+    protocols?: ProtocolDecl[];
 }
 interface RegisterResponse {
     id: string;
 }
 interface HeartbeatRequest {
     id: string;
+    /** Every protocol the peer currently serves (hash only), sent on each heartbeat. */
+    protocols?: ProtocolDecl[];
 }
-/** `ok:false` with `"unknown peer (re-register)"` when the broker does not know the id. */
-type HeartbeatResponse = OkResult;
+/**
+ * `ok:false` with `"unknown peer (re-register)"` when the broker does not know the id.
+ * `resend` lists the `"name@version"` of declared protocols whose body the broker does not hold; the client answers
+ * with `/set-protocol`. Absent when nothing is missing (and from 0.9.x brokers).
+ */
+type HeartbeatResponse = {
+    ok: true;
+    resend?: string[];
+} | {
+    ok: false;
+    error: string;
+};
 interface SetSummaryRequest {
     id: string;
     summary?: string;
@@ -184,6 +270,10 @@ interface ListPeersRequest {
     git_root?: string | null;
     /** Peer id to omit from the result (the caller itself). */
     exclude_id?: string;
+    /** Only peers that declare this protocol (AND with `scope`). */
+    protocol?: string;
+    /** Only with `protocol`: only peers that declare exactly this version. */
+    version?: string;
 }
 type ListPeersResponse = Peer[];
 interface SendMessageRequest {
@@ -195,6 +285,8 @@ interface SendMessageRequest {
     text?: string;
     /** Defaults to `"pull"`. Unknown values are rejected. */
     mode?: MessageMode;
+    /** Protocol tag. Both fields must be strings of at most `PROTOCOL_META_MAX_LENGTH` characters. */
+    meta?: MessageMeta;
 }
 type SendMessageResponse = {
     ok: true;
@@ -243,6 +335,7 @@ interface RelayedMessage {
     text: string;
     mode?: MessageMode;
     sent_at: string;
+    meta?: MessageMeta;
 }
 interface RelayMessagesRequest {
     messages: RelayedMessage[];
@@ -256,6 +349,72 @@ interface RelayMessagesResponse {
 }
 /** Extra POST route served by the TypeScript broker. Not in `BROKER_POST_ROUTES` (that table mirrors the legacy broker). */
 declare const RELAY_ROUTE: "/relay-messages";
+/** `{ok:false}` answer of the protocol routes; `code` is one of `PROTOCOL_ERROR_CODES`. */
+interface ProtocolErrorResponse {
+    ok: false;
+    error: string;
+    code: ProtocolErrorCode;
+    /** `PROTOCOL_CONFLICT`: hash the broker already holds for this `(name, version)`. */
+    existing_hash?: string;
+    /** `PROTOCOL_CONFLICT`: servers (`name@host`) that hold it. */
+    servers?: string[];
+    /** `PROTOCOL_NOT_FOUND`: versions the broker does hold for the name (may be empty). */
+    versions?: string[];
+}
+interface SetProtocolRequest {
+    /** Peer id of the server. */
+    id: string;
+    name: string;
+    version: string;
+    /** Re-computed by the broker; a different value is `HASH_MISMATCH`. */
+    hash: string;
+    definition: ProtocolDefinition;
+}
+/** `{ok:false, error}` without `code` only for an unknown peer id. */
+type SetProtocolResponse = {
+    ok: true;
+} | ProtocolErrorResponse | {
+    ok: false;
+    error: string;
+};
+interface UnsetProtocolRequest {
+    id: string;
+    /** Protocol to drop; all declarations of the peer when omitted. */
+    name?: string;
+}
+type UnsetProtocolResponse = {
+    ok: true;
+    removed: number;
+} | {
+    ok: false;
+    error: string;
+};
+interface GetProtocolRequest {
+    name: string;
+    /** Highest version the broker holds when omitted (`0.0.0+sha` counts as lowest). */
+    version?: string;
+}
+/** `servers` = number of alive peers (replicas included) that declare the returned protocol. */
+type GetProtocolResponse = {
+    ok: true;
+    protocol: StoredProtocol;
+    servers: number;
+} | ProtocolErrorResponse;
+/** Request / response pair per protocol route. */
+interface ProtocolRouteMap {
+    "/set-protocol": {
+        request: SetProtocolRequest;
+        response: SetProtocolResponse;
+    };
+    "/unset-protocol": {
+        request: UnsetProtocolRequest;
+        response: UnsetProtocolResponse;
+    };
+    "/get-protocol": {
+        request: GetProtocolRequest;
+        response: GetProtocolResponse;
+    };
+}
 /** The only GET route. */
 declare const HEALTH_ROUTE: "/health";
 /** POST routes, in the order of `ROUTES` in `legacy/src/broker.js`. */
@@ -319,6 +478,8 @@ interface MeshSyncRequest {
     peers: Peer[];
     /** Undelivered messages the sender holds for peers that live on the receiver. Ids are the sender's. */
     messages: Message[];
+    /** Definitions declared by the sender's direct peers. Absent from 0.9.x brokers. */
+    protocols?: StoredProtocol[];
 }
 interface MeshSyncResponse {
     /** Id of the receiving broker. */
@@ -327,6 +488,8 @@ interface MeshSyncResponse {
     peers: Peer[];
     /** Sender-side ids of the messages the receiver took over; the sender drops them. */
     accepted: number[];
+    /** Definitions declared by the receiver's direct peers. Absent from 0.9.x brokers. */
+    protocols?: StoredProtocol[];
 }
 
 /**
@@ -342,9 +505,13 @@ declare const DISCOVERY_KEY: "agent-messenger";
 declare const DISCOVERY_PROBE_VALUE: "probe";
 /** Value of `DISCOVERY_KEY` in a broker reply. */
 declare const DISCOVERY_REPLY_VALUE: "broker";
+/** Value of `DISCOVERY_KEY` in a mesh broker's self-announcement (0.11.0). */
+declare const DISCOVERY_ANNOUNCE_VALUE: "announce";
 /** Client → broadcast: `{"agent-messenger":"probe"}` */
 interface DiscoveryProbe {
     [DISCOVERY_KEY]: typeof DISCOVERY_PROBE_VALUE;
+    /** Mesh brokers add a 16 byte random hex nonce; the reply's `mac` is bound to it. Clients send none. */
+    n?: string;
 }
 /** Broker → client: `{"agent-messenger":"broker","id":..,"port":..,"version":..}` */
 interface DiscoveryReply {
@@ -357,7 +524,25 @@ interface DiscoveryReply {
     version: string;
     /** Present (`true`) only when the broker is a local fallback; clients prefer other brokers, fallbacks never relay to each other. */
     fallback?: true;
+    /** Present (`true`) only when the broker takes part in the mesh (`AGENT_MESSENGER_MESH=on`). */
+    mesh?: true;
+    /** Mesh broker only, and only when the probe carried `n`: `meshMac(token, n, id, port)`. */
+    mac?: string;
+}
+/** Mesh broker → broadcast, every `AGENT_MESSENGER_MESH_ANNOUNCE_MS`: `{"agent-messenger":"announce",id,port,version,mesh:true,ts,mac}` */
+interface DiscoveryAnnounce {
+    [DISCOVERY_KEY]: typeof DISCOVERY_ANNOUNCE_VALUE;
+    id: string;
+    port: number;
+    version: string;
+    mesh: true;
+    /** Send time (ms since epoch); also the MAC nonce (decimal string). Receivers accept `|now - ts| <= MESH_ANNOUNCE_MAX_SKEW_MS`. */
+    ts: number;
+    /** `meshMac(token, String(ts), id, port)` */
+    mac: string;
 }
+/** Announces older (or newer) than this are ignored. */
+declare const MESH_ANNOUNCE_MAX_SKEW_MS = 60000;
 /** The exact probe object sent by the client. */
 declare const DISCOVERY_PROBE: DiscoveryProbe;
 /** Default probe target when `AGENT_MESSENGER_DISCOVERY_ADDR` is unset (plus per-interface directed broadcast). */
@@ -390,5 +575,26 @@ interface SessionUserLine {
 }
 type SessionSocketLine = SessionAuthLine | SessionUserLine;
 
-export { BROKER_POST_ROUTES, DEFAULT_BIND, DEFAULT_DISCOVERY_PORT, DEFAULT_DISCOVERY_TIMEOUT_MS, DEFAULT_HTTP_PORT, DISCOVERY_BROADCAST_ADDR, DISCOVERY_KEY, DISCOVERY_PROBE, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE, ENV, HEALTH_ROUTE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, LOCAL_HOSTS, MESH_SYNC_ROUTE, POLL_INTERVAL_MS, RELAY_ROUTE, SESSION_SOCKET_ENV, SESSION_TOKEN_ENV };
-export type { AcknowledgeMessagesRequest, AcknowledgeMessagesResponse, BrokerErrorResponse, BrokerPostRoute, BrokerRequest, BrokerResponse, BrokerRouteMap, DiscoveryProbe, DiscoveryReply, EnvName, GetBufferedMessagesRequest, GetBufferedMessagesResponse, HealthResponse, HeartbeatRequest, HeartbeatResponse, ListPeersRequest, ListPeersResponse, MeshSyncRequest, MeshSyncResponse, Message, MessageMode, OkResult, Peer, PeerScope, PollMessagesRequest, PollMessagesResponse, RegisterRequest, RegisterResponse, RelayMessagesRequest, RelayMessagesResponse, RelayedMessage, SendMessageRequest, SendMessageResponse, SessionAuthLine, SessionSocketLine, SessionUserLine, SetNameRequest, SetNameResponse, SetSummaryRequest, SetSummaryResponse, UnregisterRequest, UnregisterResponse };
+/**
+ * Canonical JSON for protocol hashes: object keys in ascending (UTF-16 code unit) order at every depth,
+ * no whitespace, otherwise exactly what `JSON.stringify` writes for each value. Pure TypeScript with no
+ * Node dependency, so any runtime can import it. The hash itself,
+ * `sha256(canonicalJSON({manifest, doc}))` in lower-case hex, is computed by each side with its own
+ * sha256 (broker: `node:crypto`).
+ *
+ * Input is expected to be JSON data (what `JSON.parse` returns). As in `JSON.stringify`, an object member whose
+ * value is `undefined` / a function / a symbol is skipped, and such an array element becomes `null`.
+ */
+declare function canonicalJSON(value: unknown): string;
+
+/**
+ * Mesh membership proof (0.11.0): `hex(HMAC-SHA256(key = token, "am-mesh/1|" + nonce + "|" + id + "|" + port))`
+ * cut to 32 hex characters (128 bit). The token itself never goes on the wire. `nonce` is the probe's `n`
+ * (reply) or the announce `ts` as a decimal string (announce).
+ */
+declare function meshMac(token: string, nonce: string, id: string, port: number): string;
+/** Constant-time check of a received `mac` against the one computed with our token. */
+declare function meshMacEqual(expected: string, received: unknown): boolean;
+
+export { BROKER_POST_ROUTES, CLIENT_STATE_ENV, DEFAULT_BIND, DEFAULT_DISCOVERY_PORT, DEFAULT_DISCOVERY_TIMEOUT_MS, DEFAULT_HTTP_PORT, DISCOVERY_ANNOUNCE_VALUE, DISCOVERY_BROADCAST_ADDR, DISCOVERY_KEY, DISCOVERY_PROBE, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE, DISCOVERY_TARGETS_ENV, ENV, HEALTH_ROUTE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, LOCAL_HOSTS, MESH_ANNOUNCE_ENV, MESH_ANNOUNCE_MAX_SKEW_MS, MESH_SYNC_ROUTE, POLL_INTERVAL_MS, PROTOCOL_DOC_MAX_BYTES, PROTOCOL_ERROR_CODES, PROTOCOL_MANIFEST_MAX_BYTES, PROTOCOL_MAX_STORED, PROTOCOL_META_MAX_LENGTH, PROTOCOL_NAME_PATTERN, PROTOCOL_ROUTES, PROTOCOL_TOTAL_MAX_BYTES, RELAY_ROUTE, SESSION_SOCKET_ENV, SESSION_TOKEN_ENV, canonicalJSON, meshMac, meshMacEqual };
+export type { AcknowledgeMessagesRequest, AcknowledgeMessagesResponse, BrokerErrorResponse, BrokerPostRoute, BrokerRequest, BrokerResponse, BrokerRouteMap, DiscoveryAnnounce, DiscoveryProbe, DiscoveryReply, EnvName, GetBufferedMessagesRequest, GetBufferedMessagesResponse, GetProtocolRequest, GetProtocolResponse, HealthResponse, HeartbeatRequest, HeartbeatResponse, ListPeersRequest, ListPeersResponse, MeshSyncRequest, MeshSyncResponse, Message, MessageMeta, MessageMode, OkResult, Peer, PeerScope, PollMessagesRequest, PollMessagesResponse, ProtocolDecl, ProtocolDefinition, ProtocolErrorCode, ProtocolErrorResponse, ProtocolRoute, ProtocolRouteMap, RegisterRequest, RegisterResponse, RelayMessagesRequest, RelayMessagesResponse, RelayedMessage, SendMessageRequest, SendMessageResponse, SessionAuthLine, SessionSocketLine, SessionUserLine, SetNameRequest, SetNameResponse, SetProtocolRequest, SetProtocolResponse, SetSummaryRequest, SetSummaryResponse, StoredProtocol, UnregisterRequest, UnregisterResponse, UnsetProtocolRequest, UnsetProtocolResponse };

package/dist/index.d.ts

@@ -56,6 +56,37 @@ declare const ENV: {
     readonly DELIVERY: "AGENT_MESSENGER_DELIVERY";
 };
 type EnvName = (typeof ENV)[keyof typeof ENV];
+/**
+ * Extra POST routes of the protocol registry. Like `RELAY_ROUTE`, not part of `BROKER_POST_ROUTES`
+ * (that table mirrors the legacy broker); request / response shapes are `ProtocolRouteMap` in `http.ts`.
+ */
+declare const PROTOCOL_ROUTES: readonly ["/set-protocol", "/unset-protocol", "/get-protocol"];
+type ProtocolRoute = (typeof PROTOCOL_ROUTES)[number];
+/** Max size of `protocol.json` (UTF-8 bytes). */
+declare const PROTOCOL_MANIFEST_MAX_BYTES: number;
+/** Max size of `PROTOCOL.md` (UTF-8 bytes). */
+declare const PROTOCOL_DOC_MAX_BYTES: number;
+/** Max size of manifest + doc together (UTF-8 bytes). */
+declare const PROTOCOL_TOTAL_MAX_BYTES: number;
+/** Max number of `(name, version)` definitions one broker holds; more is `LIMIT`. */
+declare const PROTOCOL_MAX_STORED = 256;
+/** Max length (characters) of each of `meta.protocol` and `meta.version`. */
+declare const PROTOCOL_META_MAX_LENGTH = 128;
+/** Valid protocol `name`. */
+declare const PROTOCOL_NAME_PATTERN: RegExp;
+/**
+ * Error `code`s of the protocol feature (design 7.2). `NO_TAG` is not listed: a repo without tags is
+ * not an error (`0.0.0+<sha7>`). Raised by the broker: HASH_MISMATCH, PROTOCOL_CONFLICT, LIMIT,
+ * PROTOCOL_NOT_FOUND, and TOO_LARGE / INVALID_DEFINITION on re-check. The rest are raised by the client.
+ */
+declare const PROTOCOL_ERROR_CODES: readonly ["REPO_UNREACHABLE", "UNSUPPORTED_REPO", "VERSION_NOT_FOUND", "INVALID_DEFINITION", "VERSION_MISMATCH", "TOO_LARGE", "HASH_MISMATCH", "PROTOCOL_CONFLICT", "LIMIT", "PROTOCOL_NOT_FOUND", "BROKER_UNSUPPORTED", "INVALID_META"];
+type ProtocolErrorCode = (typeof PROTOCOL_ERROR_CODES)[number];
+/** Discovery send targets (`host:port`, comma separated). When set, probes / announces go there instead of broadcast. */
+declare const DISCOVERY_TARGETS_ENV = "AGENT_MESSENGER_DISCOVERY_TARGETS";
+/** Client state file with the saved broker (default `~/.agent-messenger/client.json`). */
+declare const CLIENT_STATE_ENV = "AGENT_MESSENGER_CLIENT_STATE";
+/** Mesh announce interval in ms (default 10000). */
+declare const MESH_ANNOUNCE_ENV = "AGENT_MESSENGER_MESH_ANNOUNCE_MS";
 
 /**
  * Broker HTTP API — request / response JSON shapes.
@@ -72,6 +103,7 @@ type EnvName = (typeof ENV)[keyof typeof ENV];
  * - Unknown POST path: `404 {"error":"not found"}`. Handler exception: `500 {"error":<message>}`.
  * - Any other method: `200 text/plain` `agent-messenger broker <version>\n`.
  */
+
 /** A registered session as stored and returned by the broker. */
 interface Peer {
     /** 8-char broker-generated id (`[a-z0-9]`). */
@@ -95,6 +127,42 @@ interface Peer {
      * registered directly. Never returned by `/list-peers`.
      */
     origin?: string;
+    /**
+     * Protocols this peer serves (`/set-protocol`, re-sent on `/register` and `/heartbeat`). Hash only; the
+     * definition body lives in the broker's protocol store. Absent when none (and from 0.9.x brokers).
+     */
+    protocols?: ProtocolDecl[];
+}
+/** A protocol a peer declares: identity (`name` + `version`) and the hash of its definition body. */
+interface ProtocolDecl {
+    /** `^[a-z0-9][a-z0-9._-]{0,63}$` (`PROTOCOL_NAME_PATTERN`). */
+    name: string;
+    /** semver, or `0.0.0+<sha7>` for a repo without tags. */
+    version: string;
+    /** `sha256(canonicalJSON({manifest, doc}))` as lower-case hex. */
+    hash: string;
+}
+/** The definition body a server fetched from its protocol repo. */
+interface ProtocolDefinition {
+    /** Parsed `protocol.json`. */
+    manifest: object;
+    /** `PROTOCOL.md` text; `""` when the repo has none. */
+    doc: string;
+    /** Normalized repo notation (`github:o/r`, `gitea:<base>/o/r`, `file:<abs path>`). Not part of the hash. */
+    source: string;
+    /** tag or sha the body was read at (`local` for a local path). Not part of the hash. */
+    ref: string;
+}
+/** What the broker keeps per `(name, version)`. */
+interface StoredProtocol extends ProtocolDecl {
+    definition: ProtocolDefinition;
+    /** ISO 8601 timestamp of the first successful `/set-protocol` for this `(name, version)`. */
+    registered_at: string;
+}
+/** Protocol tag of a message: which protocol (and version) the sender spoke. Both fields are required when present. */
+interface MessageMeta {
+    protocol: string;
+    version: string;
 }
 type MessageMode = "pull" | "push" | "ping";
 /** A message as stored and returned by the broker. */
@@ -120,6 +188,8 @@ interface Message {
     acknowledged: 0 | 1;
     /** Mesh only: `<sender broker id>:<id there>` of a message forwarded by another broker (duplicate guard). */
     mesh_key?: string;
+    /** Protocol tag given to `/send-message`; returned by `/poll-messages` and kept across relay / mesh forwarding. */
+    meta?: MessageMeta;
 }
 /** `/list-peers` scope filter. Unknown values behave as `"all"`. */
 type PeerScope = "all" | "host" | "directory" | "repo";
@@ -146,6 +216,8 @@ interface HealthResponse {
     peers: number;
     /** Present (`true`) only when the broker was started as a local fallback (`AGENT_MESSENGER_FALLBACK=1`). */
     fallback?: true;
+    /** Present (`true`) only when the broker takes part in the mesh (0.11.0). */
+    mesh?: true;
 }
 interface RegisterRequest {
     pid: number;
@@ -155,15 +227,29 @@ interface RegisterRequest {
     tty?: string | null;
     summary?: string;
     name?: string;
+    /** Protocols to declare right away (hash only; bodies follow via `/set-protocol`). */
+    protocols?: ProtocolDecl[];
 }
 interface RegisterResponse {
     id: string;
 }
 interface HeartbeatRequest {
     id: string;
+    /** Every protocol the peer currently serves (hash only), sent on each heartbeat. */
+    protocols?: ProtocolDecl[];
 }
-/** `ok:false` with `"unknown peer (re-register)"` when the broker does not know the id. */
-type HeartbeatResponse = OkResult;
+/**
+ * `ok:false` with `"unknown peer (re-register)"` when the broker does not know the id.
+ * `resend` lists the `"name@version"` of declared protocols whose body the broker does not hold; the client answers
+ * with `/set-protocol`. Absent when nothing is missing (and from 0.9.x brokers).
+ */
+type HeartbeatResponse = {
+    ok: true;
+    resend?: string[];
+} | {
+    ok: false;
+    error: string;
+};
 interface SetSummaryRequest {
     id: string;
     summary?: string;
@@ -184,6 +270,10 @@ interface ListPeersRequest {
     git_root?: string | null;
     /** Peer id to omit from the result (the caller itself). */
     exclude_id?: string;
+    /** Only peers that declare this protocol (AND with `scope`). */
+    protocol?: string;
+    /** Only with `protocol`: only peers that declare exactly this version. */
+    version?: string;
 }
 type ListPeersResponse = Peer[];
 interface SendMessageRequest {
@@ -195,6 +285,8 @@ interface SendMessageRequest {
     text?: string;
     /** Defaults to `"pull"`. Unknown values are rejected. */
     mode?: MessageMode;
+    /** Protocol tag. Both fields must be strings of at most `PROTOCOL_META_MAX_LENGTH` characters. */
+    meta?: MessageMeta;
 }
 type SendMessageResponse = {
     ok: true;
@@ -243,6 +335,7 @@ interface RelayedMessage {
     text: string;
     mode?: MessageMode;
     sent_at: string;
+    meta?: MessageMeta;
 }
 interface RelayMessagesRequest {
     messages: RelayedMessage[];
@@ -256,6 +349,72 @@ interface RelayMessagesResponse {
 }
 /** Extra POST route served by the TypeScript broker. Not in `BROKER_POST_ROUTES` (that table mirrors the legacy broker). */
 declare const RELAY_ROUTE: "/relay-messages";
+/** `{ok:false}` answer of the protocol routes; `code` is one of `PROTOCOL_ERROR_CODES`. */
+interface ProtocolErrorResponse {
+    ok: false;
+    error: string;
+    code: ProtocolErrorCode;
+    /** `PROTOCOL_CONFLICT`: hash the broker already holds for this `(name, version)`. */
+    existing_hash?: string;
+    /** `PROTOCOL_CONFLICT`: servers (`name@host`) that hold it. */
+    servers?: string[];
+    /** `PROTOCOL_NOT_FOUND`: versions the broker does hold for the name (may be empty). */
+    versions?: string[];
+}
+interface SetProtocolRequest {
+    /** Peer id of the server. */
+    id: string;
+    name: string;
+    version: string;
+    /** Re-computed by the broker; a different value is `HASH_MISMATCH`. */
+    hash: string;
+    definition: ProtocolDefinition;
+}
+/** `{ok:false, error}` without `code` only for an unknown peer id. */
+type SetProtocolResponse = {
+    ok: true;
+} | ProtocolErrorResponse | {
+    ok: false;
+    error: string;
+};
+interface UnsetProtocolRequest {
+    id: string;
+    /** Protocol to drop; all declarations of the peer when omitted. */
+    name?: string;
+}
+type UnsetProtocolResponse = {
+    ok: true;
+    removed: number;
+} | {
+    ok: false;
+    error: string;
+};
+interface GetProtocolRequest {
+    name: string;
+    /** Highest version the broker holds when omitted (`0.0.0+sha` counts as lowest). */
+    version?: string;
+}
+/** `servers` = number of alive peers (replicas included) that declare the returned protocol. */
+type GetProtocolResponse = {
+    ok: true;
+    protocol: StoredProtocol;
+    servers: number;
+} | ProtocolErrorResponse;
+/** Request / response pair per protocol route. */
+interface ProtocolRouteMap {
+    "/set-protocol": {
+        request: SetProtocolRequest;
+        response: SetProtocolResponse;
+    };
+    "/unset-protocol": {
+        request: UnsetProtocolRequest;
+        response: UnsetProtocolResponse;
+    };
+    "/get-protocol": {
+        request: GetProtocolRequest;
+        response: GetProtocolResponse;
+    };
+}
 /** The only GET route. */
 declare const HEALTH_ROUTE: "/health";
 /** POST routes, in the order of `ROUTES` in `legacy/src/broker.js`. */
@@ -319,6 +478,8 @@ interface MeshSyncRequest {
     peers: Peer[];
     /** Undelivered messages the sender holds for peers that live on the receiver. Ids are the sender's. */
     messages: Message[];
+    /** Definitions declared by the sender's direct peers. Absent from 0.9.x brokers. */
+    protocols?: StoredProtocol[];
 }
 interface MeshSyncResponse {
     /** Id of the receiving broker. */
@@ -327,6 +488,8 @@ interface MeshSyncResponse {
     peers: Peer[];
     /** Sender-side ids of the messages the receiver took over; the sender drops them. */
     accepted: number[];
+    /** Definitions declared by the receiver's direct peers. Absent from 0.9.x brokers. */
+    protocols?: StoredProtocol[];
 }
 
 /**
@@ -342,9 +505,13 @@ declare const DISCOVERY_KEY: "agent-messenger";
 declare const DISCOVERY_PROBE_VALUE: "probe";
 /** Value of `DISCOVERY_KEY` in a broker reply. */
 declare const DISCOVERY_REPLY_VALUE: "broker";
+/** Value of `DISCOVERY_KEY` in a mesh broker's self-announcement (0.11.0). */
+declare const DISCOVERY_ANNOUNCE_VALUE: "announce";
 /** Client → broadcast: `{"agent-messenger":"probe"}` */
 interface DiscoveryProbe {
     [DISCOVERY_KEY]: typeof DISCOVERY_PROBE_VALUE;
+    /** Mesh brokers add a 16 byte random hex nonce; the reply's `mac` is bound to it. Clients send none. */
+    n?: string;
 }
 /** Broker → client: `{"agent-messenger":"broker","id":..,"port":..,"version":..}` */
 interface DiscoveryReply {
@@ -357,7 +524,25 @@ interface DiscoveryReply {
     version: string;
     /** Present (`true`) only when the broker is a local fallback; clients prefer other brokers, fallbacks never relay to each other. */
     fallback?: true;
+    /** Present (`true`) only when the broker takes part in the mesh (`AGENT_MESSENGER_MESH=on`). */
+    mesh?: true;
+    /** Mesh broker only, and only when the probe carried `n`: `meshMac(token, n, id, port)`. */
+    mac?: string;
+}
+/** Mesh broker → broadcast, every `AGENT_MESSENGER_MESH_ANNOUNCE_MS`: `{"agent-messenger":"announce",id,port,version,mesh:true,ts,mac}` */
+interface DiscoveryAnnounce {
+    [DISCOVERY_KEY]: typeof DISCOVERY_ANNOUNCE_VALUE;
+    id: string;
+    port: number;
+    version: string;
+    mesh: true;
+    /** Send time (ms since epoch); also the MAC nonce (decimal string). Receivers accept `|now - ts| <= MESH_ANNOUNCE_MAX_SKEW_MS`. */
+    ts: number;
+    /** `meshMac(token, String(ts), id, port)` */
+    mac: string;
 }
+/** Announces older (or newer) than this are ignored. */
+declare const MESH_ANNOUNCE_MAX_SKEW_MS = 60000;
 /** The exact probe object sent by the client. */
 declare const DISCOVERY_PROBE: DiscoveryProbe;
 /** Default probe target when `AGENT_MESSENGER_DISCOVERY_ADDR` is unset (plus per-interface directed broadcast). */
@@ -390,5 +575,26 @@ interface SessionUserLine {
 }
 type SessionSocketLine = SessionAuthLine | SessionUserLine;
 
-export { BROKER_POST_ROUTES, DEFAULT_BIND, DEFAULT_DISCOVERY_PORT, DEFAULT_DISCOVERY_TIMEOUT_MS, DEFAULT_HTTP_PORT, DISCOVERY_BROADCAST_ADDR, DISCOVERY_KEY, DISCOVERY_PROBE, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE, ENV, HEALTH_ROUTE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, LOCAL_HOSTS, MESH_SYNC_ROUTE, POLL_INTERVAL_MS, RELAY_ROUTE, SESSION_SOCKET_ENV, SESSION_TOKEN_ENV };
-export type { AcknowledgeMessagesRequest, AcknowledgeMessagesResponse, BrokerErrorResponse, BrokerPostRoute, BrokerRequest, BrokerResponse, BrokerRouteMap, DiscoveryProbe, DiscoveryReply, EnvName, GetBufferedMessagesRequest, GetBufferedMessagesResponse, HealthResponse, HeartbeatRequest, HeartbeatResponse, ListPeersRequest, ListPeersResponse, MeshSyncRequest, MeshSyncResponse, Message, MessageMode, OkResult, Peer, PeerScope, PollMessagesRequest, PollMessagesResponse, RegisterRequest, RegisterResponse, RelayMessagesRequest, RelayMessagesResponse, RelayedMessage, SendMessageRequest, SendMessageResponse, SessionAuthLine, SessionSocketLine, SessionUserLine, SetNameRequest, SetNameResponse, SetSummaryRequest, SetSummaryResponse, UnregisterRequest, UnregisterResponse };
+/**
+ * Canonical JSON for protocol hashes: object keys in ascending (UTF-16 code unit) order at every depth,
+ * no whitespace, otherwise exactly what `JSON.stringify` writes for each value. Pure TypeScript with no
+ * Node dependency, so any runtime can import it. The hash itself,
+ * `sha256(canonicalJSON({manifest, doc}))` in lower-case hex, is computed by each side with its own
+ * sha256 (broker: `node:crypto`).
+ *
+ * Input is expected to be JSON data (what `JSON.parse` returns). As in `JSON.stringify`, an object member whose
+ * value is `undefined` / a function / a symbol is skipped, and such an array element becomes `null`.
+ */
+declare function canonicalJSON(value: unknown): string;
+
+/**
+ * Mesh membership proof (0.11.0): `hex(HMAC-SHA256(key = token, "am-mesh/1|" + nonce + "|" + id + "|" + port))`
+ * cut to 32 hex characters (128 bit). The token itself never goes on the wire. `nonce` is the probe's `n`
+ * (reply) or the announce `ts` as a decimal string (announce).
+ */
+declare function meshMac(token: string, nonce: string, id: string, port: number): string;
+/** Constant-time check of a received `mac` against the one computed with our token. */
+declare function meshMacEqual(expected: string, received: unknown): boolean;
+
+export { BROKER_POST_ROUTES, CLIENT_STATE_ENV, DEFAULT_BIND, DEFAULT_DISCOVERY_PORT, DEFAULT_DISCOVERY_TIMEOUT_MS, DEFAULT_HTTP_PORT, DISCOVERY_ANNOUNCE_VALUE, DISCOVERY_BROADCAST_ADDR, DISCOVERY_KEY, DISCOVERY_PROBE, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE, DISCOVERY_TARGETS_ENV, ENV, HEALTH_ROUTE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, LOCAL_HOSTS, MESH_ANNOUNCE_ENV, MESH_ANNOUNCE_MAX_SKEW_MS, MESH_SYNC_ROUTE, POLL_INTERVAL_MS, PROTOCOL_DOC_MAX_BYTES, PROTOCOL_ERROR_CODES, PROTOCOL_MANIFEST_MAX_BYTES, PROTOCOL_MAX_STORED, PROTOCOL_META_MAX_LENGTH, PROTOCOL_NAME_PATTERN, PROTOCOL_ROUTES, PROTOCOL_TOTAL_MAX_BYTES, RELAY_ROUTE, SESSION_SOCKET_ENV, SESSION_TOKEN_ENV, canonicalJSON, meshMac, meshMacEqual };
+export type { AcknowledgeMessagesRequest, AcknowledgeMessagesResponse, BrokerErrorResponse, BrokerPostRoute, BrokerRequest, BrokerResponse, BrokerRouteMap, DiscoveryAnnounce, DiscoveryProbe, DiscoveryReply, EnvName, GetBufferedMessagesRequest, GetBufferedMessagesResponse, GetProtocolRequest, GetProtocolResponse, HealthResponse, HeartbeatRequest, HeartbeatResponse, ListPeersRequest, ListPeersResponse, MeshSyncRequest, MeshSyncResponse, Message, MessageMeta, MessageMode, OkResult, Peer, PeerScope, PollMessagesRequest, PollMessagesResponse, ProtocolDecl, ProtocolDefinition, ProtocolErrorCode, ProtocolErrorResponse, ProtocolRoute, ProtocolRouteMap, RegisterRequest, RegisterResponse, RelayMessagesRequest, RelayMessagesResponse, RelayedMessage, SendMessageRequest, SendMessageResponse, SessionAuthLine, SessionSocketLine, SessionUserLine, SetNameRequest, SetNameResponse, SetProtocolRequest, SetProtocolResponse, SetSummaryRequest, SetSummaryResponse, StoredProtocol, UnregisterRequest, UnregisterResponse, UnsetProtocolRequest, UnsetProtocolResponse };

package/dist/index.mjs

@@ -1,3 +1,5 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
 const DEFAULT_HTTP_PORT = 7901;
 const DEFAULT_BIND = "0.0.0.0";
 const DEFAULT_DISCOVERY_PORT = 7902;
@@ -36,6 +38,30 @@ const ENV = {
   /** Inbound delivery mode: `"auto"` (default) / `"socket"` / `"channel"`. */
   DELIVERY: "AGENT_MESSENGER_DELIVERY"
 };
+const PROTOCOL_ROUTES = ["/set-protocol", "/unset-protocol", "/get-protocol"];
+const PROTOCOL_MANIFEST_MAX_BYTES = 64 * 1024;
+const PROTOCOL_DOC_MAX_BYTES = 64 * 1024;
+const PROTOCOL_TOTAL_MAX_BYTES = 128 * 1024;
+const PROTOCOL_MAX_STORED = 256;
+const PROTOCOL_META_MAX_LENGTH = 128;
+const PROTOCOL_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const PROTOCOL_ERROR_CODES = [
+  "REPO_UNREACHABLE",
+  "UNSUPPORTED_REPO",
+  "VERSION_NOT_FOUND",
+  "INVALID_DEFINITION",
+  "VERSION_MISMATCH",
+  "TOO_LARGE",
+  "HASH_MISMATCH",
+  "PROTOCOL_CONFLICT",
+  "LIMIT",
+  "PROTOCOL_NOT_FOUND",
+  "BROKER_UNSUPPORTED",
+  "INVALID_META"
+];
+const DISCOVERY_TARGETS_ENV = "AGENT_MESSENGER_DISCOVERY_TARGETS";
+const CLIENT_STATE_ENV = "AGENT_MESSENGER_CLIENT_STATE";
+const MESH_ANNOUNCE_ENV = "AGENT_MESSENGER_MESH_ANNOUNCE_MS";
 
 const RELAY_ROUTE = "/relay-messages";
 const HEALTH_ROUTE = "/health";
@@ -56,10 +82,39 @@ const MESH_SYNC_ROUTE = "/mesh/sync";
 const DISCOVERY_KEY = "agent-messenger";
 const DISCOVERY_PROBE_VALUE = "probe";
 const DISCOVERY_REPLY_VALUE = "broker";
+const DISCOVERY_ANNOUNCE_VALUE = "announce";
+const MESH_ANNOUNCE_MAX_SKEW_MS = 6e4;
 const DISCOVERY_PROBE = { [DISCOVERY_KEY]: DISCOVERY_PROBE_VALUE };
 const DISCOVERY_BROADCAST_ADDR = "255.255.255.255";
 
 const SESSION_SOCKET_ENV = "CLAUDE_CODE_MESSAGING_SOCKET";
 const SESSION_TOKEN_ENV = "CLAUDE_CODE_MESSAGING_TOKEN";
 
-export { BROKER_POST_ROUTES, DEFAULT_BIND, DEFAULT_DISCOVERY_PORT, DEFAULT_DISCOVERY_TIMEOUT_MS, DEFAULT_HTTP_PORT, DISCOVERY_BROADCAST_ADDR, DISCOVERY_KEY, DISCOVERY_PROBE, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE, ENV, HEALTH_ROUTE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, LOCAL_HOSTS, MESH_SYNC_ROUTE, POLL_INTERVAL_MS, RELAY_ROUTE, SESSION_SOCKET_ENV, SESSION_TOKEN_ENV };
+function canonicalJSON(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value) ?? "null";
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => canonicalJSON(v)).join(",")}]`;
+  }
+  const obj = value;
+  const parts = [];
+  for (const k of Object.keys(obj).sort()) {
+    const v = obj[k];
+    if (v === void 0 || typeof v === "function" || typeof v === "symbol") continue;
+    parts.push(`${JSON.stringify(k)}:${canonicalJSON(v)}`);
+  }
+  return `{${parts.join(",")}}`;
+}
+
+function meshMac(token, nonce, id, port) {
+  return createHmac("sha256", token).update(`am-mesh/1|${nonce}|${id}|${port}`).digest("hex").slice(0, 32);
+}
+function meshMacEqual(expected, received) {
+  if (typeof received !== "string") return false;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(received);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+
+export { BROKER_POST_ROUTES, CLIENT_STATE_ENV, DEFAULT_BIND, DEFAULT_DISCOVERY_PORT, DEFAULT_DISCOVERY_TIMEOUT_MS, DEFAULT_HTTP_PORT, DISCOVERY_ANNOUNCE_VALUE, DISCOVERY_BROADCAST_ADDR, DISCOVERY_KEY, DISCOVERY_PROBE, DISCOVERY_PROBE_VALUE, DISCOVERY_REPLY_VALUE, DISCOVERY_TARGETS_ENV, ENV, HEALTH_ROUTE, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, LOCAL_HOSTS, MESH_ANNOUNCE_ENV, MESH_ANNOUNCE_MAX_SKEW_MS, MESH_SYNC_ROUTE, POLL_INTERVAL_MS, PROTOCOL_DOC_MAX_BYTES, PROTOCOL_ERROR_CODES, PROTOCOL_MANIFEST_MAX_BYTES, PROTOCOL_MAX_STORED, PROTOCOL_META_MAX_LENGTH, PROTOCOL_NAME_PATTERN, PROTOCOL_ROUTES, PROTOCOL_TOTAL_MAX_BYTES, RELAY_ROUTE, SESSION_SOCKET_ENV, SESSION_TOKEN_ENV, canonicalJSON, meshMac, meshMacEqual };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unagents/messenger-protocol",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "agent-messenger protocol: types and constants shared by broker, client and CLI. No runtime logic.",
   "type": "module",
   "license": "MIT",