agent-embassy 1.0.0

package/dist/src/gateway/codex-app-server.js

@@ -0,0 +1,1746 @@
+import { Buffer } from "node:buffer";
+import WebSocket from "ws";
+import { sharesCompatibilityMajor } from "./compatibility.js";
+/**
+ * Stable App Server methods reviewed for the gateway's first writable version.
+ *
+ * `turn/steer` is exposed only through the exact Claude-to-Codex `STEER:`
+ * contract. It queues input at the attested next tool-call boundary and never
+ * authorizes an interrupt or a generic/public JSON-RPC escape hatch.
+ */
+export const CODEX_APP_SERVER_V1_METHODS = [
+    "thread/loaded/list",
+    "thread/resume",
+    "thread/unsubscribe",
+    "turn/start",
+    "turn/steer",
+    "turn/interrupt",
+];
+/** Exact App Server builds whose writable v2 schema was reviewed. */
+export const CODEX_APP_SERVER_WRITABLE_VERSIONS = ["0.147.0"];
+export class CodexConnectorError extends Error {
+    ambiguous;
+    code;
+    constructor(code, ambiguous = false) {
+        super(code);
+        this.name = "CodexConnectorError";
+        this.code = code;
+        this.ambiguous = ambiguous;
+    }
+}
+const DEFAULT_MAX_FRAME_BYTES = 1024 * 1024;
+const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;
+const DEFAULT_TURN_WATCHDOG_MS = 2 * 60_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
+const DEFAULT_HEARTBEAT_TIMEOUT_MS = 5_000;
+const DEFAULT_MAX_INPUT_BYTES = 64 * 1024;
+const DEFAULT_MAX_QUEUE_DEPTH = 32;
+const DEFAULT_MAX_MESSAGE_IDS = 4_096;
+const DEFAULT_MAX_DEADLINE_MS = 24 * 60 * 60 * 1_000;
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function rawDataToBuffer(data) {
+    if (Buffer.isBuffer(data))
+        return data;
+    if (data instanceof ArrayBuffer)
+        return Buffer.from(data);
+    return Buffer.concat(data);
+}
+/**
+ * WebSocket client over a caller-owned, socket-compatible Duplex. The caller
+ * remains responsible for spawning, bounding, and terminating its exact local
+ * or SSH proxy process; this adapter never discovers or signals App Server.
+ */
+export class WebSocketDuplexTransport {
+    socket;
+    maxFrameBytes;
+    closeTimeoutMs;
+    heartbeatTimeoutMs;
+    static async connect(stream, options = {}) {
+        const maxFrameBytes = positiveInteger(options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, "INVALID_CONFIGURATION");
+        const handshakeTimeoutMs = positiveInteger(options.handshakeTimeoutMs ?? 5_000, "INVALID_CONFIGURATION");
+        const closeTimeoutMs = positiveInteger(options.closeTimeoutMs ?? 2_000, "INVALID_CONFIGURATION");
+        const heartbeatIntervalMs = positiveInteger(options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS, "INVALID_CONFIGURATION");
+        const heartbeatTimeoutMs = positiveInteger(options.heartbeatTimeoutMs ?? DEFAULT_HEARTBEAT_TIMEOUT_MS, "INVALID_CONFIGURATION");
+        if (heartbeatTimeoutMs >= heartbeatIntervalMs) {
+            throw new CodexConnectorError("INVALID_CONFIGURATION");
+        }
+        const socket = new WebSocket("ws://localhost/rpc", {
+            createConnection: () => {
+                stream.setNoDelay(true);
+                stream.setKeepAlive(true, heartbeatIntervalMs);
+                queueMicrotask(() => stream.emit("connect"));
+                return stream;
+            },
+            followRedirects: false,
+            handshakeTimeout: handshakeTimeoutMs,
+            maxPayload: maxFrameBytes,
+            perMessageDeflate: false,
+        });
+        // A permanent sink prevents an EventEmitter error from becoming an
+        // uncaught exception before/after connector listeners are installed.
+        socket.on("error", () => undefined);
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                socket.off("open", onOpen);
+                socket.off("error", onError);
+                socket.off("unexpected-response", onUnexpectedResponse);
+                if (error === undefined)
+                    resolve();
+                else {
+                    socket.terminate();
+                    reject(error);
+                }
+            };
+            const onOpen = () => finish();
+            const onError = () => finish(new CodexConnectorError("TRANSPORT_CLOSED"));
+            const onUnexpectedResponse = () => finish(new CodexConnectorError("PROTOCOL_ERROR"));
+            socket.once("open", onOpen);
+            socket.once("error", onError);
+            socket.once("unexpected-response", onUnexpectedResponse);
+        });
+        return new WebSocketDuplexTransport(socket, maxFrameBytes, closeTimeoutMs, heartbeatIntervalMs, heartbeatTimeoutMs);
+    }
+    closeListeners = new Set();
+    errorListeners = new Set();
+    messageListeners = new Set();
+    heartbeatInterval;
+    heartbeatTimeout;
+    heartbeatFailed = false;
+    constructor(socket, maxFrameBytes, closeTimeoutMs, heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS, heartbeatTimeoutMs = DEFAULT_HEARTBEAT_TIMEOUT_MS) {
+        this.socket = socket;
+        this.maxFrameBytes = maxFrameBytes;
+        this.closeTimeoutMs = closeTimeoutMs;
+        this.heartbeatTimeoutMs = heartbeatTimeoutMs;
+        socket.on("message", (data, isBinary) => {
+            if (isBinary) {
+                this.emitError();
+                socket.terminate();
+                return;
+            }
+            const bytes = rawDataToBuffer(data);
+            if (bytes.length > this.maxFrameBytes) {
+                this.emitError();
+                socket.terminate();
+                return;
+            }
+            const payload = bytes.toString("utf8");
+            for (const listener of this.messageListeners)
+                listener(payload);
+        });
+        socket.on("pong", () => {
+            if (this.heartbeatTimeout !== undefined) {
+                clearTimeout(this.heartbeatTimeout);
+                this.heartbeatTimeout = undefined;
+            }
+        });
+        socket.on("error", () => this.failHeartbeat());
+        socket.on("close", () => {
+            this.stopHeartbeat();
+            for (const listener of this.closeListeners)
+                listener();
+        });
+        this.heartbeatInterval = setInterval(() => this.sendHeartbeat(), heartbeatIntervalMs);
+        this.heartbeatInterval.unref();
+    }
+    onMessage(listener) {
+        this.messageListeners.add(listener);
+        return () => this.messageListeners.delete(listener);
+    }
+    onClose(listener) {
+        this.closeListeners.add(listener);
+        return () => this.closeListeners.delete(listener);
+    }
+    onError(listener) {
+        this.errorListeners.add(listener);
+        return () => this.errorListeners.delete(listener);
+    }
+    async send(payload) {
+        if (this.socket.readyState !== WebSocket.OPEN) {
+            throw new CodexConnectorError("TRANSPORT_CLOSED");
+        }
+        if (Buffer.byteLength(payload, "utf8") > this.maxFrameBytes) {
+            throw new CodexConnectorError("INPUT_INVALID");
+        }
+        await new Promise((resolve, reject) => {
+            this.socket.send(payload, (error) => {
+                if (error == null)
+                    resolve();
+                else
+                    reject(new CodexConnectorError("TRANSPORT_WRITE_FAILED", true));
+            });
+        });
+    }
+    async close() {
+        this.stopHeartbeat();
+        if (this.socket.readyState === WebSocket.CLOSED)
+            return;
+        await new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.socket.off("close", finish);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                this.socket.terminate();
+                finish();
+            }, this.closeTimeoutMs);
+            this.socket.once("close", finish);
+            this.socket.close(1000);
+        });
+    }
+    emitError() {
+        for (const listener of this.errorListeners)
+            listener();
+    }
+    sendHeartbeat() {
+        if (this.socket.readyState !== WebSocket.OPEN ||
+            this.heartbeatFailed ||
+            this.heartbeatTimeout !== undefined) {
+            return;
+        }
+        try {
+            this.socket.ping(undefined, undefined, (error) => {
+                if (error != null)
+                    this.failHeartbeat();
+            });
+        }
+        catch {
+            this.failHeartbeat();
+            return;
+        }
+        if (this.heartbeatFailed)
+            return;
+        this.heartbeatTimeout = setTimeout(() => this.failHeartbeat(), this.heartbeatTimeoutMs);
+        this.heartbeatTimeout.unref();
+    }
+    failHeartbeat() {
+        if (this.heartbeatFailed)
+            return;
+        this.heartbeatFailed = true;
+        this.stopHeartbeat();
+        this.emitError();
+        this.socket.terminate();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatInterval !== undefined) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = undefined;
+        }
+        if (this.heartbeatTimeout !== undefined) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = undefined;
+        }
+    }
+}
+const V1_METHOD_SET = new Set(CODEX_APP_SERVER_V1_METHODS);
+const OUTPUT_NOTIFICATION_OPT_OUTS = [
+    "item/started",
+    "item/agentMessage/delta",
+    "item/reasoning/textDelta",
+    "item/reasoning/summaryTextDelta",
+    "item/commandExecution/outputDelta",
+    "turn/diff/updated",
+    "turn/plan/updated",
+];
+const APPROVAL_REQUEST_METHODS = new Set([
+    "item/commandExecution/requestApproval",
+    "item/fileChange/requestApproval",
+    "item/permissions/requestApproval",
+    "item/tool/requestUserInput",
+    "mcpServer/elicitation/request",
+]);
+function positiveInteger(value, code) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new CodexConnectorError(code);
+    }
+    return value;
+}
+function validOpaqueId(value, maximumLength = 256) {
+    return (value.length > 0 &&
+        value.length <= maximumLength &&
+        /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value));
+}
+function validateRoute(route) {
+    if (!validOpaqueId(route.threadId) ||
+        !validOpaqueId(route.endpointGeneration, 128)) {
+        throw new CodexConnectorError("INVALID_ROUTE");
+    }
+    return { ...route };
+}
+function validateClientInfo(clientInfo) {
+    const values = [clientInfo.name, clientInfo.title, clientInfo.version];
+    if (values.some((value) => value.length === 0 ||
+        value.length > 128 ||
+        value.includes("\0") ||
+        /[\r\n]/u.test(value))) {
+        throw new CodexConnectorError("INVALID_CONFIGURATION");
+    }
+    return { ...clientInfo };
+}
+function validateCompatibility(compatibility, route) {
+    if (compatibility.endpointGeneration !== route.endpointGeneration ||
+        compatibility.protocol !== "app-server-v2-stable" ||
+        compatibility.steering?.method !== "turn/steer" ||
+        compatibility.steering.requestSchema !== "expected-turn-id-text-v1" ||
+        compatibility.steering.deliveryBoundary !== "next-tool-call-boundary" ||
+        !(CODEX_APP_SERVER_WRITABLE_VERSIONS.some((version) => version === compatibility.appServerVersion) ||
+            (compatibility.observedSchemaCandidate === true &&
+                CODEX_APP_SERVER_WRITABLE_VERSIONS.some((version) => sharesCompatibilityMajor(version, compatibility.appServerVersion))))) {
+        throw new CodexConnectorError("INVALID_CONFIGURATION");
+    }
+    return { ...compatibility, steering: { ...compatibility.steering } };
+}
+function parseRouteStatus(value) {
+    if (!isRecord(value) || typeof value.type !== "string")
+        return null;
+    if (value.type === "notLoaded")
+        return "not_loaded";
+    if (value.type === "idle")
+        return "idle";
+    if (value.type === "systemError")
+        return "system_error";
+    if (value.type !== "active")
+        return null;
+    if (value.activeFlags === undefined)
+        return "active";
+    if (!Array.isArray(value.activeFlags) ||
+        value.activeFlags.length > 32 ||
+        !value.activeFlags.every((flag) => typeof flag === "string" && flag.length <= 128)) {
+        return null;
+    }
+    return value.activeFlags.includes("waitingOnApproval")
+        ? "waiting_approval"
+        : "active";
+}
+function parseTurn(value) {
+    if (!isRecord(value) ||
+        typeof value.id !== "string" ||
+        !validOpaqueId(value.id) ||
+        typeof value.status !== "string" ||
+        value.status.length > 64) {
+        return null;
+    }
+    return { id: value.id, status: value.status };
+}
+/**
+ * One connection, one exact opted-in Codex route, one endpoint generation.
+ * Reconnection creates a new connector/generation; this object never retries
+ * an ambiguous write or silently rebinds a stale route.
+ */
+export class CodexAppServerConnector {
+    static async connect(options) {
+        const connector = new CodexAppServerConnector(options);
+        await connector.initialize();
+        return connector;
+    }
+    acceptedMessageIds = new Set();
+    activeMessageId = null;
+    activeTurnId = null;
+    connection = "connecting";
+    drainScheduled = false;
+    eventSequence = 0;
+    expectedClose = false;
+    faulting = false;
+    consecutiveRequestTimeouts = 0;
+    inFlightMethod = null;
+    initializeRequested = false;
+    initialized = false;
+    lastCompletedTurnId = null;
+    nextRequestId = 1;
+    ownsActiveTurn = false;
+    pending = new Map();
+    queue = [];
+    revision = 0;
+    routeStatus = "unknown";
+    selectedThreadObserved = false;
+    statusEpoch = 0;
+    transientReply = null;
+    transientReplyTooLarge = false;
+    turnWatchdogTimer;
+    unlisten = [];
+    clientInfo;
+    compatibility;
+    maxDeadlineMs;
+    maxFrameBytes;
+    maxInputBytes;
+    maxMessageIds;
+    maxQueueDepth;
+    maxReplyBytes;
+    now;
+    onEvent;
+    onTurnResult;
+    requestTimeoutMs;
+    turnWatchdogMs;
+    route;
+    transport;
+    writesEnabled;
+    constructor(options) {
+        this.route = validateRoute(options.route);
+        this.compatibility = validateCompatibility(options.compatibility, this.route);
+        if (typeof options.writesEnabled !== "boolean") {
+            throw new CodexConnectorError("INVALID_CONFIGURATION");
+        }
+        this.writesEnabled = options.writesEnabled;
+        this.transport = options.transport;
+        this.clientInfo = validateClientInfo(options.clientInfo ?? {
+            name: "agent_embassy_gateway",
+            title: "Embassy Gateway",
+            version: "1.0.0",
+        });
+        this.maxFrameBytes = positiveInteger(options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, "INVALID_CONFIGURATION");
+        this.maxDeadlineMs = positiveInteger(options.maxDeadlineMs ?? DEFAULT_MAX_DEADLINE_MS, "INVALID_CONFIGURATION");
+        this.maxInputBytes = positiveInteger(options.maxInputBytes ?? DEFAULT_MAX_INPUT_BYTES, "INVALID_CONFIGURATION");
+        this.maxMessageIds = positiveInteger(options.maxMessageIds ?? DEFAULT_MAX_MESSAGE_IDS, "INVALID_CONFIGURATION");
+        this.maxQueueDepth = positiveInteger(options.maxQueueDepth ?? DEFAULT_MAX_QUEUE_DEPTH, "INVALID_CONFIGURATION");
+        this.maxReplyBytes = positiveInteger(options.maxReplyBytes ?? DEFAULT_MAX_INPUT_BYTES, "INVALID_CONFIGURATION");
+        this.requestTimeoutMs = positiveInteger(options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, "INVALID_CONFIGURATION");
+        this.turnWatchdogMs = positiveInteger(options.turnWatchdogMs ?? DEFAULT_TURN_WATCHDOG_MS, "INVALID_CONFIGURATION");
+        this.now = options.now ?? (() => new Date());
+        this.onEvent = options.onEvent;
+        this.onTurnResult = options.onTurnResult;
+        this.unlisten.push(this.transport.onMessage((payload) => this.handlePayload(payload)), this.transport.onClose(() => this.handleDisconnect()), this.transport.onError(() => this.protocolFault("TRANSPORT_CLOSED")));
+    }
+    observation() {
+        const writeBlockCode = this.currentWriteBlockCode();
+        return {
+            connection: this.connection,
+            eventSequence: this.eventSequence,
+            hasActiveTurn: this.activeTurnId !== null,
+            queueDepth: this.queue.length,
+            requestInFlight: this.inFlightMethod !== null,
+            routeStatus: this.routeStatus,
+            writableReady: this.isWritableReady(),
+            writeBlockCode,
+        };
+    }
+    guard() {
+        const writableReady = this.isWritableReady();
+        return {
+            ...this.route,
+            activeTurnId: this.activeTurnId,
+            revision: this.revision,
+            status: this.routeStatus,
+            writableReady,
+        };
+    }
+    async observeLoadedThread(guard) {
+        this.assertGuard(guard);
+        this.assertReady();
+        this.assertNoRequest();
+        this.beginRequest("thread/loaded/list");
+        try {
+            const result = await this.request("thread/loaded/list", {});
+            if (!isRecord(result) || !Array.isArray(result.data)) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+            }
+            const data = result.data;
+            if (data.length > 100_000 ||
+                !data.every((item) => typeof item === "string" && validOpaqueId(item))) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+            }
+            const selectedThreadLoaded = data.includes(this.route.threadId);
+            if (this.selectedThreadObserved !== selectedThreadLoaded) {
+                this.selectedThreadObserved = selectedThreadLoaded;
+                this.bumpRevision();
+            }
+            if (!selectedThreadLoaded) {
+                if (this.routeStatus === "active" ||
+                    this.routeStatus === "waiting_approval" ||
+                    this.routeStatus === "interrupting" ||
+                    this.activeTurnId !== null) {
+                    throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+                }
+                this.setRouteStatus("not_loaded");
+            }
+            const loadedObservation = {
+                loadedThreadCount: data.length,
+                selectedThreadLoaded,
+            };
+            this.emit("thread_observed", {
+                loadedThreadCount: data.length,
+                selectedThreadLoaded,
+            });
+            this.finishRequest("thread/loaded/list");
+            return { ...loadedObservation, observation: this.observation() };
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            if (normalized.ambiguous && this.connection === "ready") {
+                this.settleActiveDelivery("ambiguous");
+                this.setRouteStatus("uncertain");
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            this.finishRequest("thread/loaded/list");
+        }
+    }
+    async resumeThread(guard) {
+        this.assertGuard(guard);
+        this.assertReady();
+        this.assertNoRequest();
+        if (!this.selectedThreadObserved) {
+            throw new CodexConnectorError("THREAD_NOT_OBSERVED");
+        }
+        if (this.routeStatus !== "unknown" &&
+            this.routeStatus !== "not_loaded" &&
+            !(this.currentWriteBlockCode() !== null &&
+                this.routeStatus === "idle" &&
+                this.activeTurnId === null)) {
+            throw new CodexConnectorError("ROUTE_BUSY");
+        }
+        const statusEpoch = this.statusEpoch;
+        this.beginRequest("thread/resume");
+        try {
+            const result = await this.request("thread/resume", {
+                excludeTurns: true,
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result) ||
+                !isRecord(result.thread) ||
+                !Array.isArray(result.thread.turns) ||
+                result.thread.turns.length !== 0) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (result.thread.id !== this.route.threadId) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (this.statusEpoch === statusEpoch) {
+                const status = parseRouteStatus(result.thread.status);
+                if (status === null) {
+                    // A response without status proves subscription but not idleness. Do
+                    // not guess; queued/model actions remain fail-closed until status is
+                    // observed.
+                    this.setRouteStatus("unknown");
+                }
+                else {
+                    this.setRouteStatus(status);
+                }
+            }
+            this.emit("thread_resumed");
+            const writeBlockCode = this.currentWriteBlockCode();
+            if (writeBlockCode !== null) {
+                this.emit("route_write_blocked", { errorCode: writeBlockCode });
+            }
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            if (normalized.ambiguous && this.connection === "ready") {
+                this.setRouteStatus("uncertain");
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            this.finishRequest("thread/resume");
+        }
+        return this.observation();
+    }
+    /**
+     * Revalidate the exact selected thread/resume schema without creating a
+     * turn. Unlike initial route setup, certification is permitted while the
+     * route is already idle; every other state remains fail-closed.
+     */
+    async certifyThreadOperations(guard) {
+        this.assertGuard(guard);
+        this.assertReady();
+        this.assertNoRequest();
+        if (!this.selectedThreadObserved) {
+            throw new CodexConnectorError("THREAD_NOT_OBSERVED");
+        }
+        if (this.routeStatus !== "idle") {
+            throw new CodexConnectorError("ROUTE_BUSY");
+        }
+        const statusEpoch = this.statusEpoch;
+        this.beginRequest("thread/resume");
+        try {
+            const result = await this.request("thread/resume", {
+                excludeTurns: true,
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result) ||
+                !isRecord(result.thread) ||
+                result.thread.id !== this.route.threadId ||
+                !Array.isArray(result.thread.turns) ||
+                result.thread.turns.length !== 0) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (this.statusEpoch === statusEpoch) {
+                const status = parseRouteStatus(result.thread.status);
+                if (status !== "idle") {
+                    throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+                }
+                this.setRouteStatus(status);
+            }
+            this.emit("thread_resumed");
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            if (normalized.ambiguous && this.connection === "ready") {
+                this.setRouteStatus("uncertain");
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            this.finishRequest("thread/resume");
+        }
+        return this.observation();
+    }
+    async unsubscribeThread(guard) {
+        this.assertGuard(guard);
+        this.assertReady();
+        this.assertNoRequest();
+        if (this.activeTurnId !== null ||
+            this.routeStatus === "active" ||
+            this.routeStatus === "waiting_approval" ||
+            this.routeStatus === "starting" ||
+            this.routeStatus === "interrupting") {
+            throw new CodexConnectorError("ROUTE_BUSY");
+        }
+        this.dropQueuedMessages();
+        this.beginRequest("thread/unsubscribe");
+        try {
+            const result = await this.request("thread/unsubscribe", {
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result) ||
+                (result.status !== "unsubscribed" &&
+                    result.status !== "notSubscribed" &&
+                    result.status !== "notLoaded")) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+            }
+            this.setRouteStatus("not_loaded");
+            this.selectedThreadObserved = false;
+            this.emit("thread_unsubscribed");
+            const status = result.status;
+            this.finishRequest("thread/unsubscribe");
+            return { observation: this.observation(), status };
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            if (normalized.ambiguous && this.connection === "ready") {
+                this.setRouteStatus("uncertain");
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            this.finishRequest("thread/unsubscribe");
+        }
+    }
+    /**
+     * Drop only this exact route's transient queued bodies. Route disable and
+     * unregister paths use this before releasing broker ownership.
+     */
+    cancelQueuedMessages(guard) {
+        this.assertGuard(guard);
+        this.assertReady();
+        const droppedMessages = this.dropQueuedMessages();
+        this.emit("queued_messages_cancelled", { droppedMessages });
+        return this.observation();
+    }
+    async submitMessage(guard, input) {
+        this.assertGuard(guard);
+        this.assertReady();
+        if (!this.selectedThreadObserved) {
+            throw new CodexConnectorError("THREAD_NOT_OBSERVED");
+        }
+        if (input.steer === true && this.routeStatus === "active") {
+            this.assertWritableReady();
+            const message = this.validateMessage(input);
+            if (this.activeTurnId === null || this.inFlightMethod !== null) {
+                this.acceptedMessageIds.delete(message.messageId);
+                return { disposition: "deferred", observation: this.observation() };
+            }
+            const disposition = await this.steerMessage(message);
+            return { disposition, observation: this.observation() };
+        }
+        if (this.routeStatus === "starting" ||
+            this.routeStatus === "active" ||
+            this.routeStatus === "waiting_approval" ||
+            this.routeStatus === "interrupting") {
+            this.assertWritableReady();
+            const message = this.validateMessage(input);
+            if (input.steer === true) {
+                this.acceptedMessageIds.delete(message.messageId);
+                return { disposition: "deferred", observation: this.observation() };
+            }
+            this.enqueue(message);
+            return { disposition: "queued", observation: this.observation() };
+        }
+        this.assertWritableReady();
+        const message = this.validateMessage(input);
+        if (this.routeStatus !== "idle") {
+            this.acceptedMessageIds.delete(message.messageId);
+            throw new CodexConnectorError("ROUTE_NOT_READY");
+        }
+        const disposition = await this.startMessage(message);
+        return { disposition, observation: this.observation() };
+    }
+    /**
+     * Interrupt only a connector-originated turn whose exact ID is present in a
+     * fresh CAS guard. The method clears queued work and never targets a Desktop
+     * or user-originated active turn.
+     */
+    async interruptOwnedTurn(guard) {
+        this.assertGuard(guard);
+        this.assertReady();
+        this.assertNoRequest();
+        if (!this.selectedThreadObserved) {
+            throw new CodexConnectorError("THREAD_NOT_OBSERVED");
+        }
+        if (!this.ownsActiveTurn ||
+            this.activeTurnId === null ||
+            guard.activeTurnId !== this.activeTurnId ||
+            (this.routeStatus !== "active" &&
+                this.routeStatus !== "waiting_approval")) {
+            throw new CodexConnectorError("TURN_NOT_OWNED");
+        }
+        const turnId = this.activeTurnId;
+        const droppedMessages = this.dropQueuedMessages();
+        this.beginRequest("turn/interrupt");
+        try {
+            const result = await this.request("turn/interrupt", {
+                threadId: this.route.threadId,
+                turnId,
+            });
+            if (!isRecord(result)) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            // A completion notification can win the race with the response.
+            if (this.activeTurnId === turnId && this.ownsActiveTurn) {
+                this.setRouteStatus("interrupting");
+            }
+            this.emit("turn_interrupt_requested", { droppedMessages });
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            if (normalized.ambiguous && this.connection === "ready") {
+                this.settleActiveDelivery("ambiguous");
+                this.activeTurnId = null;
+                this.setRouteStatus("uncertain");
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            this.finishRequest("turn/interrupt");
+        }
+        return this.observation();
+    }
+    async close() {
+        if (this.connection === "closed" || this.connection === "faulted")
+            return;
+        this.clearTurnWatchdog();
+        this.expectedClose = true;
+        try {
+            await this.transport.close();
+        }
+        finally {
+            this.handleDisconnect();
+        }
+    }
+    async initialize() {
+        try {
+            const result = await this.request("initialize", {
+                capabilities: {
+                    // `thread/resume.excludeTurns` is field-gated behind this capability
+                    // in the exactly attested 0.147.0 schema. The client method allowlist
+                    // remains closed and exposes no experimental method.
+                    experimentalApi: true,
+                    optOutNotificationMethods: [...OUTPUT_NOTIFICATION_OPT_OUTS],
+                },
+                clientInfo: this.clientInfo,
+            });
+            if (!isRecord(result)) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+            }
+            await this.transport.send(JSON.stringify({ method: "initialized", params: {} }));
+            this.initialized = true;
+            this.connection = "ready";
+            this.bumpRevision();
+            this.emit("connection_ready");
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            this.protocolFault(normalized.code);
+            throw normalized;
+        }
+    }
+    validateMessage(input) {
+        if (!validOpaqueId(input.messageId, 128) ||
+            typeof input.text !== "string" ||
+            input.text.trim().length === 0 ||
+            input.text.includes("\0")) {
+            throw new CodexConnectorError("INPUT_INVALID");
+        }
+        const nowMs = this.now().getTime();
+        const deadlineAtMs = typeof input.deadlineAt === "string"
+            ? Date.parse(input.deadlineAt)
+            : Number.NaN;
+        if (!Number.isFinite(nowMs) ||
+            !Number.isFinite(deadlineAtMs) ||
+            new Date(deadlineAtMs).toISOString() !== input.deadlineAt ||
+            deadlineAtMs <= nowMs ||
+            deadlineAtMs > nowMs + this.maxDeadlineMs) {
+            throw new CodexConnectorError("INPUT_INVALID");
+        }
+        const byteLength = Buffer.byteLength(input.text, "utf8");
+        if (byteLength === 0 || byteLength > this.maxInputBytes) {
+            throw new CodexConnectorError("INPUT_INVALID");
+        }
+        if (this.acceptedMessageIds.has(input.messageId)) {
+            throw new CodexConnectorError("MESSAGE_DUPLICATE");
+        }
+        if (this.acceptedMessageIds.size >= this.maxMessageIds) {
+            throw new CodexConnectorError("MESSAGE_CAPACITY");
+        }
+        this.acceptedMessageIds.add(input.messageId);
+        return {
+            byteLength,
+            deadlineAtMs,
+            messageId: input.messageId,
+            text: input.text,
+        };
+    }
+    enqueue(message) {
+        if (this.queue.length >= this.maxQueueDepth) {
+            this.acceptedMessageIds.delete(message.messageId);
+            throw new CodexConnectorError("QUEUE_FULL");
+        }
+        this.queue.push(message);
+        this.bumpRevision();
+        this.emit("message_queued", { messageBytes: message.byteLength });
+    }
+    async startMessage(message) {
+        this.assertNoRequest();
+        this.assertWritableReady();
+        if (this.messageExpired(message)) {
+            this.expireMessage(message);
+            return "expired";
+        }
+        // Reserve queue order while the host-local lease is being revalidated,
+        // but do not claim turn ownership until immediately before the RPC write.
+        this.activeMessageId = message.messageId;
+        this.ownsActiveTurn = false;
+        this.transientReply = null;
+        this.transientReplyTooLarge = false;
+        this.setRouteStatus("starting");
+        let requestBegan = false;
+        try {
+            await this.refreshExactRouteBoundary();
+            if (this.messageExpired(message)) {
+                this.activeMessageId = null;
+                this.acceptedMessageIds.delete(message.messageId);
+                if (this.routeStatus === "starting")
+                    this.setRouteStatus("idle");
+                this.settleDelivery(message.messageId, "expired");
+                return "expired";
+            }
+            if (this.connection !== "ready" ||
+                this.routeStatus !== "starting" ||
+                this.activeMessageId !== message.messageId) {
+                throw new CodexConnectorError("ROUTE_NOT_READY");
+            }
+            const statusEpoch = this.statusEpoch;
+            this.ownsActiveTurn = true;
+            this.emit("turn_starting", { messageBytes: message.byteLength });
+            this.beginRequest("turn/start");
+            requestBegan = true;
+            const result = await this.request("turn/start", {
+                input: [{ text: message.text, type: "text" }],
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result)) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            const turn = parseTurn(result.turn);
+            if (turn === null || turn.status !== "inProgress") {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (this.activeTurnId !== null && this.activeTurnId !== turn.id) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (this.lastCompletedTurnId === turn.id) {
+                // A very fast turn may complete before its start response is handled.
+                // Never resurrect it or retry; the completion notification is final.
+                return "started";
+            }
+            this.activeTurnId = turn.id;
+            this.ownsActiveTurn = true;
+            if (this.statusEpoch === statusEpoch || this.routeStatus === "starting") {
+                this.setRouteStatus("active");
+            }
+            this.emit("turn_started", { messageBytes: message.byteLength });
+            this.armTurnWatchdog();
+            return "started";
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            const noObservedTurn = this.activeTurnId === null;
+            if (this.connection !== "ready") {
+                // The transport close/fault already settled the reserved delivery.
+            }
+            else if (!normalized.ambiguous && noObservedTurn) {
+                this.settleDelivery(message.messageId, "failed", null, "REPLY_UNAVAILABLE");
+                this.activeMessageId = null;
+                this.ownsActiveTurn = false;
+                this.acceptedMessageIds.delete(message.messageId);
+                if (normalized.code !== "ROUTE_NOT_READY" ||
+                    this.routeStatus === "starting") {
+                    // A clean JSON-RPC rejection may represent a concurrent Desktop
+                    // state change. Stop the queue until authoritative state is observed.
+                    this.setRouteStatus("system_error");
+                }
+            }
+            else {
+                this.settleActiveDelivery("ambiguous");
+                this.activeTurnId = null;
+                this.setRouteStatus("uncertain");
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            if (requestBegan)
+                this.finishRequest("turn/start");
+        }
+    }
+    /**
+     * Add one exact input to the currently observed active turn. App Server owns
+     * the temporal boundary: the attested method applies it at the next tool-call
+     * boundary, never by interrupting an in-progress generation.
+     */
+    async steerMessage(message) {
+        this.assertNoRequest();
+        this.assertWritableReady();
+        if (this.messageExpired(message)) {
+            this.expireMessage(message);
+            return "expired";
+        }
+        if (this.routeStatus !== "active" || this.activeTurnId === null) {
+            this.acceptedMessageIds.delete(message.messageId);
+            return "deferred";
+        }
+        const expectedTurnId = this.activeTurnId;
+        this.beginRequest("turn/steer");
+        try {
+            const result = await this.request("turn/steer", {
+                expectedTurnId,
+                input: [{ text: message.text, type: "text" }],
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result) ||
+                Object.keys(result).length !== 1 ||
+                typeof result.turnId !== "string" ||
+                result.turnId !== expectedTurnId) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (this.activeTurnId !== null &&
+                this.activeTurnId !== expectedTurnId) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            this.acceptedMessageIds.delete(message.messageId);
+            this.emit("turn_steered", { messageBytes: message.byteLength });
+            return "steered";
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            this.acceptedMessageIds.delete(message.messageId);
+            if (!normalized.ambiguous && normalized.code === "RPC_REJECTED") {
+                return "deferred";
+            }
+            this.handleActionError(normalized);
+            throw normalized;
+        }
+        finally {
+            this.finishRequest("turn/steer");
+        }
+    }
+    scheduleDrain() {
+        this.dropExpiredQueuedMessages();
+        if (this.drainScheduled ||
+            this.connection !== "ready" ||
+            this.routeStatus !== "idle" ||
+            this.currentWriteBlockCode() !== null ||
+            this.inFlightMethod !== null ||
+            this.queue.length === 0) {
+            return;
+        }
+        // Leave the body in the queue until the microtask commits the start. This
+        // keeps it visible to exact-route cancellation/close in the completion ->
+        // drain scheduling window.
+        this.drainScheduled = true;
+        queueMicrotask(() => {
+            this.drainScheduled = false;
+            this.dropExpiredQueuedMessages();
+            if (this.connection !== "ready" ||
+                this.routeStatus !== "idle" ||
+                this.currentWriteBlockCode() !== null ||
+                this.inFlightMethod !== null ||
+                this.queue.length === 0) {
+                return;
+            }
+            const message = this.queue.shift();
+            if (message === undefined)
+                return;
+            this.bumpRevision();
+            void this.startMessage(message).then((disposition) => {
+                if (disposition === "expired")
+                    this.scheduleDrain();
+            }, () => undefined);
+        });
+    }
+    assertGuard(guard) {
+        if (guard.threadId !== this.route.threadId ||
+            guard.endpointGeneration !== this.route.endpointGeneration) {
+            throw new CodexConnectorError("STALE_ENDPOINT");
+        }
+        if (guard.revision !== this.revision ||
+            guard.status !== this.routeStatus ||
+            guard.activeTurnId !== this.activeTurnId ||
+            guard.writableReady !== this.isWritableReady()) {
+            throw new CodexConnectorError("ROUTE_CAS_MISMATCH");
+        }
+    }
+    assertReady() {
+        if (!this.initialized ||
+            this.connection !== "ready" ||
+            this.routeStatus === "stale") {
+            throw new CodexConnectorError("CONNECTOR_CLOSED");
+        }
+    }
+    assertNoRequest() {
+        if (this.inFlightMethod !== null) {
+            throw new CodexConnectorError("ROUTE_BUSY");
+        }
+    }
+    currentWriteBlockCode() {
+        return this.writesEnabled ? null : "WRITES_DISABLED";
+    }
+    isWritableReady() {
+        return this.connection === "ready" && this.currentWriteBlockCode() === null;
+    }
+    assertWritableReady() {
+        const code = this.currentWriteBlockCode();
+        if (code !== null)
+            throw new CodexConnectorError(code);
+    }
+    /**
+     * Refresh the exact thread on this same connection immediately before a
+     * `turn/start`. This confirms the registered task is still the observed idle
+     * route without reading history or changing its native approval/sandbox
+     * policy.
+     */
+    async refreshExactRouteBoundary() {
+        this.assertWritableReady();
+        if (this.routeStatus !== "starting" ||
+            this.activeMessageId === null ||
+            this.activeTurnId !== null ||
+            this.ownsActiveTurn) {
+            throw new CodexConnectorError("ROUTE_NOT_READY");
+        }
+        const statusEpoch = this.statusEpoch;
+        this.beginRequest("thread/resume");
+        try {
+            const result = await this.request("thread/resume", {
+                excludeTurns: true,
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result) ||
+                !isRecord(result.thread) ||
+                result.thread.id !== this.route.threadId ||
+                !Array.isArray(result.thread.turns) ||
+                result.thread.turns.length !== 0) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            const refreshedStatus = parseRouteStatus(result.thread.status);
+            if (refreshedStatus === null) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (refreshedStatus !== "idle") {
+                this.setRouteStatus(refreshedStatus);
+                throw new CodexConnectorError("ROUTE_NOT_READY");
+            }
+            this.assertWritableReady();
+            if (this.statusEpoch !== statusEpoch ||
+                this.routeStatus !== "starting" ||
+                this.activeMessageId === null ||
+                this.activeTurnId !== null ||
+                this.ownsActiveTurn) {
+                throw new CodexConnectorError("ROUTE_NOT_READY");
+            }
+        }
+        finally {
+            this.finishRequest("thread/resume");
+        }
+    }
+    messageExpired(message) {
+        const nowMs = this.now().getTime();
+        return !Number.isFinite(nowMs) || nowMs >= message.deadlineAtMs;
+    }
+    expireMessage(message) {
+        this.acceptedMessageIds.delete(message.messageId);
+        this.settleDelivery(message.messageId, "expired");
+    }
+    dropExpiredQueuedMessages() {
+        let dropped = 0;
+        for (let index = this.queue.length - 1; index >= 0; index -= 1) {
+            const message = this.queue[index];
+            if (message === undefined || !this.messageExpired(message))
+                continue;
+            this.queue.splice(index, 1);
+            this.expireMessage(message);
+            dropped += 1;
+        }
+        if (dropped > 0)
+            this.bumpRevision();
+    }
+    beginRequest(method) {
+        if (!V1_METHOD_SET.has(method) || this.inFlightMethod !== null) {
+            throw new CodexConnectorError("ROUTE_BUSY");
+        }
+        this.inFlightMethod = method;
+        this.bumpRevision();
+        this.emit("request_started", { operation: method });
+    }
+    finishRequest(method) {
+        if (this.inFlightMethod !== method)
+            return;
+        this.inFlightMethod = null;
+        this.bumpRevision();
+        if (this.routeStatus === "idle")
+            this.scheduleDrain();
+    }
+    request(method, params) {
+        if (method !== "initialize" && !V1_METHOD_SET.has(method)) {
+            return Promise.reject(new CodexConnectorError("METHOD_NOT_ALLOWED"));
+        }
+        if (method === "initialize") {
+            if (this.initializeRequested || this.connection !== "connecting") {
+                return Promise.reject(new CodexConnectorError("METHOD_NOT_ALLOWED"));
+            }
+            this.initializeRequested = true;
+        }
+        else if (!this.initialized) {
+            return Promise.reject(new CodexConnectorError("CONNECTOR_CLOSED"));
+        }
+        if (this.connection === "closed" || this.connection === "faulted") {
+            return Promise.reject(new CodexConnectorError("CONNECTOR_CLOSED"));
+        }
+        const id = this.nextRequestId;
+        this.nextRequestId += 1;
+        if (!Number.isSafeInteger(this.nextRequestId)) {
+            return Promise.reject(new CodexConnectorError("PROTOCOL_ERROR"));
+        }
+        const payload = JSON.stringify({ id, method, params });
+        if (Buffer.byteLength(payload, "utf8") > this.maxFrameBytes) {
+            return Promise.reject(new CodexConnectorError("INPUT_INVALID"));
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                const pending = this.pending.get(id);
+                if (pending === undefined)
+                    return;
+                this.pending.delete(id);
+                this.consecutiveRequestTimeouts += 1;
+                pending.reject(new CodexConnectorError("REQUEST_TIMEOUT", true));
+                if (this.consecutiveRequestTimeouts >= 2) {
+                    queueMicrotask(() => {
+                        if (this.connection === "ready") {
+                            this.protocolFault("REQUEST_TIMEOUT");
+                        }
+                    });
+                }
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { method, reject, resolve, timer });
+            let write;
+            try {
+                write = this.transport.send(payload);
+            }
+            catch {
+                write = Promise.reject(new CodexConnectorError("TRANSPORT_WRITE_FAILED", true));
+            }
+            void write.catch(() => {
+                const pending = this.pending.get(id);
+                if (pending === undefined)
+                    return;
+                this.pending.delete(id);
+                clearTimeout(pending.timer);
+                pending.reject(new CodexConnectorError("TRANSPORT_WRITE_FAILED", true));
+            });
+        });
+    }
+    handlePayload(payload) {
+        if (Buffer.byteLength(payload, "utf8") > this.maxFrameBytes) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(payload);
+        }
+        catch {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        if (!isRecord(parsed)) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        if (typeof parsed.method === "string") {
+            if (parsed.id === undefined)
+                this.handleNotification(parsed.method, parsed.params);
+            else
+                this.handleServerRequest(parsed.method, parsed.params);
+            return;
+        }
+        if (parsed.id === undefined) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        if (!Number.isSafeInteger(parsed.id) || typeof parsed.id !== "number") {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        const pending = this.pending.get(parsed.id);
+        if (pending === undefined) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        const hasResult = Object.hasOwn(parsed, "result");
+        const hasError = Object.hasOwn(parsed, "error");
+        if (hasResult === hasError) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        this.pending.delete(parsed.id);
+        clearTimeout(pending.timer);
+        this.consecutiveRequestTimeouts = 0;
+        if (hasError) {
+            if (!isRecord(parsed.error) ||
+                typeof parsed.error.code !== "number" ||
+                !Number.isSafeInteger(parsed.error.code)) {
+                pending.reject(new CodexConnectorError("PROTOCOL_ERROR", true));
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            // Deliberately discard the server's free-form error message/data.
+            pending.reject(new CodexConnectorError("RPC_REJECTED"));
+            return;
+        }
+        pending.resolve(parsed.result);
+    }
+    handleNotification(method, params) {
+        if (method === "item/completed") {
+            this.captureCompletedAgentMessage(params);
+            return;
+        }
+        if (method === "thread/settings/updated") {
+            if (!isRecord(params) || typeof params.threadId !== "string") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (params.threadId !== this.route.threadId)
+                return;
+            // Native settings remain owned by Codex. Registration is the Embassy
+            // reachability boundary, so a settings update neither blocks the route
+            // nor drops already accepted messages.
+            return;
+        }
+        if (method === "thread/status/changed") {
+            if (!isRecord(params) || typeof params.threadId !== "string") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (params.threadId !== this.route.threadId)
+                return;
+            const status = parseRouteStatus(params.status);
+            if (status === null) {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            const reservedRefreshInFlight = this.routeStatus === "starting" &&
+                this.activeMessageId !== null &&
+                this.activeTurnId === null &&
+                !this.ownsActiveTurn &&
+                this.inFlightMethod === "thread/resume";
+            const ownedStartInFlight = this.activeMessageId !== null &&
+                this.activeTurnId === null &&
+                this.ownsActiveTurn &&
+                this.inFlightMethod === "turn/start";
+            if (status === "idle" &&
+                (reservedRefreshInFlight || ownedStartInFlight)) {
+                // This idle belongs to the external turn whose completion released the
+                // queue. Do not let it invalidate the exact refresh epoch or reopen the
+                // drain while the reserved message crosses the refresh/start boundary.
+                return;
+            }
+            this.statusEpoch += 1;
+            if (status === "idle" && this.activeTurnId !== null) {
+                // Wait for the correlated turn/completed notification before draining.
+                return;
+            }
+            if (status === "not_loaded") {
+                this.clearTurnWatchdog();
+                this.selectedThreadObserved = false;
+                this.settleActiveDelivery("ambiguous");
+                this.activeTurnId = null;
+                this.activeMessageId = null;
+                this.ownsActiveTurn = false;
+                this.clearTransientReply();
+                this.dropQueuedMessages();
+            }
+            if (status === "active" &&
+                this.routeStatus === "interrupting" &&
+                this.activeTurnId !== null) {
+                return;
+            }
+            this.setRouteStatus(status);
+            if ((status === "active" || status === "waiting_approval") &&
+                this.ownsActiveTurn &&
+                this.activeTurnId !== null) {
+                this.armTurnWatchdog();
+            }
+            this.emit(status === "waiting_approval"
+                ? "approval_waiting"
+                : "route_status_changed");
+            if (status === "idle")
+                this.scheduleDrain();
+            return;
+        }
+        if (method === "thread/closed") {
+            if (!isRecord(params) || typeof params.threadId !== "string") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (params.threadId !== this.route.threadId)
+                return;
+            this.settleActiveDelivery("ambiguous");
+            this.clearTurnWatchdog();
+            this.activeTurnId = null;
+            this.selectedThreadObserved = false;
+            this.activeMessageId = null;
+            this.ownsActiveTurn = false;
+            this.clearTransientReply();
+            this.dropQueuedMessages();
+            this.setRouteStatus("not_loaded");
+            this.emit("route_status_changed");
+            return;
+        }
+        if (method === "turn/started") {
+            if (!isRecord(params) ||
+                typeof params.threadId !== "string") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (params.threadId !== this.route.threadId)
+                return;
+            const turn = parseTurn(params.turn);
+            if (turn === null ||
+                turn.status !== "inProgress") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (!this.ownsActiveTurn && this.activeMessageId === null) {
+                if (this.lastCompletedTurnId === turn.id)
+                    return;
+                if (this.activeTurnId !== null && this.activeTurnId !== turn.id) {
+                    this.protocolFault("PROTOCOL_ERROR");
+                    return;
+                }
+                this.activeTurnId = turn.id;
+                this.setRouteStatus("active");
+                this.emit("turn_started");
+                return;
+            }
+            if (!this.ownsActiveTurn || this.activeMessageId === null) {
+                return;
+            }
+            if (this.lastCompletedTurnId === turn.id)
+                return;
+            if (this.activeTurnId !== null && this.activeTurnId !== turn.id) {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            this.activeTurnId = turn.id;
+            this.ownsActiveTurn =
+                this.ownsActiveTurn && this.activeMessageId !== null;
+            this.setRouteStatus("active");
+            this.emit("turn_started");
+            this.armTurnWatchdog();
+            return;
+        }
+        if (method === "turn/completed") {
+            if (!isRecord(params) ||
+                typeof params.threadId !== "string") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (params.threadId !== this.route.threadId)
+                return;
+            const turn = parseTurn(params.turn);
+            if (turn === null ||
+                (turn.status !== "completed" &&
+                    turn.status !== "failed" &&
+                    turn.status !== "interrupted")) {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            const outcome = turn.status;
+            this.clearTurnWatchdog();
+            if (!this.ownsActiveTurn || this.activeMessageId === null) {
+                // An approval request from another client records the external turn ID
+                // so Embassy can wait without answering it. Its terminal notification
+                // must release that observation and any queued Embassy work, while
+                // never claiming or settling the external turn as gateway-owned.
+                if (this.ownsActiveTurn || this.activeMessageId !== null) {
+                    this.protocolFault("PROTOCOL_ERROR");
+                    return;
+                }
+                if (this.activeTurnId === null)
+                    return;
+                if (this.activeTurnId !== turn.id) {
+                    this.protocolFault("PROTOCOL_ERROR");
+                    return;
+                }
+                this.activeTurnId = null;
+                this.lastCompletedTurnId = turn.id;
+                this.clearTransientReply();
+                this.setRouteStatus(outcome === "failed" ? "system_error" : "idle");
+                this.emit("turn_completed", { turnOutcome: outcome });
+                if (outcome !== "failed")
+                    this.scheduleDrain();
+                return;
+            }
+            if (this.activeTurnId === null)
+                return;
+            if (this.activeTurnId !== turn.id) {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            const messageId = this.activeMessageId;
+            const reply = this.transientReply;
+            const replyTooLarge = this.transientReplyTooLarge;
+            this.activeTurnId = null;
+            this.lastCompletedTurnId = turn.id;
+            this.activeMessageId = null;
+            this.ownsActiveTurn = false;
+            this.clearTransientReply();
+            this.setRouteStatus(outcome === "failed" ? "system_error" : "idle");
+            this.emit("turn_completed", { turnOutcome: outcome });
+            if (messageId !== null) {
+                const text = outcome === "completed" && !replyTooLarge ? reply : null;
+                const replyCode = replyTooLarge
+                    ? "REPLY_TOO_LARGE"
+                    : text === null
+                        ? "REPLY_UNAVAILABLE"
+                        : null;
+                this.settleDelivery(messageId, outcome, text, replyCode);
+            }
+            if (outcome !== "failed")
+                this.scheduleDrain();
+            return;
+        }
+        if (method === "serverRequest/resolved") {
+            if (!isRecord(params) || typeof params.threadId !== "string") {
+                this.protocolFault("PROTOCOL_ERROR");
+                return;
+            }
+            if (params.threadId === this.route.threadId &&
+                this.routeStatus === "waiting_approval") {
+                this.setRouteStatus("active");
+                this.emit("route_status_changed");
+            }
+            return;
+        }
+        if (method === "warning" || method === "configWarning") {
+            this.emit("server_warning");
+        }
+        // Every other notification is ignored after the global frame bound. Raw
+        // item/model/tool payloads are neither normalized nor retained.
+    }
+    handleServerRequest(method, params) {
+        if (!APPROVAL_REQUEST_METHODS.has(method)) {
+            this.emit("server_request_ignored");
+            return;
+        }
+        if (!isRecord(params) ||
+            typeof params.threadId !== "string" ||
+            typeof params.turnId !== "string" ||
+            !validOpaqueId(params.turnId)) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        if (params.threadId !== this.route.threadId)
+            return;
+        if (this.activeTurnId !== null && this.activeTurnId !== params.turnId) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        this.activeTurnId = params.turnId;
+        // Do not acquire ownership merely by observing another client's approval.
+        this.setRouteStatus("waiting_approval");
+        this.emit("approval_waiting");
+        // Intentionally no JSON-RPC response: the gateway is not an approval UI or
+        // authority. The owning Desktop client must resolve the request.
+    }
+    captureCompletedAgentMessage(params) {
+        if (!this.ownsActiveTurn ||
+            this.activeMessageId === null ||
+            this.activeTurnId === null) {
+            return;
+        }
+        if (!isRecord(params) ||
+            typeof params.threadId !== "string" ||
+            typeof params.turnId !== "string" ||
+            !isRecord(params.item)) {
+            this.protocolFault("PROTOCOL_ERROR");
+            return;
+        }
+        if (params.threadId !== this.route.threadId)
+            return;
+        if (params.turnId !== this.activeTurnId) {
+            return;
+        }
+        const item = params.item;
+        if (item.type !== "agentMessage")
+            return;
+        if (item.phase !== undefined && item.phase !== "final_answer")
+            return;
+        if (typeof item.text !== "string" || item.text.includes("\0"))
+            return;
+        const replyBytes = Buffer.byteLength(item.text, "utf8");
+        if (replyBytes === 0)
+            return;
+        if (replyBytes > this.maxReplyBytes) {
+            this.transientReply = null;
+            this.transientReplyTooLarge = true;
+            return;
+        }
+        this.transientReply = item.text;
+        this.transientReplyTooLarge = false;
+        this.armTurnWatchdog();
+    }
+    clearTransientReply() {
+        this.transientReply = null;
+        this.transientReplyTooLarge = false;
+    }
+    settleDelivery(messageId, outcome, text = null, replyCode = "REPLY_UNAVAILABLE") {
+        try {
+            this.onTurnResult?.({ messageId, outcome, replyCode, text });
+        }
+        catch {
+            // Delivery consumers cannot alter transport or route state. Any reply
+            // text is dropped immediately after this synchronous handoff.
+        }
+    }
+    settleActiveDelivery(outcome) {
+        this.clearTurnWatchdog();
+        if (this.activeMessageId !== null) {
+            this.settleDelivery(this.activeMessageId, outcome);
+        }
+        this.activeMessageId = null;
+        this.ownsActiveTurn = false;
+        this.clearTransientReply();
+    }
+    setRouteStatus(status) {
+        if (this.routeStatus === status)
+            return;
+        this.routeStatus = status;
+        this.bumpRevision();
+    }
+    bumpRevision() {
+        this.revision += 1;
+        if (!Number.isSafeInteger(this.revision)) {
+            this.protocolFault("PROTOCOL_ERROR");
+        }
+    }
+    emit(kind, details) {
+        this.eventSequence += 1;
+        const event = {
+            ...this.observation(),
+            kind,
+            timestamp: this.now().toISOString(),
+            ...(details === undefined ? {} : { details }),
+        };
+        try {
+            this.onEvent?.(event);
+        }
+        catch {
+            // Monitoring consumers cannot affect routing or protocol state.
+        }
+    }
+    dropQueuedMessages() {
+        const dropped = this.queue.length;
+        for (const message of this.queue) {
+            this.settleDelivery(message.messageId, "abandoned");
+        }
+        this.queue.length = 0;
+        if (dropped > 0)
+            this.bumpRevision();
+        return dropped;
+    }
+    normalizeError(error, ambiguousFallback) {
+        return error instanceof CodexConnectorError
+            ? error
+            : new CodexConnectorError("PROTOCOL_ERROR", ambiguousFallback);
+    }
+    handleActionError(error) {
+        const normalized = this.normalizeError(error, true);
+        if (normalized.code === "PROTOCOL_ERROR" ||
+            normalized.code === "RESULT_SCHEMA_MISMATCH" ||
+            normalized.code === "TRANSPORT_WRITE_FAILED" ||
+            normalized.code === "TRANSPORT_CLOSED") {
+            this.protocolFault(normalized.code);
+        }
+    }
+    rejectPending(code) {
+        for (const [id, pending] of this.pending) {
+            this.pending.delete(id);
+            clearTimeout(pending.timer);
+            pending.reject(new CodexConnectorError(code, true));
+        }
+    }
+    protocolFault(code) {
+        if (this.faulting || this.connection === "faulted")
+            return;
+        this.faulting = true;
+        this.connection = "faulted";
+        this.initialized = false;
+        this.routeStatus = "stale";
+        this.selectedThreadObserved = false;
+        this.clearTurnWatchdog();
+        this.settleActiveDelivery("ambiguous");
+        this.activeTurnId = null;
+        const droppedMessages = this.dropQueuedMessages();
+        this.inFlightMethod = null;
+        this.bumpRevision();
+        this.rejectPending(code);
+        this.emit("protocol_fault", { droppedMessages, errorCode: code });
+        void this.transport.close().catch(() => undefined);
+        for (const remove of this.unlisten.splice(0))
+            remove();
+        this.faulting = false;
+    }
+    handleDisconnect() {
+        if (this.connection === "closed" || this.connection === "faulted")
+            return;
+        this.connection = "closed";
+        this.initialized = false;
+        this.routeStatus = "stale";
+        this.selectedThreadObserved = false;
+        this.clearTurnWatchdog();
+        this.settleActiveDelivery("ambiguous");
+        this.activeTurnId = null;
+        const droppedMessages = this.dropQueuedMessages();
+        this.inFlightMethod = null;
+        this.bumpRevision();
+        this.rejectPending("TRANSPORT_CLOSED");
+        this.emit("connection_closed", {
+            droppedMessages,
+            ...(!this.expectedClose ? { errorCode: "TRANSPORT_CLOSED" } : {}),
+        });
+        for (const remove of this.unlisten.splice(0))
+            remove();
+    }
+    armTurnWatchdog(delayMs = this.turnWatchdogMs) {
+        this.clearTurnWatchdog();
+        if (this.connection !== "ready" ||
+            !this.ownsActiveTurn ||
+            this.activeMessageId === null ||
+            this.activeTurnId === null) {
+            return;
+        }
+        this.turnWatchdogTimer = setTimeout(() => {
+            this.turnWatchdogTimer = undefined;
+            void this.probeOwnedTurnStatus();
+        }, delayMs);
+        this.turnWatchdogTimer.unref();
+    }
+    clearTurnWatchdog() {
+        if (this.turnWatchdogTimer === undefined)
+            return;
+        clearTimeout(this.turnWatchdogTimer);
+        this.turnWatchdogTimer = undefined;
+    }
+    async probeOwnedTurnStatus() {
+        if (this.connection !== "ready" ||
+            !this.ownsActiveTurn ||
+            this.activeMessageId === null ||
+            this.activeTurnId === null) {
+            return;
+        }
+        if (this.inFlightMethod !== null) {
+            this.armTurnWatchdog(Math.min(this.turnWatchdogMs, this.requestTimeoutMs));
+            return;
+        }
+        const watchedMessageId = this.activeMessageId;
+        const watchedTurnId = this.activeTurnId;
+        this.beginRequest("thread/resume");
+        try {
+            const result = await this.request("thread/resume", {
+                excludeTurns: true,
+                threadId: this.route.threadId,
+            });
+            if (!isRecord(result) ||
+                !isRecord(result.thread) ||
+                result.thread.id !== this.route.threadId ||
+                !Array.isArray(result.thread.turns) ||
+                result.thread.turns.length !== 0) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            const status = parseRouteStatus(result.thread.status);
+            if (status === null) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            if (!this.ownsActiveTurn ||
+                this.activeMessageId !== watchedMessageId ||
+                this.activeTurnId !== watchedTurnId) {
+                return;
+            }
+            if (status === "active" || status === "waiting_approval") {
+                this.setRouteStatus(status);
+                this.emit(status === "waiting_approval"
+                    ? "approval_waiting"
+                    : "route_status_changed");
+                this.armTurnWatchdog();
+                return;
+            }
+            this.settleActiveDelivery("ambiguous");
+            this.activeTurnId = null;
+            if (status === "not_loaded")
+                this.selectedThreadObserved = false;
+            this.setRouteStatus(status);
+            this.emit("route_status_changed");
+            if (status === "idle")
+                this.scheduleDrain();
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            this.handleActionError(normalized);
+            if (this.connection === "ready" &&
+                this.ownsActiveTurn &&
+                this.activeMessageId === watchedMessageId &&
+                this.activeTurnId === watchedTurnId) {
+                this.armTurnWatchdog();
+            }
+        }
+        finally {
+            this.finishRequest("thread/resume");
+        }
+    }
+}
+//# sourceMappingURL=codex-app-server.js.map