agent-embassy 1.5.0 → 1.6.0

package/dist/src/gateway/providers.js

@@ -1,8 +1,9 @@
 import path from "node:path";
+import { chmod, lstat, mkdir, mkdtemp, readdir, realpath, rmdir, } from "node:fs/promises";
 import { BridgeError } from "../errors.js";
 import { CLAUDE_PEER_COMPATIBILITY, ClaudePeerAdapter, } from "./claude-peer.js";
 import { certifiedCompatibilityVersions, compatibilityProbeNames, evaluateCompatibilityAttestation, isCompatibilityAttestation, isCompatibilityVersion, sharesCompatibilityMajor, UNKNOWN_COMPATIBILITY_VERSION, } from "./compatibility.js";
-import { CODEX_APP_SERVER_WRITABLE_VERSIONS, CodexAppServerConnector, CodexConnectorError, } from "./codex-app-server.js";
+import { CODEX_APP_SERVER_WRITABLE_VERSIONS, CodexAppServerConnector, CodexConnectorError, codexWriteProbeFailure, } from "./codex-app-server.js";
 import { LocalCodexTransportError } from "./codex-local-transport.js";
 import { ClaudeNativeHelperSupervisor, } from "./claude-helper-supervisor.js";
 import { isDashboardLocale } from "./locale.js";
@@ -24,6 +25,12 @@ const DEFAULT_CODEX_RECOVERY_INITIAL_MS = 250;
 const DEFAULT_CODEX_RECOVERY_MAX_MS = 5_000;
 const MAX_CODEX_ENDPOINT_REFRESH_CANDIDATES = 3;
 const COMPATIBILITY_PROBE_THREAD_ID = "00000000-0000-7000-8000-000000000000";
