agent-embassy 1.5.0 → 1.6.0

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

@@ -1,4 +1,6 @@
 import { Buffer } from "node:buffer";
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
 import WebSocket from "ws";
 import { sharesCompatibilityMajor } from "./compatibility.js";
 /**
@@ -9,15 +11,33 @@ import { sharesCompatibilityMajor } from "./compatibility.js";
  * authorizes an interrupt or a generic/public JSON-RPC escape hatch.
  */
 export const CODEX_APP_SERVER_V1_METHODS = [
+    "account/rateLimits/read",
+    "model/list",
+    "thread/archive",
     "thread/loaded/list",
     "thread/resume",
+    "thread/start",
     "thread/unsubscribe",
     "turn/start",
     "turn/steer",
     "turn/interrupt",
 ];
+export const CODEX_PROBE_MODEL_PREFERENCE = ["gpt-5.6-luna"];
+export const CODEX_PROBE_EFFORT = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
+export const CODEX_WRITE_PROBE_INPUT = "Reply with exactly OK. Do not use tools.";
 /** Exact App Server builds whose writable v2 schema was reviewed. */
 export const CODEX_APP_SERVER_WRITABLE_VERSIONS = ["0.147.0"];
+export function codexWriteProbeFailure(safeErrorCode, evidence = {}) {
+    return {
+        ...(evidence.archivedThreadCount === 1 ? { archivedThreadCount: 1 } : {}),
+        outcome: "fail",
+        safeErrorCode,
+        settingsEchoObserved: evidence.settingsEchoObserved ?? false,
+        ...(evidence.tokenCount === undefined
+            ? {}
+            : { tokenCount: evidence.tokenCount }),
+    };
+}
 export class CodexConnectorError extends Error {
     ambiguous;
     code;
@@ -243,6 +263,9 @@ export class WebSocketDuplexTransport {
     }
 }
 const V1_METHOD_SET = new Set(CODEX_APP_SERVER_V1_METHODS);
