@unagents/messenger-protocol 0.9.0 → 0.10.0

package/dist/index.d.mts

@@ -56,6 +56,31 @@ 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];
 
 /**
  * Broker HTTP API — request / response JSON shapes.
@@ -72,6 +97,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 +121,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 +182,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";
@@ -155,15 +219,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 +262,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 +277,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 +327,7 @@ interface RelayedMessage {
     text: string;
     mode?: MessageMode;
     sent_at: string;
+    meta?: MessageMeta;
 }
 interface RelayMessagesRequest {
     messages: RelayedMessage[];
@@ -256,6 +341,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 +470,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 +480,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[];
 }
 
 /**
@@ -390,5 +545,17 @@ 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;
+
+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, 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 };
+export type { AcknowledgeMessagesRequest, AcknowledgeMessagesResponse, BrokerErrorResponse, BrokerPostRoute, BrokerRequest, BrokerResponse, BrokerRouteMap, 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,31 @@ 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];
 
 /**
  * Broker HTTP API — request / response JSON shapes.
@@ -72,6 +97,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 +121,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 +182,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";
@@ -155,15 +219,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 +262,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 +277,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 +327,7 @@ interface RelayedMessage {
     text: string;
     mode?: MessageMode;
     sent_at: string;
+    meta?: MessageMeta;
 }
 interface RelayMessagesRequest {
     messages: RelayedMessage[];
@@ -256,6 +341,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 +470,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 +480,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[];
 }
 
 /**
@@ -390,5 +545,17 @@ 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;
+
+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, 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 };
+export type { AcknowledgeMessagesRequest, AcknowledgeMessagesResponse, BrokerErrorResponse, BrokerPostRoute, BrokerRequest, BrokerResponse, BrokerRouteMap, 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

@@ -36,6 +36,27 @@ 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 RELAY_ROUTE = "/relay-messages";
 const HEALTH_ROUTE = "/health";
@@ -62,4 +83,21 @@ 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(",")}}`;
+}
+
+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, 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 };

package/package.json

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