agent-embassy 3.0.0 → 3.1.0

package/dist/src/gateway/cli.js

@@ -20,7 +20,7 @@ const CLI_MAX_OUTPUT_BYTES = GATEWAY_CONTROL_MAX_RESPONSE_BYTES;
 const DELIVERY_POLL_INTERVAL_MS = 250;
 const DELIVERY_POLL_MIN_REQUEST_TIMEOUT_MS = 50;
 const PEER_AWAIT_REQUEST_TIMEOUT_MS = 35_000;
-export const EMBASSY_VERSION = "3.0.0";
+export const EMBASSY_VERSION = "3.1.0";
 // RELEASE VERSION SWEEP — every place the version lives, seven sites:
 // package.json; npm-shrinkwrap.json (two: the root and packages[""]); this
 // constant; test/gateway-cli.test.ts's literal package-version assertion; and
@@ -33,7 +33,7 @@ export const gatewayCliCommands = [
     "unregister-codex",
     "send", "reply",
     "register-peer", "unregister-peer", "await",
-    "peer-stdio",
+    "peer-stdio", "retire",
 ];
 export const gatewayCliExitCodes = Object.freeze({
     ok: 0,
@@ -60,8 +60,11 @@ Commands:
   check [--to <alias>] [--timeout <s>]
                          Round-trip self-test against a registered peer
   refresh                Rescan for Claude sessions
-  register-codex         Register or succeed a Codex task
-  unregister-codex       Unregister the current Codex task
+  retire --alias <alias> Remove a local route and report settled work
+  register-codex --alias <codex-alias> [--succeeds <old-alias>]
+                         Register or succeed a Codex task
+  unregister-codex --alias <codex-alias>
+                         Unregister the current Codex task
   register-peer --alias <peer-alias> [--token-stdin|--emit-env]
                          Register a universal shell peer
   unregister-peer --alias <peer-alias> [--token-stdin]
@@ -69,12 +72,15 @@ Commands:
   await --alias <peer-alias> [--token-stdin]
                          Wait for one peer message and acknowledge stdout
   peer-stdio             Serve the bounded federation protocol on stdin/stdout
-  send                   Send stdin to a route with --to, or to a conversation
-                         you belong to with --conversation; a discovered Claude
-                         session's route installs on its first send
+  send --from <own-alias> --to <alias-or-uuid> [--expects-reply]
+  send --from <own-alias> --conversation <token>
+                         Exactly one of --to and --conversation; body from stdin.
+                         A discovered Claude session's route installs on first send
   reply                  Deprecated alias for send --conversation
-  delivery-status        Read a delivery token
-  wait-delivery          Wait for terminal delivery status
+  delivery-status --token <delivery-token>
+                         Read a delivery token
+  wait-delivery --token <delivery-token>
+                         Wait for terminal delivery status
 
 Options:
   --token-stdin          Read the peer token as the first LF-terminated stdin line
@@ -120,7 +126,8 @@ const CLI_HINT = {
     stateSyncFailed: "nodes.json was written at {stateDir} but the directory could not be synced; start again and check the volume",
     unknownTarget: "no current route answers to that name. A Claude session is addressed by its live name: run embassy refresh, then read embassy status for the name it has now.",
     aliasCollision: "the alias names more than one live session; rename one, or address the session by UUID with --to <session-uuid>.",
-    workspaceOverlap: "that session's workspace contains the gateway state directory; move one so they no longer overlap, then retry.",
+    workspaceBroad: "that session's workspace is a filesystem root or overlaps a temporary root; reopen the session in a specific project directory outside temporary roots.",
+    workspaceUnsafe: "the session workspace or user home failed directory checks; verify access, ownership, permissions and canonical, non-symlink paths before retrying.",
     callerAliasMismatch: "--from must be the sending session's own alias; read the name embassy status shows for this session.",
     targetChanged: "the session you addressed renamed or exited while the send was being set up; run embassy refresh and address it by its current name.",
     checkNoTarget: "no Codex task is registered, so there is nothing to check. Run `embassy register-codex --alias codex-<name>@{localHost}` from inside the task, or name any current route with `embassy check --to <alias>`.",
@@ -246,7 +253,7 @@ function requireConversationId(options, name) {
         fault();
     return conversationId;
 }
-function requireClaudeSelector(options, name) {
+function requireDestinationSelector(options, name) {
     const selector = requireString(options, name);
     if (!isClaudeSessionSelector(selector))
         fault();
@@ -422,6 +429,14 @@ async function buildRequest(command, args, env, stdin, loadLocalHost) {
                 throw aliasHostFault(local, gatewayAliasHost(alias));
             return envelope("unregister_codex", { alias, threadId });
         }
+        case "retire": {
+            const options = parseOptions(args, ["alias"]);
+            count(options, 1, 1);
+            const alias = requireAlias(options, "alias"), local = await loadLocalHost();
+            if (gatewayAliasHost(alias) !== local.host)
+                throw aliasHostFault(local, gatewayAliasHost(alias));
+            return envelope("retire_route", { alias });
+        }
         case "register-peer":
         case "unregister-peer":
         case "await": {
@@ -463,7 +478,7 @@ async function buildRequest(command, args, env, stdin, loadLocalHost) {
             const conversationId = options.conversation === undefined
                 ? undefined : requireConversationId(options, "conversation");
             const toAlias = options.to === undefined
-                ? undefined : requireClaudeSelector(options, "to");
+                ? undefined : requireDestinationSelector(options, "to");
             // One target, and a conversation is always answered expecting a reply.
             if ((toAlias === undefined) === (conversationId === undefined))
                 fault();
@@ -618,8 +633,10 @@ function refusalHint(request, result) {
     const from = request.method === "send" ? request.params.fromAlias : undefined;
     if (reason === "PEER_ALIAS_COLLISION")
         return { hint: "aliasCollision" };
-    if (typeof reason === "string" && reason.startsWith("CLAUDE_PEER_WORKSPACE_"))
-        return { hint: "workspaceOverlap" };
+    if (reason === "CLAUDE_PEER_WORKSPACE_BROAD")
+        return { hint: "workspaceBroad" };
+    if (reason === "CLAUDE_PEER_WORKSPACE_UNSAFE")
+        return { hint: "workspaceUnsafe" };
     // A Codex task with no registration under its alias — every task, after a
     // private state reset — is told to register; a registration held by another
     // task is a genuine mismatch with its own remedy; a conversation answered
@@ -645,6 +662,11 @@ function writeUnknownMethodHint(stderr, code) {
     if (code === "UNKNOWN_METHOD")
         stderr.write(`[embassy] ${CLI_HINT.unknownMethod}\n`);
 }
+function reportControlFailure(command, code, stdout, stderr) {
+    writeFailure(stdout, stderr, command, code, { kind: "failure" });
+    writeUnknownMethodHint(stderr, code);
+    return gatewayCliExitCodes.failure;
+}
 function responseExitCode(response) {
     return !response.ok ? gatewayCliExitCodes.failure
         : isRejectedResult(response.result) ? gatewayCliExitCodes.rejected : gatewayCliExitCodes.ok;
@@ -1042,6 +1064,92 @@ async function runGatewayCheck(options) {
     return summarize(exitCode);
 }
 /** Run one command; foreground runners own and release their signal handlers. */
+async function runServiceCommand(args, dependencies, loadIdentity) {
+    const command = "service";
+    const env = dependencies.env ?? process.env;
+    const stdout = dependencies.stdout ?? process.stdout, stderr = dependencies.stderr ?? process.stderr;
+    const sendRequest = dependencies.sendRequest ?? sendGatewayControlRequest;
+    const validateSocket = dependencies.validateControlSocket ?? validatePrivateGatewayControlSocket;
+    const success = (result) => {
+        stdout.write(serializedOutput({ ok: true, command, result }));
+    };
+    const subcommand = args[0];
+    if (args.length !== 1)
+        fault();
+    if (subcommand !== "install" && subcommand !== "uninstall" && subcommand !== "status")
+        fault();
+    // Identity and the state directory are validated before the first
+    // launchd side effect. Loading them afterwards meant a missing
+    // inventory or an unusable state root exited 2 "request rejected"
+    // while the agent was already bootstrapped and looping.
+    const config = subcommand === "install" ? (await loadIdentity()).config : undefined;
+    const serviceDeps = {
+        homeDir: (dependencies.serviceHomeDir ?? (() => userInfo().homedir))(),
+        runLaunchctl: dependencies.runLaunchctl ?? defaultRunLaunchctl,
+        env, execPath: process.execPath, cliPath: fileURLToPath(import.meta.url),
+        uid: process.getuid(),
+        delay: dependencies.delay ?? defaultDelay, now: dependencies.now ?? monotonicNow,
+        probeHostLease: dependencies.probeHostLease ?? defaultProbeHostLease,
+    };
+    try {
+        if (subcommand === "install") {
+            const installed = await installServiceAgent(serviceDeps);
+            const health = await pollServiceHealth(config, sendRequest, validateSocket, dependencies.delay ?? defaultDelay, dependencies.now ?? monotonicNow);
+            if (!health.ok) {
+                // The agent stays installed either way: this is a report about
+                // the broker, not an install failure, so nothing is rolled back.
+                const elapsed = (health.elapsedMs / 1000).toFixed(1);
+                const decisive = SERVICE_HEALTH_DECISIVE.get(health.lastObserved);
+                writeFailure(stdout, stderr, command, "SERVICE_HEALTH_UNAVAILABLE", {
+                    retryable: decisive?.retryable ?? true, kind: decisive?.kind ?? "unavailable",
+                    detail: { lastObserved: health.lastObserved },
+                });
+                stderr.write(decisive === undefined
+                    ? `[embassy] Installed, but the broker did not answer within ${elapsed} s; last observed ${health.lastObserved}. Run \`embassy service status\` or \`embassy health\`; log: ${installed.logPath}.\n`
+                    : `[embassy] Installed, but the broker answered ${health.lastObserved} after ${elapsed} s. Run \`embassy health\` to diagnose it; log: ${installed.logPath}.\n`);
+                if (decisive?.hint !== undefined)
+                    stderr.write(hintLine(decisive.hint, env));
+                return decisive?.exitCode ?? gatewayCliExitCodes.unavailable;
+            }
+            success({ subcommand, ...installed, health });
+            return gatewayCliExitCodes.ok;
+        }
+        if (subcommand === "uninstall") {
+            success({ subcommand, ...(await uninstallServiceAgent(serviceDeps)) });
+            return gatewayCliExitCodes.ok;
+        }
+        const status = await serviceAgentStatus(serviceDeps);
+        success({ subcommand, ...status });
+        if (status.state !== "unknown")
+            return gatewayCliExitCodes.ok;
+        stderr.write(fixedStderr("unavailable"));
+        stderr.write(`[embassy] ${status.note}${status.launchctlStderr === undefined ? "" : ` launchctl: ${status.launchctlStderr}`}\n`);
+        return gatewayCliExitCodes.unavailable;
+    }
+    catch (error) {
+        // launchctl's own stderr and the instance lease's own message are the
+        // whole value of these failures; the generic handler below discards
+        // the message and reports only the code. A genuine filesystem failure
+        // on this path (an unreadable plist, an undeletable one) is a real,
+        // recoverable service failure, not an INTERNAL_ERROR — but only an
+        // errno-shaped one. A string `code` alone would also match CliFault
+        // and the lease's own spawn failures, relabelling faults that already
+        // carry a truer code of their own.
+        const errno = error !== null && typeof error === "object" &&
+            (typeof error.errno === "number" ||
+                typeof error.syscall === "string");
+        if (!(error instanceof BridgeError) && !(errno && error instanceof Error))
+            throw error;
+        const failure = error instanceof BridgeError ? error : new BridgeError("SERVICE_AGENT_FILESYSTEM_FAILED", `The service command could not complete: ${boundedServiceDetail(error.message)}`, true);
+        writeFailure(stdout, stderr, command, failure.code, {
+            retryable: failure.recoverable,
+            kind: failure.code === "SERVICE_AGENT_PATH_UNSAFE" ? "unsafe"
+                : failure.recoverable ? "unavailable" : "input",
+        });
+        stderr.write(`[embassy] ${failure.message}\n`);
+        return failure.recoverable ? gatewayCliExitCodes.unavailable : gatewayCliExitCodes.invalidInput;
+    }
+}
 export async function runGatewayCli(argv = process.argv.slice(2), dependencies = {}) {
     const env = dependencies.env ?? process.env;
     const stdin = dependencies.stdin ?? process.stdin, stdout = dependencies.stdout ?? process.stdout;
@@ -1100,7 +1208,12 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
                         },
                         handoff: async (handoff) => {
                             firstCatalog = undefined;
-                            return await request("peer_handoff", { peerHost: peerHost, handoff });
+                            const result = await request("peer_handoff", { peerHost: peerHost, handoff });
+                            if (!result.accepted)
+                                throw new PeerHandlerError({
+                                    code: -32000, message: "Peer handoff refused", data: result
+                                });
+                            return result;
                         },
                     },
                 });
@@ -1112,84 +1225,8 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
                 return gatewayCliExitCodes.unavailable;
             }
         }
-        if (command === "service") {
-            const subcommand = args[0];
-            if (args.length !== 1)
-                fault();
-            if (subcommand !== "install" && subcommand !== "uninstall" && subcommand !== "status")
-                fault();
-            // Identity and the state directory are validated before the first
-            // launchd side effect. Loading them afterwards meant a missing
-            // inventory or an unusable state root exited 2 "request rejected"
-            // while the agent was already bootstrapped and looping.
-            const config = subcommand === "install" ? (await loadIdentity()).config : undefined;
-            const serviceDeps = {
-                homeDir: (dependencies.serviceHomeDir ?? (() => userInfo().homedir))(),
-                runLaunchctl: dependencies.runLaunchctl ?? defaultRunLaunchctl,
-                env, execPath: process.execPath, cliPath: fileURLToPath(import.meta.url),
-                uid: process.getuid(),
-                delay: dependencies.delay ?? defaultDelay, now: dependencies.now ?? monotonicNow,
-                probeHostLease: dependencies.probeHostLease ?? defaultProbeHostLease,
-            };
-            try {
-                if (subcommand === "install") {
-                    const installed = await installServiceAgent(serviceDeps);
-                    const health = await pollServiceHealth(config, sendRequest, validateSocket, dependencies.delay ?? defaultDelay, dependencies.now ?? monotonicNow);
-                    if (!health.ok) {
-                        // The agent stays installed either way: this is a report about
-                        // the broker, not an install failure, so nothing is rolled back.
-                        const elapsed = (health.elapsedMs / 1000).toFixed(1);
-                        const decisive = SERVICE_HEALTH_DECISIVE.get(health.lastObserved);
-                        writeFailure(stdout, stderr, command, "SERVICE_HEALTH_UNAVAILABLE", {
-                            retryable: decisive?.retryable ?? true, kind: decisive?.kind ?? "unavailable",
-                            detail: { lastObserved: health.lastObserved },
-                        });
-                        stderr.write(decisive === undefined
-                            ? `[embassy] Installed, but the broker did not answer within ${elapsed} s; last observed ${health.lastObserved}. Run \`embassy service status\` or \`embassy health\`; log: ${installed.logPath}.\n`
-                            : `[embassy] Installed, but the broker answered ${health.lastObserved} after ${elapsed} s. Run \`embassy health\` to diagnose it; log: ${installed.logPath}.\n`);
-                        if (decisive?.hint !== undefined)
-                            stderr.write(hintLine(decisive.hint, env));
-                        return decisive?.exitCode ?? gatewayCliExitCodes.unavailable;
-                    }
-                    success({ subcommand, ...installed, health });
-                    return gatewayCliExitCodes.ok;
-                }
-                if (subcommand === "uninstall") {
-                    success({ subcommand, ...(await uninstallServiceAgent(serviceDeps)) });
-                    return gatewayCliExitCodes.ok;
-                }
-                const status = await serviceAgentStatus(serviceDeps);
-                success({ subcommand, ...status });
-                if (status.state !== "unknown")
-                    return gatewayCliExitCodes.ok;
-                stderr.write(fixedStderr("unavailable"));
-                stderr.write(`[embassy] ${status.note}${status.launchctlStderr === undefined ? "" : ` launchctl: ${status.launchctlStderr}`}\n`);
-                return gatewayCliExitCodes.unavailable;
-            }
-            catch (error) {
-                // launchctl's own stderr and the instance lease's own message are the
-                // whole value of these failures; the generic handler below discards
-                // the message and reports only the code. A genuine filesystem failure
-                // on this path (an unreadable plist, an undeletable one) is a real,
-                // recoverable service failure, not an INTERNAL_ERROR — but only an
-                // errno-shaped one. A string `code` alone would also match CliFault
-                // and the lease's own spawn failures, relabelling faults that already
-                // carry a truer code of their own.
-                const errno = error !== null && typeof error === "object" &&
-                    (typeof error.errno === "number" ||
-                        typeof error.syscall === "string");
-                if (!(error instanceof BridgeError) && !(errno && error instanceof Error))
-                    throw error;
-                const failure = error instanceof BridgeError ? error : new BridgeError("SERVICE_AGENT_FILESYSTEM_FAILED", `The service command could not complete: ${boundedServiceDetail(error.message)}`, true);
-                writeFailure(stdout, stderr, command, failure.code, {
-                    retryable: failure.recoverable,
-                    kind: failure.code === "SERVICE_AGENT_PATH_UNSAFE" ? "unsafe"
-                        : failure.recoverable ? "unavailable" : "input",
-                });
-                stderr.write(`[embassy] ${failure.message}\n`);
-                return failure.recoverable ? gatewayCliExitCodes.unavailable : gatewayCliExitCodes.invalidInput;
-            }
-        }
+        if (command === "service")
+            return await runServiceCommand(args, dependencies, loadIdentity);
         if (command === "status" || command === "watch" || command === "check") {
             // Options are parsed before anything is loaded or contacted, so an
             // unknown flag is a flat argument fault with no side effect at all.
@@ -1199,7 +1236,7 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
             count(options, 0, 2);
             const recent = boundedOption(options, "recent", STATUS_RECENT.default, STATUS_RECENT.minimum, STATUS_RECENT.maximum);
             const timeoutSeconds = boundedOption(options, "timeout", CHECK_TIMEOUT_DEFAULT_SECONDS, 1, CHECK_TIMEOUT_MAX_SECONDS);
-            const target = options.to === undefined ? undefined : requireClaudeSelector(options, "to");
+            const target = options.to === undefined ? undefined : requireDestinationSelector(options, "to");
             const { config } = await loadIdentity();
             await validateSocket(config.stateDir, config.controlSocketPath);
             const ask = async (method, params) => await sendRequest({
@@ -1215,9 +1252,7 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
                 // The header reports how old the scan is and offers `embassy refresh`.
                 const response = await ask("list_snapshot", {});
                 if (!response.ok) {
-                    writeFailure(stdout, stderr, command, response.error.code, { kind: "failure" });
-                    writeUnknownMethodHint(stderr, response.error.code);
-                    return gatewayCliExitCodes.failure;
+                    return reportControlFailure(command, response.error.code, stdout, stderr);
                 }
                 if (options.json === true || !isTerminal(stdout)) {
                     success(response.result);
@@ -1242,9 +1277,7 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
                     while (!interrupt.signal.aborted) {
                         const observed = await ask("observe_snapshot", {});
                         if (!observed.ok) {
-                            writeFailure(stdout, stderr, command, observed.error.code, { kind: "failure" });
-                            writeUnknownMethodHint(stderr, observed.error.code);
-                            return gatewayCliExitCodes.failure;
+                            return reportControlFailure(command, observed.error.code, stdout, stderr);
                         }
                         if (observed.result.snapshotRevision !== revision) {
                             revision = observed.result.snapshotRevision;
@@ -1274,9 +1307,7 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
             if (chosen === undefined) {
                 const snapshot = await ask("list_snapshot", {});
                 if (!snapshot.ok) {
-                    writeFailure(stdout, stderr, command, snapshot.error.code, { kind: "failure" });
-                    writeUnknownMethodHint(stderr, snapshot.error.code);
-                    return gatewayCliExitCodes.failure;
+                    return reportControlFailure(command, snapshot.error.code, stdout, stderr);
                 }
                 const candidates = snapshot.result.routes
                     .filter((route) => route.provider === "codex" && route.enabled)
@@ -1400,9 +1431,7 @@ export async function runGatewayCli(argv = process.argv.slice(2), dependencies =
             response = await sendRequest({ socketPath: config.controlSocketPath, request });
         }
         if (!response.ok) {
-            writeFailure(stdout, stderr, command, response.error.code, { kind: "failure" });
-            writeUnknownMethodHint(stderr, response.error.code);
-            return gatewayCliExitCodes.failure;
+            return reportControlFailure(command, response.error.code, stdout, stderr);
         }
         if (command === "register-peer" && args.includes("--emit-env") && "token" in response.result) {
             stdout.write(`export EMBASSY_PEER_TOKEN='${response.result.token}'\n`);