@unagents/messenger-protocol 0.0.0-stage → 0.10.0

package/dist/index.d.mts

@@ -0,0 +1,561 @@
+/**
+ * Protocol constants shared by broker, client and CLI.
+ *
+ * Values are transcribed from the current JavaScript implementation
+ * (`legacy/src/config.js`, `legacy/src/broker.js`, `legacy/src/server.js`). Do not change them here
+ * without changing the implementation on both ends.
+ */
+/** Broker HTTP listen port (`AGENT_MESSENGER_PORT` default). */
+declare const DEFAULT_HTTP_PORT = 7901;
+/** Broker HTTP bind address (`AGENT_MESSENGER_BIND` default). */
+declare const DEFAULT_BIND = "0.0.0.0";
+/** UDP discovery port (`AGENT_MESSENGER_DISCOVERY_PORT` default). */
+declare const DEFAULT_DISCOVERY_PORT = 7902;
+/** How long a client waits for discovery answers (`AGENT_MESSENGER_DISCOVERY_TIMEOUT_MS` default). */
+declare const DEFAULT_DISCOVERY_TIMEOUT_MS = 1000;
+/** Client heartbeat interval (`AGENT_MESSENGER_HEARTBEAT_MS` default). */
+declare const HEARTBEAT_INTERVAL_MS = 15000;
+/** Broker drops a peer whose `last_seen` is older than this. Not configurable. */
+declare const HEARTBEAT_TIMEOUT_MS = 60000;
+/** Client `/poll-messages` interval. Not configurable. */
+declare const POLL_INTERVAL_MS = 1000;
+/** Loopback hosts treated as "local broker" by the client resolver. */
+declare const LOCAL_HOSTS: readonly ["127.0.0.1", "localhost", "::1"];
+/**
+ * Environment variable names. Source of truth: `legacy/src/config.js`
+ * (`DELIVERY` lives in `legacy/src/server.js`).
+ */
+declare const ENV: {
+    /** Explicit broker host. `"auto"` or unset = resolve by config / discovery / local. */
+    readonly HOST: "AGENT_MESSENGER_HOST";
+    /** Broker HTTP port (client target / broker listen). */
+    readonly PORT: "AGENT_MESSENGER_PORT";
+    /** Broker bind address. */
+    readonly BIND: "AGENT_MESSENGER_BIND";
+    /** Bearer token; when set, every POST must carry `Authorization: Bearer <token>`. */
+    readonly TOKEN: "AGENT_MESSENGER_TOKEN";
+    /** Peer name for this session. */
+    readonly NAME: "AGENT_MESSENGER_NAME";
+    /** Broker id shown in `/health` and discovery replies (default hostname). */
+    readonly BROKER_ID: "AGENT_MESSENGER_BROKER_ID";
+    /** Broker state file (default `~/.agent-messenger/broker.json`). */
+    readonly STATE: "AGENT_MESSENGER_STATE";
+    /** Client config file (default `~/.agent-messenger/config.json`). */
+    readonly CONFIG: "AGENT_MESSENGER_CONFIG";
+    /** `"off"` disables UDP discovery (broker responder and client probe). */
+    readonly DISCOVERY: "AGENT_MESSENGER_DISCOVERY";
+    /** UDP discovery port. */
+    readonly DISCOVERY_PORT: "AGENT_MESSENGER_DISCOVERY_PORT";
+    /** Discovery probe target address. */
+    readonly DISCOVERY_ADDR: "AGENT_MESSENGER_DISCOVERY_ADDR";
+    /** Discovery answer wait time in ms. */
+    readonly DISCOVERY_TIMEOUT_MS: "AGENT_MESSENGER_DISCOVERY_TIMEOUT_MS";
+    /** Client heartbeat interval in ms. */
+    readonly HEARTBEAT_MS: "AGENT_MESSENGER_HEARTBEAT_MS";
+    /** Inbound delivery mode: `"auto"` (default) / `"socket"` / `"channel"`. */
+    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.
+ *
+ * Transcribed from `legacy/src/broker.js` (handlers) and `legacy/src/server.js` /
+ * `legacy/bin/agent-messenger.js` (callers). Field optionality follows the broker:
+ * a field the broker defaults with `??` is optional here.
+ *
+ * Transport rules (from `legacy/src/broker.js` `startBroker`):
+ * - `GET /health` is the only GET route.
+ * - Every other route is `POST` with a JSON body; empty body is treated as `{}`.
+ * - When the broker has a token, each POST must send `Authorization: Bearer <token>`,
+ *   otherwise `401 {"error":"unauthorized"}`.
+ * - 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]`). */
+    id: string;
+    /** Stable name set via `/register` or `/set-name`; `""` when unset. */
+    name: string;
+    /** Client process id. */
+    pid: number;
+    hostname: string;
+    cwd: string;
+    git_root: string | null;
+    tty: string | null;
+    summary: string;
+    /** ISO 8601 timestamp. */
+    registered_at: string;
+    /** ISO 8601 timestamp; refreshed by `/heartbeat`. */
+    last_seen: string;
+    /**
+     * Mesh only: id of the permanent broker this peer is registered with, set on
+     * copies a mesh broker replicated from another one. Absent for peers that
+     * 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. */
+interface Message {
+    /** Broker-assigned incrementing integer. */
+    id: number;
+    /** Sender peer id, or `"cli"` when sent from the CLI. */
+    from_id: string;
+    from_name: string;
+    to_id: string;
+    text: string;
+    /**
+     * How the receiver shows it: `"pull"` = unread notice only, text via
+     * `check_messages`; `"push"` = text shown directly; `"ping"` = liveness
+     * notice; `text` is its optional subject (e.g. a task id), `""` when none. Missing (older broker / sender) means `"pull"`.
+     */
+    mode?: MessageMode;
+    /** ISO 8601 timestamp. */
+    sent_at: string;
+    /** 0 until returned by `/poll-messages`, then 1. */
+    delivered: 0 | 1;
+    /** Always 0 in the current implementation (acknowledged messages are deleted). */
+    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";
+/** Generic `{ok:true}` / `{ok:false,error}` result. */
+type OkResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Body of a non-2xx broker response. */
+interface BrokerErrorResponse {
+    error: string;
+}
+interface HealthResponse {
+    status: "ok";
+    /** Broker package version. */
+    version: string;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+    /** Broker HTTP port. */
+    port: number;
+    /** Count of peers seen within `HEARTBEAT_TIMEOUT_MS`. */
+    peers: number;
+    /** Present (`true`) only when the broker was started as a local fallback (`AGENT_MESSENGER_FALLBACK=1`). */
+    fallback?: true;
+}
+interface RegisterRequest {
+    pid: number;
+    hostname?: string;
+    cwd?: string;
+    git_root?: string | null;
+    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.
+ * `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;
+}
+type SetSummaryResponse = OkResult;
+interface SetNameRequest {
+    id: string;
+    name?: string;
+}
+type SetNameResponse = OkResult;
+interface ListPeersRequest {
+    scope?: PeerScope;
+    /** Used by scope `"host"`. */
+    hostname?: string;
+    /** Used by scope `"directory"`, and by `"repo"` when `git_root` is empty. */
+    cwd?: string;
+    /** Used by scope `"repo"`. */
+    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 {
+    /** Target peer id or unique peer name. */
+    to: string;
+    /** Defaults to `"cli"`. */
+    from_id?: string;
+    from_name?: string;
+    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;
+    to_id: string;
+    to_name: string;
+    message_id: number;
+} | {
+    ok: false;
+    error: string;
+};
+interface PollMessagesRequest {
+    id: string;
+}
+/** Undelivered messages for `id`; each is marked `delivered: 1` on return. */
+interface PollMessagesResponse {
+    messages: Message[];
+}
+interface AcknowledgeMessagesRequest {
+    id: string;
+    message_ids?: number[];
+}
+type AcknowledgeMessagesResponse = {
+    ok: true;
+};
+interface GetBufferedMessagesRequest {
+    id: string;
+}
+/** Messages for `id` with `delivered: 1` and `acknowledged: 0`. */
+interface GetBufferedMessagesResponse {
+    messages: Message[];
+}
+interface UnregisterRequest {
+    id: string;
+}
+type UnregisterResponse = {
+    ok: true;
+};
+/** One undelivered message handed over by a fallback broker. The recipient is addressed by name: peer ids are broker-local. */
+interface RelayedMessage {
+    from_id: string;
+    from_name: string;
+    /** Recipient peer name on the sending broker. Items without a name cannot be relayed. */
+    to_name: string;
+    /** Recipient hostname on the sending broker; narrows ambiguous names. */
+    to_hostname?: string;
+    text: string;
+    mode?: MessageMode;
+    sent_at: string;
+    meta?: MessageMeta;
+}
+interface RelayMessagesRequest {
+    messages: RelayedMessage[];
+}
+/** `delivered` = queued for a registered peer, `queued` = held until a peer of that name registers, `dropped` = no usable name. */
+interface RelayMessagesResponse {
+    ok: true;
+    delivered: number;
+    queued: number;
+    dropped: number;
+}
+/** 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`. */
+declare const BROKER_POST_ROUTES: readonly ["/register", "/heartbeat", "/set-summary", "/set-name", "/list-peers", "/send-message", "/poll-messages", "/acknowledge-messages", "/get-buffered-messages", "/unregister"];
+type BrokerPostRoute = (typeof BROKER_POST_ROUTES)[number];
+/** Request / response pair per POST route. */
+interface BrokerRouteMap {
+    "/register": {
+        request: RegisterRequest;
+        response: RegisterResponse;
+    };
+    "/heartbeat": {
+        request: HeartbeatRequest;
+        response: HeartbeatResponse;
+    };
+    "/set-summary": {
+        request: SetSummaryRequest;
+        response: SetSummaryResponse;
+    };
+    "/set-name": {
+        request: SetNameRequest;
+        response: SetNameResponse;
+    };
+    "/list-peers": {
+        request: ListPeersRequest;
+        response: ListPeersResponse;
+    };
+    "/send-message": {
+        request: SendMessageRequest;
+        response: SendMessageResponse;
+    };
+    "/poll-messages": {
+        request: PollMessagesRequest;
+        response: PollMessagesResponse;
+    };
+    "/acknowledge-messages": {
+        request: AcknowledgeMessagesRequest;
+        response: AcknowledgeMessagesResponse;
+    };
+    "/get-buffered-messages": {
+        request: GetBufferedMessagesRequest;
+        response: GetBufferedMessagesResponse;
+    };
+    "/unregister": {
+        request: UnregisterRequest;
+        response: UnregisterResponse;
+    };
+}
+type BrokerRequest<R extends BrokerPostRoute> = BrokerRouteMap[R]["request"];
+type BrokerResponse<R extends BrokerPostRoute> = BrokerRouteMap[R]["response"];
+/** Broker-to-broker sync route. Old brokers answer 404 and are simply not part of the mesh. */
+declare const MESH_SYNC_ROUTE: "/mesh/sync";
+/**
+ * POST /mesh/sync — one round of peer / message replication, sent by each
+ * mesh broker to every other one.
+ */
+interface MeshSyncRequest {
+    /** Id of the sending broker (= `origin` of the peers below). */
+    from: string;
+    /** Live peers that registered directly with the sender (replaces what the receiver holds for `from`). */
+    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. */
+    id: string;
+    /** Live peers that registered directly with the receiver. */
+    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[];
+}
+
+/**
+ * UDP LAN discovery — probe / reply JSON shapes.
+ *
+ * Transcribed from `legacy/src/resolve.js` (`discoverBrokers`) and `legacy/src/broker.js`
+ * (discovery responder). Both packets are single JSON objects; the broker's
+ * address is the reply packet's UDP source address.
+ */
+/** JSON key present in both probe and reply. */
+declare const DISCOVERY_KEY: "agent-messenger";
+/** Value of `DISCOVERY_KEY` in a client probe. */
+declare const DISCOVERY_PROBE_VALUE: "probe";
+/** Value of `DISCOVERY_KEY` in a broker reply. */
+declare const DISCOVERY_REPLY_VALUE: "broker";
+/** Client → broadcast: `{"agent-messenger":"probe"}` */
+interface DiscoveryProbe {
+    [DISCOVERY_KEY]: typeof DISCOVERY_PROBE_VALUE;
+}
+/** Broker → client: `{"agent-messenger":"broker","id":..,"port":..,"version":..}` */
+interface DiscoveryReply {
+    [DISCOVERY_KEY]: typeof DISCOVERY_REPLY_VALUE;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+    /** Broker HTTP port. */
+    port: number;
+    /** Broker package version. */
+    version: string;
+    /** Present (`true`) only when the broker is a local fallback; clients prefer other brokers, fallbacks never relay to each other. */
+    fallback?: true;
+}
+/** 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). */
+declare const DISCOVERY_BROADCAST_ADDR = "255.255.255.255";
+
+/**
+ * Claude Code session inbox socket — line shapes.
+ *
+ * Transcribed from `legacy/src/server.js` (`postToSession`). The client connects to
+ * the unix socket named by `CLAUDE_CODE_MESSAGING_SOCKET`, writes one JSON
+ * object per line (`\n` terminated), then half-closes:
+ *
+ *   1. `{"type":"auth","token":<CLAUDE_CODE_MESSAGING_TOKEN>}`   only when the token is set
+ *   2. `{"type":"user","message":{"role":"user","content":<text>}}`
+ */
+/** Environment variable holding the session socket path. */
+declare const SESSION_SOCKET_ENV = "CLAUDE_CODE_MESSAGING_SOCKET";
+/** Environment variable holding the session socket auth token. */
+declare const SESSION_TOKEN_ENV = "CLAUDE_CODE_MESSAGING_TOKEN";
+interface SessionAuthLine {
+    type: "auth";
+    token: string;
+}
+interface SessionUserLine {
+    type: "user";
+    message: {
+        role: "user";
+        content: string;
+    };
+}
+type SessionSocketLine = SessionAuthLine | SessionUserLine;
+
+/**
+ * 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

@@ -0,0 +1,561 @@
+/**
+ * Protocol constants shared by broker, client and CLI.
+ *
+ * Values are transcribed from the current JavaScript implementation
+ * (`legacy/src/config.js`, `legacy/src/broker.js`, `legacy/src/server.js`). Do not change them here
+ * without changing the implementation on both ends.
+ */
+/** Broker HTTP listen port (`AGENT_MESSENGER_PORT` default). */
+declare const DEFAULT_HTTP_PORT = 7901;
+/** Broker HTTP bind address (`AGENT_MESSENGER_BIND` default). */
+declare const DEFAULT_BIND = "0.0.0.0";
+/** UDP discovery port (`AGENT_MESSENGER_DISCOVERY_PORT` default). */
+declare const DEFAULT_DISCOVERY_PORT = 7902;
+/** How long a client waits for discovery answers (`AGENT_MESSENGER_DISCOVERY_TIMEOUT_MS` default). */
+declare const DEFAULT_DISCOVERY_TIMEOUT_MS = 1000;
+/** Client heartbeat interval (`AGENT_MESSENGER_HEARTBEAT_MS` default). */
+declare const HEARTBEAT_INTERVAL_MS = 15000;
+/** Broker drops a peer whose `last_seen` is older than this. Not configurable. */
+declare const HEARTBEAT_TIMEOUT_MS = 60000;
+/** Client `/poll-messages` interval. Not configurable. */
+declare const POLL_INTERVAL_MS = 1000;
+/** Loopback hosts treated as "local broker" by the client resolver. */
+declare const LOCAL_HOSTS: readonly ["127.0.0.1", "localhost", "::1"];
+/**
+ * Environment variable names. Source of truth: `legacy/src/config.js`
+ * (`DELIVERY` lives in `legacy/src/server.js`).
+ */
+declare const ENV: {
+    /** Explicit broker host. `"auto"` or unset = resolve by config / discovery / local. */
+    readonly HOST: "AGENT_MESSENGER_HOST";
+    /** Broker HTTP port (client target / broker listen). */
+    readonly PORT: "AGENT_MESSENGER_PORT";
+    /** Broker bind address. */
+    readonly BIND: "AGENT_MESSENGER_BIND";
+    /** Bearer token; when set, every POST must carry `Authorization: Bearer <token>`. */
+    readonly TOKEN: "AGENT_MESSENGER_TOKEN";
+    /** Peer name for this session. */
+    readonly NAME: "AGENT_MESSENGER_NAME";
+    /** Broker id shown in `/health` and discovery replies (default hostname). */
+    readonly BROKER_ID: "AGENT_MESSENGER_BROKER_ID";
+    /** Broker state file (default `~/.agent-messenger/broker.json`). */
+    readonly STATE: "AGENT_MESSENGER_STATE";
+    /** Client config file (default `~/.agent-messenger/config.json`). */
+    readonly CONFIG: "AGENT_MESSENGER_CONFIG";
+    /** `"off"` disables UDP discovery (broker responder and client probe). */
+    readonly DISCOVERY: "AGENT_MESSENGER_DISCOVERY";
+    /** UDP discovery port. */
+    readonly DISCOVERY_PORT: "AGENT_MESSENGER_DISCOVERY_PORT";
+    /** Discovery probe target address. */
+    readonly DISCOVERY_ADDR: "AGENT_MESSENGER_DISCOVERY_ADDR";
+    /** Discovery answer wait time in ms. */
+    readonly DISCOVERY_TIMEOUT_MS: "AGENT_MESSENGER_DISCOVERY_TIMEOUT_MS";
+    /** Client heartbeat interval in ms. */
+    readonly HEARTBEAT_MS: "AGENT_MESSENGER_HEARTBEAT_MS";
+    /** Inbound delivery mode: `"auto"` (default) / `"socket"` / `"channel"`. */
+    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.
+ *
+ * Transcribed from `legacy/src/broker.js` (handlers) and `legacy/src/server.js` /
+ * `legacy/bin/agent-messenger.js` (callers). Field optionality follows the broker:
+ * a field the broker defaults with `??` is optional here.
+ *
+ * Transport rules (from `legacy/src/broker.js` `startBroker`):
+ * - `GET /health` is the only GET route.
+ * - Every other route is `POST` with a JSON body; empty body is treated as `{}`.
+ * - When the broker has a token, each POST must send `Authorization: Bearer <token>`,
+ *   otherwise `401 {"error":"unauthorized"}`.
+ * - 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]`). */
+    id: string;
+    /** Stable name set via `/register` or `/set-name`; `""` when unset. */
+    name: string;
+    /** Client process id. */
+    pid: number;
+    hostname: string;
+    cwd: string;
+    git_root: string | null;
+    tty: string | null;
+    summary: string;
+    /** ISO 8601 timestamp. */
+    registered_at: string;
+    /** ISO 8601 timestamp; refreshed by `/heartbeat`. */
+    last_seen: string;
+    /**
+     * Mesh only: id of the permanent broker this peer is registered with, set on
+     * copies a mesh broker replicated from another one. Absent for peers that
+     * 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. */
+interface Message {
+    /** Broker-assigned incrementing integer. */
+    id: number;
+    /** Sender peer id, or `"cli"` when sent from the CLI. */
+    from_id: string;
+    from_name: string;
+    to_id: string;
+    text: string;
+    /**
+     * How the receiver shows it: `"pull"` = unread notice only, text via
+     * `check_messages`; `"push"` = text shown directly; `"ping"` = liveness
+     * notice; `text` is its optional subject (e.g. a task id), `""` when none. Missing (older broker / sender) means `"pull"`.
+     */
+    mode?: MessageMode;
+    /** ISO 8601 timestamp. */
+    sent_at: string;
+    /** 0 until returned by `/poll-messages`, then 1. */
+    delivered: 0 | 1;
+    /** Always 0 in the current implementation (acknowledged messages are deleted). */
+    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";
+/** Generic `{ok:true}` / `{ok:false,error}` result. */
+type OkResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Body of a non-2xx broker response. */
+interface BrokerErrorResponse {
+    error: string;
+}
+interface HealthResponse {
+    status: "ok";
+    /** Broker package version. */
+    version: string;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+    /** Broker HTTP port. */
+    port: number;
+    /** Count of peers seen within `HEARTBEAT_TIMEOUT_MS`. */
+    peers: number;
+    /** Present (`true`) only when the broker was started as a local fallback (`AGENT_MESSENGER_FALLBACK=1`). */
+    fallback?: true;
+}
+interface RegisterRequest {
+    pid: number;
+    hostname?: string;
+    cwd?: string;
+    git_root?: string | null;
+    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.
+ * `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;
+}
+type SetSummaryResponse = OkResult;
+interface SetNameRequest {
+    id: string;
+    name?: string;
+}
+type SetNameResponse = OkResult;
+interface ListPeersRequest {
+    scope?: PeerScope;
+    /** Used by scope `"host"`. */
+    hostname?: string;
+    /** Used by scope `"directory"`, and by `"repo"` when `git_root` is empty. */
+    cwd?: string;
+    /** Used by scope `"repo"`. */
+    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 {
+    /** Target peer id or unique peer name. */
+    to: string;
+    /** Defaults to `"cli"`. */
+    from_id?: string;
+    from_name?: string;
+    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;
+    to_id: string;
+    to_name: string;
+    message_id: number;
+} | {
+    ok: false;
+    error: string;
+};
+interface PollMessagesRequest {
+    id: string;
+}
+/** Undelivered messages for `id`; each is marked `delivered: 1` on return. */
+interface PollMessagesResponse {
+    messages: Message[];
+}
+interface AcknowledgeMessagesRequest {
+    id: string;
+    message_ids?: number[];
+}
+type AcknowledgeMessagesResponse = {
+    ok: true;
+};
+interface GetBufferedMessagesRequest {
+    id: string;
+}
+/** Messages for `id` with `delivered: 1` and `acknowledged: 0`. */
+interface GetBufferedMessagesResponse {
+    messages: Message[];
+}
+interface UnregisterRequest {
+    id: string;
+}
+type UnregisterResponse = {
+    ok: true;
+};
+/** One undelivered message handed over by a fallback broker. The recipient is addressed by name: peer ids are broker-local. */
+interface RelayedMessage {
+    from_id: string;
+    from_name: string;
+    /** Recipient peer name on the sending broker. Items without a name cannot be relayed. */
+    to_name: string;
+    /** Recipient hostname on the sending broker; narrows ambiguous names. */
+    to_hostname?: string;
+    text: string;
+    mode?: MessageMode;
+    sent_at: string;
+    meta?: MessageMeta;
+}
+interface RelayMessagesRequest {
+    messages: RelayedMessage[];
+}
+/** `delivered` = queued for a registered peer, `queued` = held until a peer of that name registers, `dropped` = no usable name. */
+interface RelayMessagesResponse {
+    ok: true;
+    delivered: number;
+    queued: number;
+    dropped: number;
+}
+/** 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`. */
+declare const BROKER_POST_ROUTES: readonly ["/register", "/heartbeat", "/set-summary", "/set-name", "/list-peers", "/send-message", "/poll-messages", "/acknowledge-messages", "/get-buffered-messages", "/unregister"];
+type BrokerPostRoute = (typeof BROKER_POST_ROUTES)[number];
+/** Request / response pair per POST route. */
+interface BrokerRouteMap {
+    "/register": {
+        request: RegisterRequest;
+        response: RegisterResponse;
+    };
+    "/heartbeat": {
+        request: HeartbeatRequest;
+        response: HeartbeatResponse;
+    };
+    "/set-summary": {
+        request: SetSummaryRequest;
+        response: SetSummaryResponse;
+    };
+    "/set-name": {
+        request: SetNameRequest;
+        response: SetNameResponse;
+    };
+    "/list-peers": {
+        request: ListPeersRequest;
+        response: ListPeersResponse;
+    };
+    "/send-message": {
+        request: SendMessageRequest;
+        response: SendMessageResponse;
+    };
+    "/poll-messages": {
+        request: PollMessagesRequest;
+        response: PollMessagesResponse;
+    };
+    "/acknowledge-messages": {
+        request: AcknowledgeMessagesRequest;
+        response: AcknowledgeMessagesResponse;
+    };
+    "/get-buffered-messages": {
+        request: GetBufferedMessagesRequest;
+        response: GetBufferedMessagesResponse;
+    };
+    "/unregister": {
+        request: UnregisterRequest;
+        response: UnregisterResponse;
+    };
+}
+type BrokerRequest<R extends BrokerPostRoute> = BrokerRouteMap[R]["request"];
+type BrokerResponse<R extends BrokerPostRoute> = BrokerRouteMap[R]["response"];
+/** Broker-to-broker sync route. Old brokers answer 404 and are simply not part of the mesh. */
+declare const MESH_SYNC_ROUTE: "/mesh/sync";
+/**
+ * POST /mesh/sync — one round of peer / message replication, sent by each
+ * mesh broker to every other one.
+ */
+interface MeshSyncRequest {
+    /** Id of the sending broker (= `origin` of the peers below). */
+    from: string;
+    /** Live peers that registered directly with the sender (replaces what the receiver holds for `from`). */
+    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. */
+    id: string;
+    /** Live peers that registered directly with the receiver. */
+    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[];
+}
+
+/**
+ * UDP LAN discovery — probe / reply JSON shapes.
+ *
+ * Transcribed from `legacy/src/resolve.js` (`discoverBrokers`) and `legacy/src/broker.js`
+ * (discovery responder). Both packets are single JSON objects; the broker's
+ * address is the reply packet's UDP source address.
+ */
+/** JSON key present in both probe and reply. */
+declare const DISCOVERY_KEY: "agent-messenger";
+/** Value of `DISCOVERY_KEY` in a client probe. */
+declare const DISCOVERY_PROBE_VALUE: "probe";
+/** Value of `DISCOVERY_KEY` in a broker reply. */
+declare const DISCOVERY_REPLY_VALUE: "broker";
+/** Client → broadcast: `{"agent-messenger":"probe"}` */
+interface DiscoveryProbe {
+    [DISCOVERY_KEY]: typeof DISCOVERY_PROBE_VALUE;
+}
+/** Broker → client: `{"agent-messenger":"broker","id":..,"port":..,"version":..}` */
+interface DiscoveryReply {
+    [DISCOVERY_KEY]: typeof DISCOVERY_REPLY_VALUE;
+    /** Broker id (`AGENT_MESSENGER_BROKER_ID`, default hostname). */
+    id: string;
+    /** Broker HTTP port. */
+    port: number;
+    /** Broker package version. */
+    version: string;
+    /** Present (`true`) only when the broker is a local fallback; clients prefer other brokers, fallbacks never relay to each other. */
+    fallback?: true;
+}
+/** 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). */
+declare const DISCOVERY_BROADCAST_ADDR = "255.255.255.255";
+
+/**
+ * Claude Code session inbox socket — line shapes.
+ *
+ * Transcribed from `legacy/src/server.js` (`postToSession`). The client connects to
+ * the unix socket named by `CLAUDE_CODE_MESSAGING_SOCKET`, writes one JSON
+ * object per line (`\n` terminated), then half-closes:
+ *
+ *   1. `{"type":"auth","token":<CLAUDE_CODE_MESSAGING_TOKEN>}`   only when the token is set
+ *   2. `{"type":"user","message":{"role":"user","content":<text>}}`
+ */
+/** Environment variable holding the session socket path. */
+declare const SESSION_SOCKET_ENV = "CLAUDE_CODE_MESSAGING_SOCKET";
+/** Environment variable holding the session socket auth token. */
+declare const SESSION_TOKEN_ENV = "CLAUDE_CODE_MESSAGING_TOKEN";
+interface SessionAuthLine {
+    type: "auth";
+    token: string;
+}
+interface SessionUserLine {
+    type: "user";
+    message: {
+        role: "user";
+        content: string;
+    };
+}
+type SessionSocketLine = SessionAuthLine | SessionUserLine;
+
+/**
+ * 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

@@ -0,0 +1,103 @@
+const DEFAULT_HTTP_PORT = 7901;
+const DEFAULT_BIND = "0.0.0.0";
+const DEFAULT_DISCOVERY_PORT = 7902;
+const DEFAULT_DISCOVERY_TIMEOUT_MS = 1e3;
+const HEARTBEAT_INTERVAL_MS = 15e3;
+const HEARTBEAT_TIMEOUT_MS = 6e4;
+const POLL_INTERVAL_MS = 1e3;
+const LOCAL_HOSTS = ["127.0.0.1", "localhost", "::1"];
+const ENV = {
+  /** Explicit broker host. `"auto"` or unset = resolve by config / discovery / local. */
+  HOST: "AGENT_MESSENGER_HOST",
+  /** Broker HTTP port (client target / broker listen). */
+  PORT: "AGENT_MESSENGER_PORT",
+  /** Broker bind address. */
+  BIND: "AGENT_MESSENGER_BIND",
+  /** Bearer token; when set, every POST must carry `Authorization: Bearer <token>`. */
+  TOKEN: "AGENT_MESSENGER_TOKEN",
+  /** Peer name for this session. */
+  NAME: "AGENT_MESSENGER_NAME",
+  /** Broker id shown in `/health` and discovery replies (default hostname). */
+  BROKER_ID: "AGENT_MESSENGER_BROKER_ID",
+  /** Broker state file (default `~/.agent-messenger/broker.json`). */
+  STATE: "AGENT_MESSENGER_STATE",
+  /** Client config file (default `~/.agent-messenger/config.json`). */
+  CONFIG: "AGENT_MESSENGER_CONFIG",
+  /** `"off"` disables UDP discovery (broker responder and client probe). */
+  DISCOVERY: "AGENT_MESSENGER_DISCOVERY",
+  /** UDP discovery port. */
+  DISCOVERY_PORT: "AGENT_MESSENGER_DISCOVERY_PORT",
+  /** Discovery probe target address. */
+  DISCOVERY_ADDR: "AGENT_MESSENGER_DISCOVERY_ADDR",
+  /** Discovery answer wait time in ms. */
+  DISCOVERY_TIMEOUT_MS: "AGENT_MESSENGER_DISCOVERY_TIMEOUT_MS",
+  /** Client heartbeat interval in ms. */
+  HEARTBEAT_MS: "AGENT_MESSENGER_HEARTBEAT_MS",
+  /** 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";
+const BROKER_POST_ROUTES = [
+  "/register",
+  "/heartbeat",
+  "/set-summary",
+  "/set-name",
+  "/list-peers",
+  "/send-message",
+  "/poll-messages",
+  "/acknowledge-messages",
+  "/get-buffered-messages",
+  "/unregister"
+];
+const MESH_SYNC_ROUTE = "/mesh/sync";
+
+const DISCOVERY_KEY = "agent-messenger";
+const DISCOVERY_PROBE_VALUE = "probe";
+const DISCOVERY_REPLY_VALUE = "broker";
+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";
+
+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,29 @@
 {
   "name": "@unagents/messenger-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.10.0",
+  "description": "agent-messenger protocol: types and constants shared by broker, client and CLI. No runtime logic.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unagents/agent-messenger.git",
+    "directory": "packages/protocol"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "unbuild",
+    "typecheck": "tsgo -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/README.md

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