+const PROBE_ONLY_METHODS = new Set([
+    "account/rateLimits/read", "model/list", "thread/archive", "thread/start",
+]);
 const OUTPUT_NOTIFICATION_OPT_OUTS = [
     "item/started",
     "item/agentMessage/delta",
@@ -252,6 +275,14 @@ const OUTPUT_NOTIFICATION_OPT_OUTS = [
     "turn/diff/updated",
     "turn/plan/updated",
 ];
+const PROBE_PASSIVE_ITEM_TYPES = new Set(["agentMessage", "reasoning", "userMessage"]);
+const PROBE_TOOL_NOTIFICATION_METHODS = new Set([
+    "item/autoApprovalReview/completed", "item/autoApprovalReview/started",
+    "item/commandExecution/terminalInteraction",
+    "item/fileChange/outputDelta", "item/fileChange/patchUpdated",
+    "item/mcpToolCall/progress",
+]);
+const MAX_PROBE_TOKEN_COUNT = 1_000_000_000;
 const APPROVAL_REQUEST_METHODS = new Set([
     "item/commandExecution/requestApproval",
     "item/fileChange/requestApproval",
@@ -270,6 +301,56 @@ function validOpaqueId(value, maximumLength = 256) {
         value.length <= maximumLength &&
         /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value));
 }
+function validUuidV7(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value);
+}
+function parseLoadedThreadIds(value) {
+    if (!isRecord(value) ||
+        !Array.isArray(value.data) ||
+        (value.nextCursor !== undefined && value.nextCursor !== null)) {
+        return null;
+    }
+    if (value.data.length > 100_000 ||
+        !value.data.every((threadId) => typeof threadId === "string" && validOpaqueId(threadId)) ||
+        new Set(value.data).size !== value.data.length) {
+        return null;
+    }
+    return value.data;
+}
+function rateLimitConstrained(value) {
+    if (!isRecord(value) || !isRecord(value.rateLimits))
+        return null;
+    const byLimit = value.rateLimitsByLimitId;
+    const snapshot = isRecord(byLimit) && isRecord(byLimit.codex)
+        ? byLimit.codex
+        : value.rateLimits;
+    const percent = (container, key) => {
+        if (container === null || container === undefined)
+            return Number.NaN;
+        if (!isRecord(container) || !Number.isSafeInteger(container[key]))
+            return null;
+        const result = container[key];
+        return result >= 0 && result <= 100 ? result : null;
+    };
+    const remaining = percent(snapshot.individualLimit, "remainingPercent");
+    const primary = percent(snapshot.primary, "usedPercent");
+    const secondary = percent(snapshot.secondary, "usedPercent");
+    if ([remaining, primary, secondary].includes(null))
+        return null;
+    if ((snapshot.rateLimitReachedType !== null &&
+        snapshot.rateLimitReachedType !== undefined) ||
+        snapshot.spendControlReached === true) {
+        return true;
+    }
+    if (snapshot.spendControlReached !== null &&
+        snapshot.spendControlReached !== undefined &&
+        snapshot.spendControlReached !== false) {
+        return null;
+    }
+    return ((!Number.isNaN(remaining) && remaining <= 5) ||
+        (!Number.isNaN(primary) && primary >= 95) ||
+        (!Number.isNaN(secondary) && secondary >= 95));
+}
 function validateRoute(route) {
     if (!validOpaqueId(route.threadId) ||
         !validOpaqueId(route.endpointGeneration, 128)) {
@@ -359,6 +440,8 @@ export class CodexAppServerConnector {
     nextRequestId = 1;
     ownsActiveTurn = false;
     pending = new Map();
+    probeAttempted = false;
+    probeRuntime = null;
     queue = [];
     revision = 0;
     routeStatus = "unknown";
@@ -383,6 +466,7 @@ export class CodexAppServerConnector {
     turnWatchdogMs;
     route;
     transport;
+    writeCompatibilityProbe;
     writesEnabled;
     constructor(options) {
         this.route = validateRoute(options.route);
@@ -395,11 +479,12 @@ export class CodexAppServerConnector {
             throw new CodexConnectorError("INVALID_CONFIGURATION");
         }
         this.writesEnabled = options.writesEnabled;
+        this.writeCompatibilityProbe = options.writeCompatibilityProbe === true;
         this.transport = options.transport;
         this.clientInfo = validateClientInfo(options.clientInfo ?? {
             name: "agent_embassy_gateway",
             title: "Embassy Gateway",
-            version: "1.5.0",
+            version: "1.6.0",
         });
         this.maxFrameBytes = positiveInteger(options.maxFrameBytes ?? DEFAULT_MAX_FRAME_BYTES, "INVALID_CONFIGURATION");
         this.maxDeadlineMs = positiveInteger(options.maxDeadlineMs ?? DEFAULT_MAX_DEADLINE_MS, "INVALID_CONFIGURATION");
@@ -709,6 +794,309 @@ export class CodexAppServerConnector {
             this.handleDisconnect();
         }
     }
+    /**
+     * Run the one fixed disposable-thread write probe. The method never exposes
+     * JSON-RPC, native IDs, content, or route state, and every failure settles as
+     * a safe result so compatibility discovery cannot take down the broker.
+     */
+    async runWriteCompatibilityProbe(input) {
+        if (this.probeAttempted) {
+            return codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        }
+        this.probeAttempted = true;
+        let threadId = null;
+        let archivedThreadCount;
+        let result = codexWriteProbeFailure("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+        try {
+            if (!this.writeCompatibilityProbe ||
+                this.connection !== "ready" ||
+                this.inFlightMethod !== null ||
+                this.pending.size !== 0 ||
+                !isAbsolute(input.cwd) ||
+                !Array.isArray(input.forbiddenThreadIds) ||
+                !input.forbiddenThreadIds.every((value) => typeof value === "string" && validOpaqueId(value))) {
+                return result;
+            }
+            const beforeStat = await stat(input.cwd, { bigint: true });
+            const beforeEntries = await readdir(input.cwd);
+            if (!beforeStat.isDirectory() ||
+                beforeStat.uid !== BigInt(process.getuid?.() ?? -1) ||
+                (beforeStat.mode & 511n) !== 448n ||
+                beforeEntries.length !== 0) {
+                return result;
+            }
+            const limits = rateLimitConstrained(await this.request("account/rateLimits/read", null));
+            if (limits === null)
+                return result;
+            if (limits) {
+                return codexWriteProbeFailure("CODEX_WRITE_PROBE_RATE_LIMIT_CONSTRAINED");
+            }
+            const selection = this.selectProbeModel(await this.request("model/list", {
+                includeHidden: true,
+                limit: 100,
+            }).catch(() => null));
+            if (selection === null) {
+                return codexWriteProbeFailure("CODEX_WRITE_PROBE_MODEL_PIN_UNAVAILABLE");
+            }
+            const [model, effort] = selection;
+            const loadedBefore = parseLoadedThreadIds(await this.request("thread/loaded/list", {}));
+            if (loadedBefore === null)
+                return result;
+            const runtime = {
+                expectedCwd: input.cwd,
+                expectedEffort: effort,
+                expectedModel: model,
+                failCode: null,
+                phase: "awaiting_start",
+                resolveTurn: null,
+                settingsEchoObserved: false,
+                settingsThreadId: null,
+                threadId: null,
+                tokenCount: null,
+                turnId: null,
+            };
+            this.probeRuntime = runtime;
+            const started = await this.request("thread/start", {
+                allowProviderModelFallback: false,
+                approvalPolicy: "never",
+                cwd: input.cwd,
+                dynamicTools: [],
+                environments: [],
+                ephemeral: false,
+                model,
+                runtimeWorkspaceRoots: [],
+                sandbox: "read-only",
+                selectedCapabilityRoots: [],
+            });
+            const candidateThreadId = this.probeCleanupThreadId(started, loadedBefore, input.forbiddenThreadIds);
+            if (candidateThreadId === null ||
+                !this.validateProbeThread(started, input.cwd, model, candidateThreadId)) {
+                throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+            }
+            threadId = candidateThreadId;
+            runtime.threadId = candidateThreadId;
+            if (runtime.settingsThreadId !== null &&
+                runtime.settingsThreadId !== candidateThreadId) {
+                runtime.failCode = "CODEX_WRITE_PROBE_THREAD_SETUP_FAILED";
+            }
+            if (runtime.failCode === null) {
+                const turnResult = await this.request("turn/start", {
+                    approvalPolicy: "never",
+                    cwd: input.cwd,
+                    effort,
+                    environments: [],
+                    input: [{ text: CODEX_WRITE_PROBE_INPUT, type: "text" }],
+                    model,
+                    runtimeWorkspaceRoots: [],
+                    sandboxPolicy: { networkAccess: false, type: "readOnly" },
+                    threadId,
+                });
+                const turn = isRecord(turnResult) ? parseTurn(turnResult.turn) : null;
+                if (turn === null ||
+                    !isRecord(turnResult) ||
+                    !isRecord(turnResult.turn) ||
+                    !Array.isArray(turnResult.turn.items) ||
+                    (turn.status !== "inProgress" && turn.status !== "completed")) {
+                    throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+                }
+                if (runtime.turnId !== null && runtime.turnId !== turn.id) {
+                    throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH", true);
+                }
+                runtime.turnId = turn.id;
+                await this.waitForProbeTurn(runtime);
+            }
+            if (runtime.failCode !== null) {
+                result = codexWriteProbeFailure(runtime.failCode, {
+                    settingsEchoObserved: runtime.settingsEchoObserved,
+                    ...(runtime.tokenCount === null
+                        ? {}
+                        : { tokenCount: runtime.tokenCount }),
+                });
+            }
+            else if (runtime.phase === "terminal" &&
+                runtime.tokenCount !== null) {
+                const afterStat = await stat(input.cwd, { bigint: true });
+                const afterEntries = await readdir(input.cwd);
+                if (afterEntries.length === 0 &&
+                    afterStat.dev === beforeStat.dev &&
+                    afterStat.ino === beforeStat.ino &&
+                    afterStat.mtimeNs === beforeStat.mtimeNs &&
+                    afterStat.uid === beforeStat.uid &&
+                    afterStat.mode === beforeStat.mode) {
+                    result = {
+                        archivedThreadCount: 1,
+                        outcome: "pass",
+                        settingsEchoObserved: runtime.settingsEchoObserved,
+                        tokenCount: runtime.tokenCount,
+                    };
+                }
+                else {
+                    result = codexWriteProbeFailure("CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED", {
+                        settingsEchoObserved: runtime.settingsEchoObserved,
+                        tokenCount: runtime.tokenCount,
+                    });
+                }
+            }
+        }
+        catch (error) {
+            const normalized = this.normalizeError(error, true);
+            const runtime = this.probeRuntime;
+            result = codexWriteProbeFailure(normalized.code === "REQUEST_TIMEOUT"
+                ? "CODEX_WRITE_PROBE_TIMEOUT"
+                : "CODEX_WRITE_PROBE_THREAD_SETUP_FAILED", {
+                settingsEchoObserved: runtime?.settingsEchoObserved ?? false,
+                ...(runtime?.tokenCount === null || runtime?.tokenCount === undefined
+                    ? {}
+                    : { tokenCount: runtime.tokenCount }),
+            });
+        }
+        finally {
+            const runtime = this.probeRuntime;
+            if (threadId !== null &&
+                runtime !== null &&
+                runtime.turnId !== null &&
+                (result.outcome === "fail" || runtime.failCode !== null)) {
+                try {
+                    await this.request("turn/interrupt", {
+                        threadId,
+                        turnId: runtime.turnId,
+                    });
+                }
+                catch {
+                    // Archival remains the one required cleanup proof below.
+                }
+            }
+            let cleanupUnconfirmed = runtime !== null && threadId === null;
+            if (threadId !== null) {
+                try {
+                    const archived = await this.request("thread/archive", { threadId });
+                    if (!isRecord(archived) || Object.keys(archived).length !== 0) {
+                        throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+                    }
+                    archivedThreadCount = 1;
+                    const unsubscribed = await this.request("thread/unsubscribe", {
+                        threadId,
+                    });
+                    if (!isRecord(unsubscribed) ||
+                        (unsubscribed.status !== "unsubscribed" &&
+                            unsubscribed.status !== "notSubscribed" &&
+                            unsubscribed.status !== "notLoaded")) {
+                        throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+                    }
+                    const loadedAfter = parseLoadedThreadIds(await this.request("thread/loaded/list", {}));
+                    if (loadedAfter === null || loadedAfter.includes(threadId)) {
+                        throw new CodexConnectorError("RESULT_SCHEMA_MISMATCH");
+                    }
+                }
+                catch {
+                    cleanupUnconfirmed = true;
+                }
+            }
+            const tokenCount = runtime?.tokenCount ?? result.tokenCount;
+            const evidence = {
+                ...(archivedThreadCount === undefined ? {} : { archivedThreadCount }),
+                settingsEchoObserved: runtime?.settingsEchoObserved ?? result.settingsEchoObserved,
+                ...(tokenCount === undefined ? {} : { tokenCount }),
+            };
+            if (cleanupUnconfirmed || (result.outcome === "pass" && archivedThreadCount !== 1)) {
+                result = codexWriteProbeFailure("CODEX_WRITE_PROBE_CLEANUP_UNCONFIRMED", evidence);
+            }
+            else if (runtime?.failCode !== null && runtime?.failCode !== undefined) {
+                result = codexWriteProbeFailure(runtime.failCode, evidence);
+            }
+            if (result.outcome === "fail") {
+                result = codexWriteProbeFailure(result.safeErrorCode, evidence);
+            }
+            this.probeRuntime = null;
+        }
+        return result;
+    }
+    selectProbeModel(value) {
+        if (!isRecord(value) || !Array.isArray(value.data) || value.data.length > 100) {
+            return null;
+        }
+        const data = value.data;
+        for (const model of CODEX_PROBE_MODEL_PREFERENCE) {
+            const candidate = data.find((entry) => isRecord(entry) &&
+                entry.model === model &&
+                entry.hidden === false);
+            if (!isRecord(candidate) || !Array.isArray(candidate.supportedReasoningEfforts)) {
+                continue;
+            }
+            const supported = candidate.supportedReasoningEfforts;
+            const effort = CODEX_PROBE_EFFORT.find((preference) => supported.some((option) => isRecord(option) && option.reasoningEffort === preference));
+            if (effort !== undefined)
+                return [model, effort];
+        }
+        return null;
+    }
+    probeCleanupThreadId(value, loadedBefore, forbiddenThreadIds) {
+        if (!isRecord(value) ||
+            !isRecord(value.thread) ||
+            typeof value.thread.id !== "string" ||
+            !validUuidV7(value.thread.id) ||
+            value.thread.id === this.route.threadId ||
+            loadedBefore.includes(value.thread.id) ||
+            forbiddenThreadIds.includes(value.thread.id)) {
+            return null;
+        }
+        return value.thread.id;
+    }
+    validateProbeThread(value, cwd, model, threadId) {
+        if (!isRecord(value) || !isRecord(value.thread))
+            return false;
+        const roots = value.runtimeWorkspaceRoots;
+        const networkAccess = isRecord(value.sandbox)
+            ? value.sandbox.networkAccess
+            : undefined;
+        return (value.approvalPolicy === "never" &&
+            value.cwd === cwd &&
+            value.model === model &&
+            isRecord(value.sandbox) &&
+            value.sandbox.type === "readOnly" &&
+            (networkAccess === undefined || networkAccess === false) &&
+            (roots === undefined || (Array.isArray(roots) && roots.length === 0)) &&
+            value.thread.id === threadId &&
+            value.thread.cwd === cwd &&
+            value.thread.ephemeral === false &&
+            isRecord(value.thread.status) &&
+            value.thread.status.type === "idle" &&
+            Array.isArray(value.thread.turns) &&
+            value.thread.turns.length === 0);
+    }
+    async waitForProbeTurn(runtime) {
+        if (runtime.failCode !== null ||
+            (runtime.phase === "terminal" && runtime.tokenCount !== null)) {
+            return;
+        }
+        let timer;
+        await new Promise((resolve) => {
+            runtime.resolveTurn = resolve;
+            timer = setTimeout(resolve, this.turnWatchdogMs);
+        });
+        runtime.resolveTurn = null;
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (runtime.failCode === null &&
+            !(runtime.phase === "terminal" && runtime.tokenCount !== null)) {
+            runtime.failCode = "CODEX_WRITE_PROBE_TIMEOUT";
+        }
+    }
+    settleProbeRuntime() {
+        const runtime = this.probeRuntime;
+        if (runtime === null || runtime.resolveTurn === null)
+            return;
+        if (runtime.failCode !== null ||
+            (runtime.phase === "terminal" && runtime.tokenCount !== null)) {
+            runtime.resolveTurn();
+        }
+    }
+    settleProbeConnectionLoss() {
+        if (this.probeRuntime === null)
+            return;
+        this.probeRuntime.failCode ??= "CODEX_WRITE_PROBE_THREAD_SETUP_FAILED";
+        this.settleProbeRuntime();
+    }
     async initialize() {
         try {
             const result = await this.request("initialize", {
@@ -717,7 +1105,7 @@ export class CodexAppServerConnector {
                     // 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],
+                    optOutNotificationMethods: OUTPUT_NOTIFICATION_OPT_OUTS.filter((method) => method !== "item/started" || !this.writeCompatibilityProbe),
                 },
                 clientInfo: this.clientInfo,
             });
@@ -1085,6 +1473,11 @@ export class CodexAppServerConnector {
         if (method !== "initialize" && !V1_METHOD_SET.has(method)) {
             return Promise.reject(new CodexConnectorError("METHOD_NOT_ALLOWED"));
         }
+        if (method !== "initialize" &&
+            PROBE_ONLY_METHODS.has(method) &&
+            !this.writeCompatibilityProbe) {
+            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"));
@@ -1201,6 +1594,8 @@ export class CodexAppServerConnector {
         pending.resolve(parsed.result);
     }
     handleNotification(method, params) {
+        if (this.handleProbeNotification(method, params))
+            return;
         if (method === "item/completed") {
             this.handleCompletedItem(params);
             return;
@@ -1430,6 +1825,14 @@ export class CodexAppServerConnector {
         // item/model/tool payloads are neither normalized nor retained.
     }
     handleServerRequest(method, params) {
+        if (this.probeRuntime !== null &&
+            isRecord(params) &&
+            params.threadId === this.probeRuntime.threadId) {
+            this.probeRuntime.failCode ??=
+                "CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED";
+            this.settleProbeRuntime();
+            return;
+        }
         if (!APPROVAL_REQUEST_METHODS.has(method)) {
             this.emit("server_request_ignored");
             return;
@@ -1454,6 +1857,135 @@ export class CodexAppServerConnector {
         // Intentionally no JSON-RPC response: the gateway is not an approval UI or
         // authority. The owning Desktop client must resolve the request.
     }
+    handleProbeNotification(method, params) {
+        const runtime = this.probeRuntime;
+        if (runtime === null)
+            return false;
+        const fail = (code) => {
+            runtime.failCode ??= code;
+            this.settleProbeRuntime();
+        };
+        if (method === "model/rerouted") {
+            fail("CODEX_WRITE_PROBE_MODEL_REROUTED");
+            return true;
+        }
+        if (!isRecord(params))
+            return false;
+        const observeTurnId = (value) => {
+            if (typeof value !== "string" || !validOpaqueId(value))
+                return false;
+            if (runtime.turnId !== null && runtime.turnId !== value)
+                return false;
+            runtime.turnId = value;
+            return true;
+        };
+        if (method === "thread/settings/updated") {
+            runtime.settingsEchoObserved = true;
+            const settingsThreadId = params.threadId;
+            const settings = params.threadSettings;
+            const sandbox = isRecord(settings) ? settings.sandboxPolicy : null;
+            if (typeof settingsThreadId !== "string" ||
+                !validUuidV7(settingsThreadId) ||
+                (runtime.threadId !== null && runtime.threadId !== settingsThreadId) ||
+                (runtime.settingsThreadId !== null &&
+                    runtime.settingsThreadId !== settingsThreadId) ||
+                !isRecord(settings) ||
+                settings.cwd !== runtime.expectedCwd ||
+                settings.model !== runtime.expectedModel ||
+                settings.approvalPolicy !== "never" ||
+                (settings.effort !== undefined &&
+                    settings.effort !== runtime.expectedEffort) ||
+                !isRecord(sandbox) ||
+                sandbox.type !== "readOnly" ||
+                (sandbox.networkAccess !== undefined &&
+                    sandbox.networkAccess !== false)) {
+                fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            else {
+                runtime.settingsThreadId = settingsThreadId;
+            }
+            return true;
+        }
+        if (runtime.threadId === null || params.threadId !== runtime.threadId) {
+            return false;
+        }
+        if (PROBE_TOOL_NOTIFICATION_METHODS.has(method)) {
+            fail("CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED");
+            return true;
+        }
+        if (method === "thread/tokenUsage/updated") {
+            const totalTokens = observeTurnId(params.turnId) &&
+                isRecord(params.tokenUsage) &&
+                isRecord(params.tokenUsage.last)
+                ? params.tokenUsage.last.totalTokens
+                : null;
+            if (!Number.isSafeInteger(totalTokens) ||
+                totalTokens < 0 ||
+                totalTokens > MAX_PROBE_TOKEN_COUNT) {
+                fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            else {
+                runtime.tokenCount = totalTokens;
+                this.settleProbeRuntime();
+            }
+            return true;
+        }
+        if (method === "turn/started" || method === "turn/completed") {
+            const turn = parseTurn(params.turn);
+            if (turn === null ||
+                !isRecord(params.turn) ||
+                !Array.isArray(params.turn.items) ||
+                !observeTurnId(turn.id)) {
+                fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            else if (method === "turn/started") {
+                if (turn.status !== "inProgress" ||
+                    runtime.phase !== "awaiting_start") {
+                    fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+                }
+                else {
+                    runtime.phase = "started";
+                }
+            }
+            else if (turn.status === "completed" &&
+                runtime.phase === "item_completed") {
+                runtime.phase = "terminal";
+                this.settleProbeRuntime();
+            }
+            else {
+                fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            return true;
+        }
+        if (method === "item/started" || method === "item/completed") {
+            const observedAt = method === "item/started" ? params.startedAtMs : params.completedAtMs;
+            const itemType = isRecord(params.item) ? params.item.type : null;
+            if (typeof itemType === "string" &&
+                !PROBE_PASSIVE_ITEM_TYPES.has(itemType)) {
+                fail("CODEX_WRITE_PROBE_TOOL_ACTIVITY_OBSERVED");
+                return true;
+            }
+            if (!observeTurnId(params.turnId) ||
+                !isRecord(params.item) ||
+                typeof itemType !== "string" ||
+                !Number.isSafeInteger(observedAt) ||
+                observedAt < 0 ||
+                (runtime.phase !== "started" && runtime.phase !== "item_completed")) {
+                fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+            }
+            else if (method === "item/completed" &&
+                itemType === "agentMessage") {
+                if (runtime.phase !== "started") {
+                    fail("CODEX_WRITE_PROBE_THREAD_SETUP_FAILED");
+                }
+                else {
+                    runtime.phase = "item_completed";
+                }
+            }
+            return true;
+        }
+        return false;
+    }
     handleCompletedItem(params) {
         if (!isRecord(params) ||
             typeof params.threadId !== "string") {
@@ -1597,6 +2129,7 @@ export class CodexAppServerConnector {
             return;
         this.faulting = true;
         this.connection = "faulted";
+        this.settleProbeConnectionLoss();
         this.initialized = false;
         this.routeStatus = "stale";
         this.selectedThreadObserved = false;
@@ -1617,6 +2150,7 @@ export class CodexAppServerConnector {
         if (this.connection === "closed" || this.connection === "faulted")
             return;
         this.connection = "closed";
+        this.settleProbeConnectionLoss();
         this.initialized = false;
         this.routeStatus = "stale";
         this.selectedThreadObserved = false;