agent-embassy 1.4.0 → 1.5.0

package/dist/src/gateway/claude-peer.js

@@ -9,33 +9,28 @@ import { BridgeError } from "../errors.js";
 import { KeyedMutex } from "../mutex.js";
 import { createCodexRegistrationGeneration, isCodexRegistrationGeneration, } from "./codex-registration-generation.js";
 import { isDashboardLocale } from "./locale.js";
-import { sharesCompatibilityMajor } from "./compatibility.js";
+import { isCompatibilityVersionEvidence, sharesCompatibilityMajor, } from "./compatibility.js";
 /**
  * This adapter intentionally pins the inspected, implementation-specific
  * local peer boundary. The feature is documented in Claude Code, but its
  * registry and NDJSON formats are not a stable public integration contract.
  */
 export const CLAUDE_PEER_COMPATIBILITY = Object.freeze({
-    claudeCodeVersion: "2.1.226",
+    claudeCodeVersion: "2.1.227",
     peerProtocol: 1,
     messageVersion: 1,
 });
-/** Live peer records may outlive a same-protocol Claude Code upgrade. */
-export const CLAUDE_PEER_COMPATIBLE_SESSION_VERSIONS = Object.freeze([
-    "2.1.224",
-    "2.1.225",
-    "2.1.226",
-]);
+const EMBASSY_ADVERTISEMENT_VERSION = 1;
 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 ALIAS_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const CLAUDE_PEER_NOTICE_COPY = {
     en: {
-        stall: "The local gateway is still waiting to deliver the preceding message. Run `embassy status` or inspect the dashboard for details.",
-        diagnostic: "The local gateway could not deliver the preceding message. Run `embassy status` or inspect the dashboard for details.",
+        stall: "The local gateway is still waiting to deliver the preceding message. Run `embassy status` or inspect the dashboard for details. Queued mail reaches a busy recipient when its turn ends.",
+        diagnostic: "The local gateway could not deliver the preceding message. Run `embassy status` or inspect the dashboard for details. Queued mail reaches a busy recipient when its turn ends.",
     },
     "zh-CN": {
-        stall: "本地网关仍在等待投递前一条消息。运行 `embassy status` 或查看仪表盘了解详情。",
-        diagnostic: "本地网关无法投递前一条消息。运行 `embassy status` 或查看仪表盘了解详情。",
+        stall: "本地网关仍在等待投递前一条消息。运行 `embassy status` 或查看仪表盘了解详情。排队邮件会在忙碌接收方的当前轮次结束后到达。",
+        diagnostic: "本地网关无法投递前一条消息。运行 `embassy status` 或查看仪表盘了解详情。排队邮件会在忙碌接收方的当前轮次结束后到达。",
     },
 };
 const REGISTRY_FILE_PATTERN = /^([1-9][0-9]{0,9})\.json$/;
@@ -205,9 +200,25 @@ function parseRegistryRecord(value, expectedPid) {
         "name",
         "updatedAt",
     ];
-    const optional = ["nameSource", "status", "statusUpdatedAt"];
-    if (!hasExactKeys(value, required, optional))
+    if (!required.every((key) => Object.hasOwn(value, key)))
         return undefined;