+const CODEX_WRITE_PROBE_DIRECTORY_PREFIX = ".codex-write-probe-";
+const CODEX_WRITE_PROBE_ROOT = "write-probes";
+const MAX_CODEX_WRITE_PROBE_ATTEMPTS = 16;
+const CODEX_WRITE_PROBE_TRANSIENT_ERRNOS = new Set([
+    "EAGAIN", "EIO", "EMFILE", "ENFILE",
+]);
 const CLAUDE_CLEAN_PREWRITE_RETRY_CODES = new Set([
     "CLAUDE_PEER_TARGET_UNKNOWN",
     "CLAUDE_PEER_TARGET_STALE",
@@ -85,6 +92,99 @@ function passedProbe(name) {
 function failedProbe(name, safeErrorCode) {
     return { name, outcome: "fail", safeErrorCode };
 }
+function systemErrorCode(error) {
+    return typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+function transientCodexWriteProbeError(error) {
+    return CODEX_WRITE_PROBE_TRANSIENT_ERRNOS.has(systemErrorCode(error) ?? "");
+}
+function safeCodexWriteProbeFilesystemFailure(error) {
+    return (transientCodexWriteProbeError(error) ||
+        systemErrorCode(error) === "ENOTEMPTY" ||
+        (error instanceof BridgeError &&
+            error.code === "CODEX_WRITE_PROBE_THREAD_SETUP_FAILED"));
+}
+async function attestCodexWriteProbeDirectory(directory) {
+    try {
+        const resolved = path.resolve(directory);
+        const [metadata, canonical, entries] = await Promise.all([
+            lstat(resolved, { bigint: true }),
+            realpath(resolved),
+            readdir(resolved),
+        ]);
+        const uid = process.getuid?.();
+        if (uid === undefined ||
+            !metadata.isDirectory() ||
+            canonical !== resolved ||
+            metadata.uid !== BigInt(uid) ||
+            (metadata.mode & 511n) !== 448n) {
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory crossed its ownership, mode, or canonical-path boundary.");
+        }
+        if (entries.length !== 0) {
+            throw new BridgeError("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", "The disposable Codex probe directory was not empty.");
+        }
+        return {
+            dev: metadata.dev,
+            ino: metadata.ino,
+            mode: metadata.mode & 511n,
+            mtimeNs: metadata.mtimeNs,
+            uid: metadata.uid,
+        };
+    }
+    catch (error) {
+        if (error instanceof BridgeError)
+            throw error;
+        if (transientCodexWriteProbeError(error)) {
+            throw new BridgeError("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", "A transient filesystem error prevented disposable probe attestation.");
+        }
+        throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory could not be attested safely.");
+    }
+}
+async function attestCodexWriteProbeRoot(root) {
+    try {
+        const resolved = path.resolve(root);
+        const [metadata, canonical] = await Promise.all([
+            lstat(resolved, { bigint: true }),
+            realpath(resolved),
+        ]);
+        const uid = process.getuid?.();
+        if (uid === undefined ||
+            !metadata.isDirectory() ||
+            canonical !== resolved ||
+            metadata.uid !== BigInt(uid) ||
+            (metadata.mode & 511n) !== 448n) {
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "A controller-owned Codex probe root changed outside its exact owned-directory boundary.");
+        }
+        return {
+            dev: metadata.dev,
+            ino: metadata.ino,
+            mode: metadata.mode & 511n,
+            uid: metadata.uid,
+        };
+    }
+    catch (error) {
+        if (error instanceof BridgeError)
+            throw error;
+        if (transientCodexWriteProbeError(error)) {
+            return null;
+        }
+        throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "A controller-owned Codex probe root could not be attested.");
+    }
+}
+function sameCodexWriteProbeDirectory(before, after) {
+    return sameCodexWriteProbeRoot(before, after) && before.mtimeNs === after.mtimeNs;
+}
+function sameCodexWriteProbeRoot(before, after) {
+    return (before.dev === after.dev &&
+        before.ino === after.ino &&
+        before.mode === after.mode &&
+        before.uid === after.uid);
+}
 function exactLocalHost(hostId) {
     if ((hostId ?? LOCAL_HOST) !== LOCAL_HOST) {
         throw new BridgeError("GATEWAY_REMOTE_PROVIDER_DISABLED", "This provider is restricted to the exact local host boundary.");
@@ -1897,11 +1997,15 @@ export class LocalCodexGatewayProvider {
     endpointActivationRetry;
     endpointActivationRetryTimer;
     callbackDrainFrozen = false;
+    writeProbeObservationsByGeneration = new Map();
+    writeProbeResults = new Map();
+    writeProbeOverflow;
     compatibilityAttested;
     compatibilityFailureCode;
     endpointUnavailable = false;
     pendingEndpointAttestation;
     pendingEndpointRefreshEvent;
+    pendingEndpointRefreshSelectorClaimed = false;
     initialized = false;
     closing = false;
     closed = false;
@@ -1961,6 +2065,7 @@ export class LocalCodexGatewayProvider {
         if (attestation.tier === "incompatible") {
             this.pendingEndpointAttestation = undefined;
             this.pendingEndpointRefreshEvent = undefined;
+            this.pendingEndpointRefreshSelectorClaimed = false;
             this.clearEndpointActivationRetry();
             this.compatibilityAttested = false;
             this.endpointUnavailable = true;
@@ -1982,15 +2087,43 @@ export class LocalCodexGatewayProvider {
         }
         this.pendingEndpointAttestation = undefined;
         this.pendingEndpointRefreshEvent = undefined;
+        this.pendingEndpointRefreshSelectorClaimed = false;
         this.clearEndpointActivationRetry();
         this.compatibilityAttested = writableCertified;
         this.endpointUnavailable = !writableCertified;
         this.compatibilityFailureCode = undefined;
     }
-    async runCompatibilityProbes() {
-        return await this.runCompatibilityProbesFor(this.factory);
+    releaseEndpointRefreshSelectorClaim(endpointGeneration) {
+        const event = this.pendingEndpointRefreshEvent;
+        if (event?.current.endpointGeneration === endpointGeneration &&
+            this.pendingEndpointAttestation !== undefined) {
+            this.pendingEndpointRefreshSelectorClaimed = false;
+        }
+    }
+    rearmEndpointRefreshActivation(endpointGeneration) {
+        const event = this.pendingEndpointRefreshEvent;
+        if (event?.current.endpointGeneration === endpointGeneration &&
+            this.pendingEndpointAttestation !== undefined &&
+            !this.closing &&
+            !this.closed) {
+            this.publishEndpointRefresh(event);
+        }
+    }
+    latestWriteCompatibilityProbeObservation(endpointGeneration) {
+        return (this.writeProbeObservationsByGeneration.get(endpointGeneration) ??
+            (this.writeProbeOverflow?.endpointGeneration === endpointGeneration
+                ? this.writeProbeOverflow.observation
+                : undefined));
+    }
+    async runCompatibilityProbes(context) {
+        return await this.runCompatibilityProbesFor(this.factory, context === undefined
+            ? undefined
+            : {
+                stateRoot: path.resolve(context.stateRoot),
+                forbiddenCodexThreadIds: [...context.forbiddenCodexThreadIds],
+            });
     }
-    async runCompatibilityProbesFor(factory) {
+    async runCompatibilityProbesFor(factory, context) {
         const [installation, control, initialize, threadList] = compatibilityProbeNames.codex;
         let transport;
         let connector;
@@ -2000,6 +2133,9 @@ export class LocalCodexGatewayProvider {
             stage = "initialize";
             connector = await CodexAppServerConnector.connect({
                 compatibility: factory.schemaCompatibility,
+                ...(context === undefined
+                    ? {}
+                    : { writeCompatibilityProbe: true }),
                 writesEnabled: false,
                 route: {
                     endpointGeneration: factory.endpointGeneration,
@@ -2013,16 +2149,25 @@ export class LocalCodexGatewayProvider {
             });
             stage = "thread_list";
             await connector.observeLoadedThread(connector.guard());
-            return [
+            const requiredProbes = [
                 passedProbe(installation),
                 passedProbe(control),
                 passedProbe(initialize),
                 passedProbe(threadList),
             ];
+            if (context === undefined)
+                return requiredProbes;
+            const result = await this.runCodexWriteProbe(factory, connector, context);
+            return result.outcome === "pass"
+                ? [...requiredProbes, passedProbe("write_attestation")]
+                : requiredProbes;
         }
         catch (error) {
-            if (this.isEndpointGenerationChanged(error))
+            if (this.isEndpointGenerationChanged(error) ||
+                (error instanceof BridgeError &&
+                    error.code === "CODEX_FACTORY_ATTESTATION_INVALID")) {
                 throw error;
+            }
             if (stage === "transport") {
                 const availabilityFailure = error instanceof LocalCodexTransportError &&
                     [
@@ -2066,6 +2211,148 @@ export class LocalCodexGatewayProvider {
             }
         }
     }
+    async runCodexWriteProbe(factory, connector, context) {
+        const key = `${factory.appServerVersion}\0${factory.endpointGeneration}`;
+        const cached = this.writeProbeResults.get(key);
+        if (cached !== undefined)
+            return await cached;
+        if (this.writeProbeOverflow?.key === key) {
+            return this.writeProbeOverflow.observation;
+        }
+        if (this.writeProbeResults.size >= MAX_CODEX_WRITE_PROBE_ATTEMPTS) {
+            const observation = Object.freeze(codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED"));
+            this.writeProbeOverflow = Object.freeze({
+                endpointGeneration: factory.endpointGeneration,
+                key,
+                observation,
+            });
+            if (this.callbacks !== undefined) {
+                invokeCallback(() => this.callbacks?.onProtocolNotice?.({
+                    code: observation.safeErrorCode,
+                }));
+            }
+            return observation;
+        }
+        const pending = this.executeCodexWriteProbe(connector, context).then((result) => {
+            const observation = Object.freeze({ ...result });
+            this.writeProbeObservationsByGeneration.set(factory.endpointGeneration, observation);
+            if (observation.outcome === "fail" && this.callbacks !== undefined) {
+                invokeCallback(() => this.callbacks?.onProtocolNotice?.({
+                    code: observation.safeErrorCode,
+                }));
+            }
+            return observation;
+        });
+        this.writeProbeResults.set(key, pending);
+        return await pending;
+    }
+    async executeCodexWriteProbe(connector, context) {
+        const stateRoot = path.resolve(context.stateRoot);
+        const rootBefore = await attestCodexWriteProbeRoot(stateRoot);
+        if (rootBefore === null) {
+            return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        }
+        const probeRoot = path.join(stateRoot, CODEX_WRITE_PROBE_ROOT);
+        let probeRootBefore;
+        try {
+            let created = false;
+            try {
+                await mkdir(probeRoot, { mode: 0o700 });
+                created = true;
+            }
+            catch (error) {
+                if (systemErrorCode(error) !== "EEXIST")
+                    throw error;
+            }
+            if (created)
+                await chmod(probeRoot, 0o700);
+            const evidence = await attestCodexWriteProbeRoot(probeRoot);
+            if (evidence === null) {
+                return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            probeRootBefore = evidence;
+        }
+        catch (error) {
+            if (error instanceof BridgeError &&
+                error.code === "CODEX_FACTORY_ATTESTATION_INVALID") {
+                throw error;
+            }
+            if (transientCodexWriteProbeError(error)) {
+                return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The controller-owned Codex probe root could not be established safely.");
+        }
+        let cwd;
+        let before;
+        let result = codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        try {
+            cwd = await mkdtemp(path.join(probeRoot, CODEX_WRITE_PROBE_DIRECTORY_PREFIX));
+            if (path.dirname(cwd) !== probeRoot) {
+                throw new Error("probe directory escaped its dedicated root");
+            }
+            await chmod(cwd, 0o700);
+            before = await attestCodexWriteProbeDirectory(cwd);
+            result = await connector.runWriteCompatibilityProbe({
+                cwd,
+                forbiddenThreadIds: [
+                    ...new Set([
+                        COMPATIBILITY_PROBE_THREAD_ID,
+                        ...context.forbiddenCodexThreadIds,
+                        ...this.trackedRoutes,
+                    ]),
+                ],
+            });
+        }
+        catch (error) {
+            if (!safeCodexWriteProbeFilesystemFailure(error)) {
+                if (error instanceof BridgeError)
+                    throw error;
+                throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory could not be established safely.");
+            }
+            result = codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        }
+        let unchanged = false;
+        let removed = false;
+        if (cwd !== undefined && before !== undefined) {
+            try {
+                const after = await attestCodexWriteProbeDirectory(cwd);
+                unchanged = sameCodexWriteProbeDirectory(before, after);
+                await rmdir(cwd);
+                try {
+                    await lstat(cwd);
+                }
+                catch (error) {
+                    removed = systemErrorCode(error) === "ENOENT";
+                }
+            }
+            catch (error) {
+                if (!safeCodexWriteProbeFilesystemFailure(error)) {
+                    if (error instanceof BridgeError)
+                        throw error;
+                    throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "The disposable Codex probe directory could not be re-attested safely.");
+                }
+                // Never remove a path after its exact ownership evidence changed.
+            }
+        }
+        if (cwd !== undefined && !removed) {
+            result = codexWriteProbeFailure("CODEX_WRITE_PROBE_CLEANUP_UNCONFIRMED", result);
+        }
+        else if (cwd !== undefined && !unchanged) {
+            result = codexWriteProbeFailure("CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED", result);
+        }
+        const [probeRootAfter, rootAfter] = await Promise.all([
+            attestCodexWriteProbeRoot(probeRoot),
+            attestCodexWriteProbeRoot(stateRoot),
+        ]);
+        if (probeRootAfter === null || rootAfter === null) {
+            return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", result);
+        }
+        if (!sameCodexWriteProbeRoot(probeRootBefore, probeRootAfter) ||
+            !sameCodexWriteProbeRoot(rootBefore, rootAfter)) {
+            throw new BridgeError("CODEX_FACTORY_ATTESTATION_INVALID", "A controller-owned Codex probe root changed while the disposable probe ran.");
+        }
+        return result;
+    }
     async initialize(callbacks) {
         if (this.closed || this.initialized) {
             throw new BridgeError("CODEX_PROVIDER_INITIALIZATION_REJECTED", "The local Codex provider cannot be initialized in this state.");
@@ -2124,9 +2411,13 @@ export class LocalCodexGatewayProvider {
                 throw selectionError;
             }
         };
+        const retainedEndpointRefresh = this.retainedEndpointRefreshResult();
         if (this.endpointRefresh !== undefined) {
             route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
         }
+        else if (retainedEndpointRefresh !== undefined) {
+            route = await stageRefreshedRoute(retainedEndpointRefresh);
+        }
         else if (this.endpointUnavailable &&
             this.pendingEndpointAttestation === undefined) {
             route = await stageRefreshedRoute(await this.refreshEndpoint("selector"));
@@ -2385,6 +2676,7 @@ export class LocalCodexGatewayProvider {
         this.routesRequiringRecovery.clear();
         this.clearEndpointActivationRetry();
         this.pendingEndpointRefreshEvent = undefined;
+        this.pendingEndpointRefreshSelectorClaimed = false;
         this.pendingEndpointAttestation = undefined;
         const refreshResult = this.endpointRefresh === undefined
             ? []
@@ -2413,6 +2705,7 @@ export class LocalCodexGatewayProvider {
         this.callbackQueue.length = 0;
         this.pendingEndpointAttestation = undefined;
         this.pendingEndpointRefreshEvent = undefined;
+        this.pendingEndpointRefreshSelectorClaimed = false;
         this.trackedRoutes.clear();
         this.routeAliases.clear();
         this.expectsReply.clear();
@@ -2663,6 +2956,21 @@ export class LocalCodexGatewayProvider {
             event.current.endpointGeneration === this.factory.endpointGeneration &&
             event.routes.some((route) => route.routeHandle === routeHandle));
     }
+    retainedEndpointRefreshResult() {
+        const event = this.pendingEndpointRefreshEvent;
+        if (event === undefined ||
+            this.pendingEndpointRefreshSelectorClaimed ||
+            this.pendingEndpointAttestation === undefined ||
+            event.current.endpointGeneration !== this.factory.endpointGeneration) {
+            return undefined;
+        }
+        return {
+            event,
+            delivery: "selector",
+            selectorClaimed: false,
+            published: true,
+        };
+    }
     async refreshEndpoint(delivery) {
         if (this.refreshFactory === undefined || this.closing || this.closed) {
             return undefined;
@@ -2707,6 +3015,7 @@ export class LocalCodexGatewayProvider {
                 this.compatibilityAttested = false;
                 this.pendingEndpointAttestation = undefined;
                 this.pendingEndpointRefreshEvent = undefined;
+                this.pendingEndpointRefreshSelectorClaimed = false;
                 for (const routeHandle of this.trackedRoutes) {
                     this.routesRequiringRecovery.add(routeHandle);
                 }
@@ -2721,7 +3030,9 @@ export class LocalCodexGatewayProvider {
                     },
                     delivery: "callback",
                     selectorClaimed: true,
+                    published: false,
                 };
+                result.published = true;
                 this.emitEndpointRefresh(result.event);
                 for (const routeHandle of this.routesRequiringRecovery) {
                     if (this.trackedRoutes.has(routeHandle)) {
@@ -2790,12 +3101,15 @@ export class LocalCodexGatewayProvider {
                 },
                 delivery: this.endpointRefreshDelivery ?? "callback",
                 selectorClaimed: false,
+                published: false,
             };
             if (result.event.outcome === "compatible") {
                 this.pendingEndpointRefreshEvent = result.event;
+                this.pendingEndpointRefreshSelectorClaimed = false;
             }
             if (result.delivery === "callback") {
                 result.selectorClaimed = true;
+                result.published = true;
                 this.publishEndpointRefresh(result.event);
             }
             for (const routeHandle of this.routesRequiringRecovery) {
@@ -2914,11 +3228,16 @@ export class LocalCodexGatewayProvider {
             return false;
         }
         result.selectorClaimed = true;
+        if (this.pendingEndpointRefreshEvent === result.event) {
+            this.pendingEndpointRefreshSelectorClaimed = true;
+        }
         return true;
     }
     emitSelectorRefreshFallback(result, staleRouteHandle) {
         if (result.delivery !== "selector" || !result.selectorClaimed)
             return;
+        if (result.published)
+            return;
         let event = result.event;
         if (staleRouteHandle !== undefined &&
             event.outcome === "compatible" &&
@@ -2930,6 +3249,7 @@ export class LocalCodexGatewayProvider {
             result.event = event;
             this.pendingEndpointRefreshEvent = event;
         }
+        result.published = true;
         this.publishEndpointRefresh(event);
     }
     publishEndpointRefresh(event) {