@unagents/messenger-protocol 0.0.0-stage → 0.9.0

package/dist/index.d.mts

@@ -0,0 +1,394 @@
+/**
+ * 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];
+
+/**
+ * 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;
+}
+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;
+}
+/** `/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;
+}
+interface RegisterResponse {
+    id: string;
+}
+interface HeartbeatRequest {
+    id: string;
+}
+/** `ok:false` with `"unknown peer (re-register)"` when the broker does not know the id. */
+type HeartbeatResponse = OkResult;
+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;
+}
+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;
+}
+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;
+}
+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";
+/** 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[];
+}
+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[];
+}
+
+/**
+ * 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;
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,394 @@
+/**
+ * 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];
+
+/**
+ * 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;
+}
+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;
+}
+/** `/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;
+}
+interface RegisterResponse {
+    id: string;
+}
+interface HeartbeatRequest {
+    id: string;
+}
+/** `ok:false` with `"unknown peer (re-register)"` when the broker does not know the id. */
+type HeartbeatResponse = OkResult;
+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;
+}
+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;
+}
+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;
+}
+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";
+/** 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[];
+}
+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[];
+}
+
+/**
+ * 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;
+
+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 };

package/dist/index.mjs

@@ -0,0 +1,65 @@
+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 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";
+
+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 };

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.9.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.