+    const embassyAdvertisement = value.embassyAdvertisementVersion === EMBASSY_ADVERTISEMENT_VERSION &&
+        isCompatibilityVersionEvidence(value.version) &&
+        typeof value.name === "string" &&
+        value.name.startsWith("codex-") &&
+        ALIAS_PATTERN.test(value.name) &&
+        value.kind === "interactive" &&
+        value.entrypoint === "cli" &&
+        value.peerProtocol === CLAUDE_PEER_COMPATIBILITY.peerProtocol &&
+        value.status !== undefined &&
+        value.statusUpdatedAt !== undefined;
+    if (value.embassyAdvertisementVersion !== undefined &&
+        !embassyAdvertisement) {
+        return undefined;
+    }
+    const versionCompatible = typeof value.version === "string" &&
+        (embassyAdvertisement ||
+            sharesCompatibilityMajor(value.version, CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion));
     if (value.pid !== expectedPid)
         return undefined;
     if (typeof value.sessionId !== "string" ||
@@ -229,8 +240,7 @@ function parseRegistryRecord(value, expectedPid) {
         !isBoundedString(value.procStart, 256) ||
         value.procStart.length === 0 ||
         value.procStart.includes("\0") ||
-        typeof value.version !== "string" ||
-        !sharesCompatibilityMajor(value.version, CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion) ||
+        !versionCompatible ||
         !isBoundedString(value.entrypoint, 64) ||
         !/^[A-Za-z0-9._-]+$/.test(value.entrypoint) ||
         (value.nameSource !== undefined &&
@@ -272,6 +282,7 @@ function parseRegistryRecord(value, expectedPid) {
         // while the model turn is active. Treat that live process conservatively
         // as busy.
         status: (value.status ?? "busy"),
+        embassyAdvertisement,
     };
 }
 function parseFrame(line, maxFrameBytes) {
@@ -450,6 +461,7 @@ export class ClaudePeerAdapter {
     #listenerOwner = Object.freeze({});
     #registryMutex = new KeyedMutex();
     #registryPublicationHook;
+    #postBindHook;
     #targets = new Map();
     #workspacePolicies = new Map();
     #listeners = new Set();
@@ -457,8 +469,9 @@ export class ClaudePeerAdapter {
         if (process.platform === "win32" || process.getuid === undefined) {
             throw new BridgeError("CLAUDE_PEER_PLATFORM_UNSUPPORTED", "Claude peer sockets are supported only on macOS and Linux.");
         }
-        if (!sharesCompatibilityMajor(options.attestedClaudeCodeVersion, CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion)) {
-            throw new BridgeError("CLAUDE_PEER_VERSION_UNSUPPORTED", `Claude peer compatibility is pinned to Claude Code ${CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion}.`);
+        if (options.attestedClaudeCodeVersion !== "unknown" &&
+            !sharesCompatibilityMajor(options.attestedClaudeCodeVersion, CLAUDE_PEER_COMPATIBILITY.claudeCodeVersion)) {
+            throw new BridgeError("CLAUDE_PEER_VERSION_UNSUPPORTED", "Claude peer transport does not support this Claude Code major.");
         }
         if (options.locale !== undefined && !isDashboardLocale(options.locale)) {
             throw new BridgeError("DASHBOARD_LOCALE_UNSUPPORTED", "The Claude peer notice locale is unsupported.");
@@ -472,7 +485,7 @@ export class ClaudePeerAdapter {
         this.#deliveryNotices = options.deliveryNotices ?? "merged";
         this.#sessionsDir = assertAbsoluteConfiguredPath(options.sessionsDir, "sessionsDir");
         this.#socketDir = assertAbsoluteConfiguredPath(options.socketDir, "socketDir");
-        this.#expectedUid = process.getuid();
+        this.#expectedUid = testing.expectedUid ?? process.getuid();
         if (!Number.isSafeInteger(this.#expectedUid) || this.#expectedUid < 0) {
             throw new BridgeError("INVALID_PEER_UID", "expectedUid must be a non-negative integer.");
         }
@@ -503,13 +516,23 @@ export class ClaudePeerAdapter {
             ...(testing.tempRoots ?? ["/tmp", "/private/tmp", os.tmpdir()]),
         ].map((root) => assertAbsoluteConfiguredPath(root, "tempRoot")));
         this.#registryPublicationHook = testing.registryPublicationHook;
+        this.#postBindHook = testing.postBindHook;
     }
-    async #validatePrivateDirectory(directory) {
+    async #validateRealDirectory(directory) {
         const stat = await lstat(directory);
         if (stat.isSymbolicLink() || !stat.isDirectory()) {
             throw new BridgeError("UNSAFE_PEER_DIRECTORY", "The Claude peer directory is not an accessible real directory.");
         }
     }
+    async #validateSessionsDirectory() {
+        const stat = await lstat(this.#sessionsDir);
+        if (stat.isSymbolicLink() ||
+            !stat.isDirectory() ||
+            stat.uid !== this.#expectedUid ||
+            exactMode(stat.mode) !== 0o700) {
+            throw new BridgeError("UNSAFE_PEER_DIRECTORY", "The Claude sessions directory failed its exact owner and mode policy.");
+        }
+    }
     async #readRegistryFile(registryPath) {
         const before = await lstat(registryPath);
         if (before.isSymbolicLink() || !before.isFile()) {
@@ -579,6 +602,11 @@ export class ClaudePeerAdapter {
         if (record === undefined) {
             throw new BridgeError("REGISTRY_INVALID_SCHEMA", "Registry schema is incompatible.");
         }
+        // Embassy advertisements are addressable by Claude, never Claude delivery
+        // targets or evidence that a Claude record parsed.
+        if (record.embassyAdvertisement || expectedPid === process.pid) {
+            throw new BridgeError("SELF_TARGET", "The gateway cannot target itself.");
+        }
         onParsed?.();
         const processIdentity = await this.#inspectProcess(expectedPid);
         if (processIdentity === undefined) {
@@ -587,9 +615,6 @@ export class ClaudePeerAdapter {
         if (processIdentity.uid !== this.#expectedUid) {
             throw new BridgeError("PID_OWNER_MISMATCH", "Registry process owner is unsafe.");
         }
-        if (expectedPid === process.pid) {
-            throw new BridgeError("SELF_TARGET", "The gateway cannot target itself.");
-        }
         const socketGeneration = await this.#validateSocket(record.messagingSocketPath, expectedPid);
         return {
             // Claude's native session UUID is the logical route identity. The
@@ -607,8 +632,8 @@ export class ClaudePeerAdapter {
     }
     async discover() {
         await Promise.all([
-            this.#validatePrivateDirectory(this.#sessionsDir),
-            this.#validatePrivateDirectory(this.#socketDir),
+            this.#validateSessionsDirectory(),
+            this.#validateRealDirectory(this.#socketDir),
         ]);
         const previousTargets = [...this.#targets.values()];
         const nextTargets = new Map();
@@ -681,6 +706,8 @@ export class ClaudePeerAdapter {
                 const code = error instanceof BridgeError
                     ? error.code
                     : "REGISTRY_RACED";
+                if (code === "SELF_TARGET")
+                    continue;
                 if (claudePeerRejectionCodes.includes(code)) {
                     reject(code);
                 }
@@ -707,8 +734,8 @@ export class ClaudePeerAdapter {
     }
     async #revalidateBinding(binding) {
         await Promise.all([
-            this.#validatePrivateDirectory(this.#sessionsDir),
-            this.#validatePrivateDirectory(this.#socketDir),
+            this.#validateSessionsDirectory(),
+            this.#validateRealDirectory(this.#socketDir),
         ]);
         if (binding.expiresAt < this.#now()) {
             this.#targets.delete(binding.targetId);
@@ -846,8 +873,8 @@ export class ClaudePeerAdapter {
     }
     async #resolveReplyAddress(address) {
         await Promise.all([
-            this.#validatePrivateDirectory(this.#sessionsDir),
-            this.#validatePrivateDirectory(this.#socketDir),
+            this.#validateSessionsDirectory(),
+            this.#validateRealDirectory(this.#socketDir),
         ]);
         if (!address.startsWith("uds:")) {
             throw new BridgeError("UNREGISTERED_REPLY_ADDRESS", "Only local registered UDS reply addresses are accepted.");
@@ -886,8 +913,8 @@ export class ClaudePeerAdapter {
      */
     async resolveReplyAddress(address) {
         await Promise.all([
-            this.#validatePrivateDirectory(this.#sessionsDir),
-            this.#validatePrivateDirectory(this.#socketDir),
+            this.#validateSessionsDirectory(),
+            this.#validateRealDirectory(this.#socketDir),
         ]);
         const binding = await this.#resolveReplyAddress(address);
         return {
@@ -900,8 +927,8 @@ export class ClaudePeerAdapter {
     }
     async #listen(options, preparedGeneration) {
         await Promise.all([
-            this.#validatePrivateDirectory(this.#sessionsDir),
-            this.#validatePrivateDirectory(this.#socketDir),
+            this.#validateSessionsDirectory(),
+            this.#validateRealDirectory(this.#socketDir),
         ]);
         const generation = preparedGeneration ?? this.#createGeneration();
         if (!isCodexRegistrationGeneration(generation)) {
@@ -949,6 +976,7 @@ export class ClaudePeerAdapter {
             ...(this.#registryPublicationHook === undefined
                 ? {}
                 : { registryPublicationHook: this.#registryPublicationHook }),
+            postBindHook: this.#postBindHook,
             onClosed: () => this.#listeners.delete(listener),
         });
         this.#listeners.add(listener);
@@ -1265,6 +1293,7 @@ export class ClaudePeerListener {
                 !sameSocketGeneration({ dev: attested.dev, ino: attested.ino }, createdGeneration)) {
                 throw new BridgeError("CLAUDE_PEER_CALLBACK_UNSAFE", "The gateway callback socket did not satisfy its ownership policy.");
             }
+            await options.postBindHook?.(socketPath);
             const sessions = await lstat(options.sessionsDir);
             if (sessions.isSymbolicLink() ||
                 !sessions.isDirectory() ||
@@ -1289,11 +1318,25 @@ export class ClaudePeerListener {
                     // net.Server.close(), which deletes by pathname.
                 }
             }
+            let closeConfirmed = false;
             if (stillOwned) {
-                await new Promise((resolve) => server.close(() => resolve()));
+                try {
+                    await new Promise((resolve, reject) => server.close((closeError) => closeError === undefined ? resolve() : reject(closeError)));
+                    try {
+                        await lstat(socketPath);
+                    }
+                    catch (closeError) {
+                        closeConfirmed =
+                            closeError.code === "ENOENT";
+                    }
+                }
+                catch {
+                    // An unconfirmed close cannot safely downgrade a callback failure.
+                }
             }
-            else {
+            if (!closeConfirmed) {
                 server.unref();
+                throw new BridgeError("CLAUDE_PEER_CALLBACK_UNSAFE", "The newly bound callback socket could not be safely closed.");
             }
             throw error;
         }
@@ -1314,7 +1357,8 @@ export class ClaudePeerListener {
         return `${JSON.stringify(record)}\n`;
     }
     #recordBelongsToThisListener(record) {
-        return (record.pid === process.pid &&
+        return (record.embassyAdvertisementVersion === EMBASSY_ADVERTISEMENT_VERSION &&
+            record.pid === process.pid &&
             UUID_PATTERN.test(record.sessionId) &&
             record.messagingSocketPath === this.#socketPath &&
             record.version === this.#attestedClaudeCodeVersion &&
@@ -1485,6 +1529,7 @@ export class ClaudePeerListener {
         }
         const now = Date.now();
         return {
+            embassyAdvertisementVersion: EMBASSY_ADVERTISEMENT_VERSION,
             pid: process.pid,
             sessionId,
             cwd,