agent-embassy 1.8.2 → 1.9.2

package/dist/src/gateway/control.d.ts

@@ -1,11 +1,13 @@
 import type { GatewayPublicSnapshot } from "./types.js";
+import { type PeerCatalogResult, type PeerHandoffParams, type PeerHandoffResult } from "./peer-protocol.js";
+import { type PeerMailboxAwaitResult } from "./peer-mailbox.js";
 export declare const GATEWAY_CONTROL_PROTOCOL_VERSION: 1;
 export declare const GATEWAY_CONTROL_MAX_FRAME_BYTES: number;
 export declare const GATEWAY_CONTROL_MAX_RESPONSE_BYTES: number;
 export declare const GATEWAY_CONTROL_MAX_MESSAGE_BYTES: number;
 export declare const GATEWAY_CONTROL_DEFAULT_TIMEOUT_MS = 3000;
 export declare const GATEWAY_CONTROL_MAX_CONNECTIONS = 32;
-export declare const gatewayControlMethods: readonly ["health", "register_codex", "unregister_codex", "remove_codex_registration", "select_claude", "unselect_claude", "pair", "unpair", "list_snapshot", "observe_snapshot", "delivery_status", "untrack", "send_to_claude", "send_to_codex", "reply", "refresh_dashboard"];
+export declare const gatewayControlMethods: readonly ["health", "register_codex", "unregister_codex", "remove_codex_registration", "select_claude", "unselect_claude", "pair", "unpair", "list_snapshot", "observe_snapshot", "delivery_status", "untrack", "send_to_claude", "send_to_codex", "reply", "refresh_dashboard", "peer_catalog", "peer_handoff", "register_peer", "unregister_peer", "await_peer", "peer_receipt"];
 export type GatewayControlMethod = (typeof gatewayControlMethods)[number];
 export type GatewayBusyPolicy = "queue";
 export type RegisterCodexParams = {
@@ -51,38 +53,44 @@ export declare function pairParamThreadAttestation(params: Readonly<PairParams>)
     alias: string;
     threadId: string;
 }> | undefined;
-export type SendToClaudeParams = {
+type SendBase = {
     fromAlias: string;
-    threadId: string;
     toAlias: string;
     text: string;
     expectsReply?: boolean;
     trackIdleMinutes?: number;
 };
-export type ValidatedSendToClaudeParams = {
-    fromAlias: string;
-    threadId: string;
-    toAlias: string;
-    text: string;
+type ValidatedSendBase = Omit<SendBase, "expectsReply"> & {
     expectsReply: boolean;
-    trackIdleMinutes?: number;
-};
-export type SendToCodexParams = {
-    fromAlias: string;
-    toAlias: string;
-    text: string;
-    replyAddress?: string;
-    expectsReply?: boolean;
-    trackIdleMinutes?: number;
-};
-export type ValidatedSendToCodexParams = {
-    fromAlias: string;
-    toAlias: string;
-    text: string;
-    replyAddress?: string;
-    expectsReply: boolean;
-    trackIdleMinutes?: number;
 };
+export type SendToClaudeParams = SendBase & ({
+    threadId: string;
+    peerToken?: never;
+} | {
+    peerToken: string;
+    threadId?: never;
+});
+export type ValidatedSendToClaudeParams = ValidatedSendBase & ({
+    threadId: string;
+    peerToken?: never;
+} | {
+    peerToken: string;
+    threadId?: never;
+});
+export type SendToCodexParams = SendBase & ({
+    replyAddress: string;
+    peerToken?: never;
+} | {
+    peerToken: string;
+    replyAddress?: never;
+});
+export type ValidatedSendToCodexParams = ValidatedSendBase & ({
+    replyAddress: string;
+    peerToken?: never;
+} | {
+    peerToken: string;
+    replyAddress?: never;
+});
 export type GatewayReplyCaller = {
     kind: "codex";
     alias: string;
@@ -91,6 +99,10 @@ export type GatewayReplyCaller = {
     kind: "claude";
     alias: string;
     replyAddress?: string;
+} | {
+    kind: "peer";
+    alias: string;
+    token: string;
 };
 export type ReplyParams = {
     conversationId: string;
@@ -104,6 +116,24 @@ export type UntrackParams = {
 export type DeliveryStatusParams = {
     token: string;
 };
+export type PeerCatalogParams = {
+    peerHost: string;
+};
+export type PeerHandoffControlParams = {
+    peerHost: string;
+    handoff: PeerHandoffParams;
+};
+export type RegisterPeerParams = {
+    alias: string;
+    token?: string;
+};
+export type PeerPrincipalParams = {
+    alias: string;
+    token: string;
+};
+export type PeerReceiptParams = PeerPrincipalParams & {
+    receipt: string;
+};
 type RequestParams = {
     health: Record<string, never>;
     register_codex: RegisterCodexParams;
@@ -121,6 +151,12 @@ type RequestParams = {
     send_to_codex: SendToCodexParams;
     reply: ReplyParams;
     refresh_dashboard: Record<string, never>;
+    peer_catalog: PeerCatalogParams;
+    peer_handoff: PeerHandoffControlParams;
+    register_peer: RegisterPeerParams;
+    unregister_peer: PeerPrincipalParams;
+    await_peer: PeerPrincipalParams;
+    peer_receipt: PeerReceiptParams;
 };
 export type GatewayControlRequest = {
     [M in GatewayControlMethod]: {
@@ -136,6 +172,7 @@ export type GatewayDecision = {
 } | {
     accepted: false;
     code: Exclude<GatewayDecisionCode, "ok">;
+    ownerHost?: string;
 };
 export type GatewaySendResult = {
     accepted: true;
@@ -170,6 +207,11 @@ export type GatewaySnapshotObservation = {
     snapshotRevision: number;
     snapshot: GatewaySnapshot;
 };
+export type GatewayRegisterPeerResult = GatewayDecision | {
+    accepted: true;
+    code: "ok";
+    token: string;
+};
 type ResultByMethod = {
     health: GatewayHealthResult;
     register_codex: GatewayDecision;
@@ -187,6 +229,12 @@ type ResultByMethod = {
     send_to_codex: GatewaySendResult;
     reply: GatewaySendResult;
     refresh_dashboard: GatewayRefreshResult;
+    peer_catalog: PeerCatalogResult;
+    peer_handoff: PeerHandoffResult;
+    register_peer: GatewayRegisterPeerResult;
+    unregister_peer: GatewayDecision;
+    await_peer: PeerMailboxAwaitResult;
+    peer_receipt: GatewayDecision;
 };
 type MaybePromise<T> = T | Promise<T>;
 export type GatewayControlHandlers = {
@@ -206,6 +254,12 @@ export type GatewayControlHandlers = {
     sendToCodex: (params: Readonly<ValidatedSendToCodexParams>) => MaybePromise<GatewaySendResult>;
     reply: (params: Readonly<ReplyParams>) => MaybePromise<GatewaySendResult>;
     refreshDashboard: () => MaybePromise<GatewayRefreshResult>;
+    peerCatalog?: (params: Readonly<PeerCatalogParams>) => MaybePromise<PeerCatalogResult>;
+    peerHandoff?: (params: Readonly<PeerHandoffControlParams>) => MaybePromise<PeerHandoffResult>;
+    registerPeer: (params: Readonly<RegisterPeerParams>) => MaybePromise<GatewayRegisterPeerResult>;
+    unregisterPeer: (params: Readonly<PeerPrincipalParams>) => MaybePromise<GatewayDecision>;
+    awaitPeer: (params: Readonly<PeerPrincipalParams>) => MaybePromise<PeerMailboxAwaitResult>;
+    peerReceipt: (params: Readonly<PeerReceiptParams>) => MaybePromise<GatewayDecision>;
 };
 export type GatewayWireErrorCode = "INVALID_JSON" | "FRAME_TOO_LARGE" | "INVALID_REQUEST" | "UNSUPPORTED_VERSION" | "UNKNOWN_METHOD" | "MULTIPLE_FRAMES" | "SERVER_BUSY" | "REQUEST_TIMEOUT" | "HANDLER_FAILURE" | "INVALID_HANDLER_RESPONSE" | "RESPONSE_TOO_LARGE";
 export type GatewayControlErrorResponse = {

package/dist/src/gateway/control.js

@@ -5,6 +5,8 @@ import net from "node:net";
 import path from "node:path";
 import { TextDecoder } from "node:util";
 import { CONNECTOR_OBSERVATION_STALE_AFTER_MS, GATEWAY_PUBLIC_SNAPSHOT_BYTE_BUDGET, gatewayProviders, gatewayPublicSnapshotLimits, isGatewayProvider, isMessageDirection, isPublicRegistryObservationSnapshot, } from "./types.js";
+import { decodePeerParams, decodePeerResult } from "./peer-protocol.js";
+import { isPeerMailboxAwaitResult } from "./peer-mailbox.js";
 export const GATEWAY_CONTROL_PROTOCOL_VERSION = 1;
 export const GATEWAY_CONTROL_MAX_FRAME_BYTES = 32 * 1024;
 export const GATEWAY_CONTROL_MAX_RESPONSE_BYTES = 256 * 1024;
@@ -19,6 +21,8 @@ const ALIAS_PATTERN = /^[a-z][a-z0-9_-]{0,31}@[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const CONVERSATION_ID_PATTERN = /^conv_[A-Za-z0-9_-]{16,64}$/;
 const DELIVERY_TOKEN_PATTERN = /^dlv_[A-Za-z0-9_-]{24}$/;
+const PEER_TOKEN_PATTERN = /^peer_[A-Za-z0-9_-]{32}$/;
+const PEER_RECEIPT_PATTERN = /^prc_[A-Za-z0-9_-]{24}$/;
 const HOST_PATTERN = /^[a-z0-9](?:[a-z0-9.-]{0,61}[a-z0-9])?$/;
 const SAFE_CODE_PATTERN = /^[A-Z][A-Z0-9_]{0,63}$/;
 const PROTOCOL_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
@@ -30,7 +34,8 @@ export const gatewayControlMethods = [
     "health", "register_codex", "unregister_codex", "remove_codex_registration",
     "select_claude", "unselect_claude", "pair", "unpair", "list_snapshot",
     "observe_snapshot", "delivery_status", "untrack", "send_to_claude",
-    "send_to_codex", "reply", "refresh_dashboard",
+    "send_to_codex", "reply", "refresh_dashboard", "peer_catalog", "peer_handoff",
+    "register_peer", "unregister_peer", "await_peer", "peer_receipt",
 ];
 export function pairParamAliases(params) {
     return "aliases" in params ? params.aliases : [params.claudeAlias, params.codexAlias];
@@ -178,11 +183,62 @@ function arrayOf(value, maximum, check) {
 function positive(value) { return nonNegative(value) && value > 0; }
 function safeCode(value) { return typeof value === "string" && SAFE_CODE_PATTERN.test(value); }
 const messageText = isMessageText;
+const peerToken = (value) => typeof value === "string" && PEER_TOKEN_PATTERN.test(value);
+const peerAlias = (value) => alias(value) && value.startsWith("peer-");
 function emptyParams(value) {
     if (!isRecord(value) || !exact(value, []))
         invalid();
     return {};
 }
+function decodePeerCatalog(value) {
+    if (!shape(value, { peerHost: host }))
+        invalid();
+    return { peerHost: value.peerHost };
+}
+function decodePeerHandoff(value) {
+    if (!isRecord(value) || !exact(value, ["peerHost", "handoff"]) || !host(value.peerHost))
+        invalid();
+    try {
+        return { peerHost: value.peerHost, handoff: decodePeerParams("handoff", value.handoff) };
+    }
+    catch {
+        return invalid();
+    }
+}
+function decodeRegisterPeer(value) {
+    if (!shape(value, { alias: peerAlias }, { token: peerToken }))
+        invalid();
+    return { alias: value.alias, ...(value.token === undefined ? {} : { token: value.token }) };
+}
+function decodePeerPrincipal(value) {
+    if (!shape(value, { alias: peerAlias, token: peerToken }))
+        invalid();
+    return { alias: value.alias, token: value.token };
+}
+function decodePeerReceipt(value) {
+    if (!shape(value, { alias: peerAlias, token: peerToken,
+        receipt: (item) => typeof item === "string" && PEER_RECEIPT_PATTERN.test(item) }))
+        invalid();
+    return { alias: value.alias, token: value.token, receipt: value.receipt };
+}
+const isPeerCatalog = (value) => {
+    try {
+        decodePeerResult("catalog/get", value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isPeerHandoffResult = (value) => {
+    try {
+        decodePeerResult("handoff", value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 function decodeRegister(value) {
     if (!isRecord(value) || !exact(value, ["alias", "threadId"], ["hostId", "busyPolicy", "succeedsAlias"]) ||
         !alias(value.alias) || !value.alias.startsWith("codex-") || !uuid(value.threadId) ||
@@ -222,9 +278,7 @@ function decodePair(value) {
     if (Object.hasOwn(value, "aliases")) {
         if (!exact(value, ["aliases"], ["threadAttestation"]) || !Array.isArray(value.aliases) ||
             value.aliases.length !== 2 || !alias(value.aliases[0]) || !alias(value.aliases[1]) ||
-            value.aliases[0] === value.aliases[1] ||
-            value.aliases[0].slice(value.aliases[0].lastIndexOf("@") + 1) !==
-                value.aliases[1].slice(value.aliases[1].lastIndexOf("@") + 1))
+            value.aliases[0] === value.aliases[1])
             invalid();
         let threadAttestation;
         if (value.threadAttestation !== undefined) {
@@ -258,24 +312,29 @@ function commonSend(value, required, optional) {
     return value;
 }
 function decodeSendClaude(value) {
-    if (!isRecord(value) || !exact(value, ["fromAlias", "threadId", "toAlias", "text"], ["expectsReply", "trackIdleMinutes"]) ||
-        !alias(value.fromAlias) || !uuid(value.threadId) || typeof value.toAlias !== "string" ||
+    if (!isRecord(value) || !exact(value, ["fromAlias", "toAlias", "text"], ["threadId", "peerToken", "expectsReply", "trackIdleMinutes"]) ||
+        !alias(value.fromAlias) || (value.threadId === undefined) === (value.peerToken === undefined) ||
+        (value.threadId !== undefined && !uuid(value.threadId)) ||
+        (value.peerToken !== undefined && !peerToken(value.peerToken)) || typeof value.toAlias !== "string" ||
         !isClaudeSessionSelector(value.toAlias) || !messageText(value.text) ||
         (value.expectsReply !== undefined && typeof value.expectsReply !== "boolean") ||
         (value.trackIdleMinutes !== undefined && !trackMinutes(value.trackIdleMinutes)))
         invalid();
-    return { fromAlias: value.fromAlias, threadId: value.threadId.toLowerCase(),
+    return { fromAlias: value.fromAlias,
         toAlias: UUID_PATTERN.test(value.toAlias) ? value.toAlias.toLowerCase() : value.toAlias,
         text: value.text, expectsReply: value.expectsReply ?? false,
+        ...(typeof value.threadId === "string" ? { threadId: value.threadId.toLowerCase() } : { peerToken: value.peerToken }),
         ...(value.trackIdleMinutes === undefined ? {} : { trackIdleMinutes: value.trackIdleMinutes }) };
 }
 function decodeSendCodex(value) {
-    const row = commonSend(value, ["fromAlias", "toAlias", "text"], ["replyAddress", "expectsReply", "trackIdleMinutes"]);
-    if (row.replyAddress !== undefined &&
-        (typeof row.replyAddress !== "string" || !isGatewayReplyAddress(row.replyAddress)))
+    const row = commonSend(value, ["fromAlias", "toAlias", "text"], ["replyAddress", "peerToken", "expectsReply", "trackIdleMinutes"]);
+    if ((row.replyAddress === undefined) === (row.peerToken === undefined) ||
+        (row.replyAddress !== undefined && (typeof row.replyAddress !== "string" || !isGatewayReplyAddress(row.replyAddress))) ||
+        (row.peerToken !== undefined && !peerToken(row.peerToken)))
         invalid();
+    const replyAddress = row.replyAddress !== undefined;
     return { fromAlias: row.fromAlias, toAlias: row.toAlias, text: row.text,
-        ...(row.replyAddress === undefined ? {} : { replyAddress: row.replyAddress }),
+        ...(replyAddress ? { replyAddress: row.replyAddress } : { peerToken: row.peerToken }),
         expectsReply: row.expectsReply === true,
         ...(row.trackIdleMinutes === undefined ? {} : { trackIdleMinutes: row.trackIdleMinutes }) };
 }
@@ -290,6 +349,8 @@ function normalizeReplyCaller(value) {
         (typeof value.replyAddress === "string" && isGatewayReplyAddress(value.replyAddress))))
         return { kind: "claude", alias: value.alias,
             ...(value.replyAddress === undefined ? {} : { replyAddress: value.replyAddress }) };
+    if (value.kind === "peer" && shape(value, { kind: oneOf("peer"), alias: peerAlias, token: peerToken }))
+        return { kind: "peer", alias: value.alias, token: value.token };
     return invalid();
 }
 function decodeReply(value) {
@@ -312,7 +373,12 @@ function decodeUntrack(value) {
     return { conversationId: value.conversationId };
 }
 function isDecision(value) {
-    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "watch_owner_conflict", "route_mismatch", "busy", "unavailable", "rejected") }) && (value.accepted === true ? value.code === "ok" : value.code !== "ok");
+    return shape(value, { accepted: (item) => typeof item === "boolean", code: oneOf("ok", "not_found", "conflict", "watch_owner_conflict", "route_mismatch", "busy", "unavailable", "rejected") }, { ownerHost: host }) && (value.accepted === true
+        ? value.code === "ok" && value.ownerHost === undefined
+        : value.code !== "ok" && (value.ownerHost === undefined || value.code === "conflict"));
+}
+function isRegisterPeerResult(value) {
+    return isDecision(value) || shape(value, { accepted: oneOf(true), code: oneOf("ok"), token: peerToken });
 }
 function isHealthResult(value) {
     return shape(value, { status: oneOf("ok", "degraded"), revision: nonNegative });
@@ -356,7 +422,7 @@ function isConnectorSnapshot(value) {
 function isRouteSnapshot(value) {
     if (!shape(value, { alias, provider: isGatewayProvider, host, enabled: (item) => typeof item === "boolean",
         state: oneOf("stale", "idle", "busy", "awaiting_approval", "offline", "disabled"),
-        busyPolicy: oneOf("queue"), queueDepth: nonNegative, counters: isRouteCounters }, { lastSeenAt: iso, oldestQueuedAt: iso, safeErrorCode: safeCode }))
+        busyPolicy: oneOf("queue"), queueDepth: nonNegative, counters: isRouteCounters }, { lastSeenAt: iso, oldestQueuedAt: iso, safeErrorCode: safeCode, mutable: (item) => typeof item === "boolean" }))
         return false;
     const row = value;
     return row.alias.endsWith(`@${row.host}`) &&
@@ -369,11 +435,12 @@ function compareConsentEndpoints(left, right) {
 function isConsentEdgeSnapshot(value) {
     const endpoint = (item) => shape(item, { alias, provider: isGatewayProvider });
     if (!shape(value, { endpoints: (rows) => Array.isArray(rows) && rows.length === 2 && rows.every(endpoint),
-        host, counters: isRouteCounters }))
+        host, counters: isRouteCounters }, { mutable: (item) => typeof item === "boolean" }))
         return false;
     const [left, right] = value.endpoints;
-    return left.provider !== right.provider && left.alias !== right.alias && compareConsentEndpoints(left, right) < 0 &&
-        left.alias.endsWith(`@${value.host}`) && right.alias.endsWith(`@${value.host}`);
+    const hosts = [left.alias.slice(left.alias.lastIndexOf("@") + 1), right.alias.slice(right.alias.lastIndexOf("@") + 1)];
+    return left.alias !== right.alias && compareConsentEndpoints(left, right) < 0 &&
+        (left.provider !== right.provider || hosts[0] !== hosts[1]) && value.host === [...hosts].sort()[0];
 }
 function isAvailablePeerSnapshot(value) {
     return shape(value, { alias, provider: oneOf("claude"), host,
@@ -500,6 +567,12 @@ const descriptors = {
     delivery_status: { handler: "deliveryStatus", decode: decodeDeliveryStatus, result: isDeliveryStatusResult, mutation: false }, untrack: { handler: "untrack", decode: decodeUntrack, result: isDecision, mutation: false },
     send_to_claude: { handler: "sendToClaude", decode: decodeSendClaude, result: isSendResult, mutation: true }, send_to_codex: { handler: "sendToCodex", decode: decodeSendCodex, result: isSendResult, mutation: true },
     reply: { handler: "reply", decode: decodeReply, result: isSendResult, mutation: true }, refresh_dashboard: { handler: "refreshDashboard", decode: emptyParams, result: isRefreshResult, mutation: false },
+    peer_catalog: { handler: "peerCatalog", decode: decodePeerCatalog, result: isPeerCatalog, mutation: false },
+    peer_handoff: { handler: "peerHandoff", decode: decodePeerHandoff, result: isPeerHandoffResult, mutation: true },
+    register_peer: { handler: "registerPeer", decode: decodeRegisterPeer, result: isRegisterPeerResult, mutation: true },
+    unregister_peer: { handler: "unregisterPeer", decode: decodePeerPrincipal, result: isDecision, mutation: true },
+    await_peer: { handler: "awaitPeer", decode: decodePeerPrincipal, result: isPeerMailboxAwaitResult, mutation: false },
+    peer_receipt: { handler: "peerReceipt", decode: decodePeerReceipt, result: isDecision, mutation: true },
 };
 function parseRequestObject(value) {
     if (!isRecord(value) || !exact(value, ["protocolVersion", "method", "params"]))
@@ -887,7 +960,7 @@ export async function startGatewayControlServer(options) {
         close,
     };
 }
-function decodeResponse(method, value) {
+function decodeResponse(method, params, value) {
     if (!isRecord(value) || value.protocolVersion !== 1)
         throw controlTransportError("CONTROL_INVALID_RESPONSE");
     if (value.ok === false) {
@@ -899,6 +972,13 @@ function decodeResponse(method, value) {
     }
     if (!shape(value, { protocolVersion: oneOf(1), ok: oneOf(true), result: descriptors[method].result }))
         throw controlTransportError("CONTROL_INVALID_RESPONSE");
+    if (method === "register_peer" && isRecord(value.result) && value.result.accepted === true &&
+        Object.hasOwn(params, "token") === Object.hasOwn(value.result, "token"))
+        throw controlTransportError("CONTROL_INVALID_RESPONSE");
+    if (method === "await_peer" && isRecord(value.result) && value.result.state === "message" &&
+        JSON.parse(value.result.frame).result.toAlias !==
+            params.alias)
+        throw controlTransportError("CONTROL_INVALID_RESPONSE");
     return value;
 }
 export async function sendGatewayControlRequest(options) {
@@ -928,7 +1008,7 @@ export async function sendGatewayControlRequest(options) {
         socket.once("connect", () => { writeStarted = true; socket.write(frame); });
         void readOneFrame(socket, maximum).then((responseFrame) => {
             try {
-                const response = decodeResponse(options.request.method, decodeJson(responseFrame, "INVALID_JSON"));
+                const response = decodeResponse(options.request.method, request.params, decodeJson(responseFrame, "INVALID_JSON"));
                 if (!settled) {
                     settled = true;
                     socket.destroy();