@astrosheep/keiyaku 0.1.87 → 1.0.1

package/build/agents/providers/codex-app-server.js

@@ -0,0 +1,656 @@
+import { spawn } from "node:child_process";
+import { z } from "zod";
+import { appendDebugLog } from "../../telemetry/debug-log.js";
+import { SUBAGENT_SESSION_VERSION } from "../session.js";
+import { createProjectionDriver } from "../harness/execution-handle.js";
+import { buildSubagentEnv, createAbortError, emitProviderEvidence, sha256Utf8 } from "../harness/runtime.js";
+import { coerceString } from "../../agents/index.js";
+/** Session handle for codex-app-server: thread id plus optional CODEX_HOME for cross-process resume. */
+export const codexAppServerSessionSchema = z.object({
+    threadId: z.string().trim().min(1),
+    codexHome: z.string().trim().min(1).optional(),
+});
+const CODEX_APP_SERVER_PROVIDER = "codex-app-server";
+const MINIMUM_CODEX_APP_SERVER_VERSION = { major: 0, minor: 143, patch: 0 };
+/** Non-interactive defaults for turn/start (faye #316 policy A). */
+export const CODEX_APP_SERVER_TURN_APPROVAL_POLICY = "never";
+export function buildCodexAppServerDefaultSandboxPolicy(cwd) {
+    return {
+        type: "workspaceWrite",
+        writableRoots: [cwd],
+        networkAccess: false,
+        excludeTmpdirEnvVar: false,
+        excludeSlashTmp: false,
+    };
+}
+/** True when config.* already owns approval policy — omit turn-level approvalPolicy default. */
+export function configOwnsApprovalPolicy(config) {
+    if (!config)
+        return false;
+    return Object.prototype.hasOwnProperty.call(config, "approval_policy");
+}
+/**
+ * True when config.* already owns sandbox settings — omit turn-level sandboxPolicy default.
+ * Matches `sandbox_mode` or any `sandbox_workspace_write` / `sandbox_workspace_write.*` key.
+ */
+export function configOwnsSandboxPolicy(config) {
+    if (!config)
+        return false;
+    for (const key of Object.keys(config)) {
+        if (key === "sandbox_mode" || key === "sandbox_workspace_write" || key.startsWith("sandbox_workspace_write.")) {
+            return true;
+        }
+    }
+    return false;
+}
+function parseSemver(version) {
+    const match = version.trim().match(/(\d+)\.(\d+)\.(\d+)/);
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+export function isCodexAppServerVersionBelowMinimum(version) {
+    if (!version)
+        return false;
+    const parsed = parseSemver(version);
+    if (!parsed)
+        return false;
+    if (parsed.major !== MINIMUM_CODEX_APP_SERVER_VERSION.major) {
+        return parsed.major < MINIMUM_CODEX_APP_SERVER_VERSION.major;
+    }
+    if (parsed.minor !== MINIMUM_CODEX_APP_SERVER_VERSION.minor) {
+        return parsed.minor < MINIMUM_CODEX_APP_SERVER_VERSION.minor;
+    }
+    return parsed.patch < MINIMUM_CODEX_APP_SERVER_VERSION.patch;
+}
+function extractVersionFromInitialize(result) {
+    if (!result || typeof result !== "object")
+        return undefined;
+    const record = result;
+    const userAgent = coerceString(record.userAgent);
+    if (userAgent) {
+        const match = userAgent.match(/(\d+\.\d+\.\d+)/);
+        if (match)
+            return match[1];
+    }
+    return coerceString(record.version) ?? coerceString(record.cliVersion);
+}
+class CodexAppServerProcess {
+    onEvidence;
+    onEvidenceDiagnostic;
+    child;
+    pending = new Map();
+    notificationListeners = new Set();
+    serverRequestListeners = new Set();
+    exitPromise;
+    nextId = 1;
+    stdoutBuffer = "";
+    closed = false;
+    exitSettled = false;
+    codexHome;
+    constructor(executable, env, codexHome, onEvidence, onEvidenceDiagnostic) {
+        this.onEvidence = onEvidence;
+        this.onEvidenceDiagnostic = onEvidenceDiagnostic;
+        this.codexHome = codexHome;
+        const spawnEnv = {
+            ...env,
+            ...(codexHome ? { CODEX_HOME: codexHome } : {}),
+        };
+        this.child = spawn(executable, ["app-server", "--listen", "stdio://"], {
+            env: spawnEnv,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (this.onEvidence && this.child.pid)
+            emitProviderEvidence(this.onEvidence, { type: "process", provider: CODEX_APP_SERVER_PROVIDER, event: "spawn", pid: this.child.pid }, this.onEvidenceDiagnostic);
+        this.child.stdout.setEncoding("utf8");
+        this.child.stderr.setEncoding("utf8");
+        this.child.stdout.on("data", (chunk) => this.onStdout(chunk));
+        // Preserve the pre-evidence diagnostic stream exactly. Process evidence
+        // never retains stderr bytes, avoiding credential boundary ambiguity.
+        this.child.stderr.on("data", (chunk) => this.onEvidenceDiagnostic?.(chunk));
+        this.child.on("error", (error) => this.failAll(error));
+        this.exitPromise = new Promise((resolve) => {
+            this.child.once("close", (exitCode) => {
+                this.exitSettled = true;
+                this.closed = true;
+                // With no observer, retain the historical error bytes. Evidence adds
+                // structured exit facts without changing provider behavior.
+                this.failAll(new Error(`${CODEX_APP_SERVER_PROVIDER} process closed`));
+                if (this.onEvidence)
+                    emitProviderEvidence(this.onEvidence, { type: "process", provider: CODEX_APP_SERVER_PROVIDER, event: "exit", exitCode, stderrTail: "" }, this.onEvidenceDiagnostic);
+                resolve();
+            });
+        });
+    }
+    onNotification(listener) {
+        this.notificationListeners.add(listener);
+        return () => this.notificationListeners.delete(listener);
+    }
+    onServerRequest(listener) {
+        this.serverRequestListeners.add(listener);
+        return () => this.serverRequestListeners.delete(listener);
+    }
+    onStdout(chunk) {
+        this.stdoutBuffer += chunk;
+        let newline = this.stdoutBuffer.indexOf("\n");
+        while (newline >= 0) {
+            const line = this.stdoutBuffer.slice(0, newline).trim();
+            this.stdoutBuffer = this.stdoutBuffer.slice(newline + 1);
+            if (line.length > 0) {
+                this.handleLine(line);
+            }
+            newline = this.stdoutBuffer.indexOf("\n");
+        }
+    }
+    handleLine(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!message || typeof message !== "object")
+            return;
+        const record = message;
+        if ("id" in record && ("result" in record || "error" in record)) {
+            const id = record.id;
+            const pending = this.pending.get(id);
+            if (!pending)
+                return;
+            this.pending.delete(id);
+            if ("error" in record && record.error) {
+                const error = record.error;
+                pending.reject(new Error(error.message ?? `${CODEX_APP_SERVER_PROVIDER} RPC error`));
+                return;
+            }
+            pending.resolve(record.result);
+            return;
+        }
+        // Server→client request: method + id. Never ignore, auto-approve, or auto-deny (faye #316).
+        if (typeof record.method === "string" && "id" in record) {
+            const request = {
+                id: record.id,
+                method: record.method,
+                params: record.params ?? undefined,
+            };
+            for (const listener of this.serverRequestListeners) {
+                listener(request);
+            }
+            return;
+        }
+        if (typeof record.method === "string" && !("id" in record)) {
+            const notification = {
+                method: record.method,
+                params: record.params ?? undefined,
+            };
+            for (const listener of this.notificationListeners) {
+                listener(notification);
+            }
+        }
+    }
+    failAll(error) {
+        for (const pending of this.pending.values()) {
+            pending.reject(error);
+        }
+        this.pending.clear();
+    }
+    request(method, params) {
+        if (this.closed) {
+            return Promise.reject(new Error(`${CODEX_APP_SERVER_PROVIDER} process is closed`));
+        }
+        const id = this.nextId++;
+        const payload = params === undefined ? { id, method } : { id, method, params };
+        const serialized = `${JSON.stringify(payload)}\n`;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.child.stdin.write(serialized, (error) => {
+                if (error) {
+                    this.pending.delete(id);
+                    reject(error);
+                }
+            });
+            // The write call above is the process boundary. Emitting afterward
+            // avoids evidence for a synchronous write failure while keeping the
+            // outbound fact before any asynchronous RPC acknowledgement.
+            this.emitOutbound(method, params);
+        });
+    }
+    notify(method, params) {
+        const payload = params === undefined ? { method } : { method, params };
+        this.child.stdin.write(`${JSON.stringify(payload)}\n`);
+    }
+    emitOutbound(method, params) {
+        if (!this.onEvidence)
+            return;
+        const kind = method === "thread/start" ? "thread-start" : method === "thread/resume" ? "thread-resume" : method === "turn/start" ? "turn-start" : method === "turn/steer" ? "steer" : undefined;
+        if (!kind)
+            return;
+        const text = method === "turn/steer"
+            ? coerceString((params?.input?.[0]?.text))
+            : JSON.stringify(params ?? {});
+        if (text === undefined)
+            return;
+        emitProviderEvidence(this.onEvidence, { type: "outbound", provider: CODEX_APP_SERVER_PROVIDER, direction: "request", kind, ...sha256Utf8(text) }, this.onEvidenceDiagnostic);
+        const developerInstructions = coerceString(params?.developerInstructions);
+        if ((method === "thread/start" || method === "thread/resume") && developerInstructions !== undefined) {
+            emitProviderEvidence(this.onEvidence, { type: "outbound", provider: CODEX_APP_SERVER_PROVIDER, direction: "request", kind: "system-prompt", ...sha256Utf8(developerInstructions) }, this.onEvidenceDiagnostic);
+        }
+    }
+    async close() {
+        if (this.exitSettled) {
+            this.closed = true;
+            return;
+        }
+        this.closed = true;
+        this.failAll(new Error(`${CODEX_APP_SERVER_PROVIDER} process closed`));
+        try {
+            this.child.stdin.end();
+        }
+        catch {
+            // ignore
+        }
+        // Destroy stdio so a hung child cannot keep the parent event loop alive via open pipes.
+        try {
+            this.child.stdout.destroy();
+        }
+        catch {
+            // ignore
+        }
+        try {
+            this.child.stderr.destroy();
+        }
+        catch {
+            // ignore
+        }
+        if (!this.exitSettled && this.child.exitCode === null && this.child.signalCode === null) {
+            try {
+                this.child.kill("SIGTERM");
+            }
+            catch {
+                // ignore
+            }
+        }
+        // Escalate to SIGKILL if the child ignores stdin EOF + SIGTERM, then wait for exit
+        // (or give up after a hard bound so close() itself cannot pin the event loop).
+        const forceKill = new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (!this.exitSettled) {
+                    try {
+                        this.child.kill("SIGKILL");
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                resolve();
+            }, 1000);
+            timer.unref?.();
+        });
+        const hardBound = new Promise((resolve) => {
+            const timer = setTimeout(resolve, 2000);
+            timer.unref?.();
+        });
+        await Promise.race([this.exitPromise, Promise.all([forceKill, this.exitPromise]).then(() => undefined), hardBound]);
+    }
+}
+/** Gate-facing production entry: the harness owns clocks, capture, classification, and outcome construction. */
+export async function startCodexAppServer(prompt, cwd, options = {}) {
+    const executable = options.executable?.trim() || "codex";
+    const resumeThreadId = options.threadId?.trim();
+    let server;
+    let activeTurnId;
+    let activeTurnSource;
+    let activeTurnAcceptingSteer = false;
+    let activeThreadId;
+    let interruptRequested = false;
+    let lastAgentMessage = "";
+    let builderDiagnostic;
+    const pendingTells = [];
+    let drainingTells = false;
+    let failActiveTurn;
+    const rejectPendingTells = (error) => {
+        for (const pending of pendingTells.splice(0))
+            pending.reject(error);
+    };
+    const recordActiveTurnId = (candidate, source) => {
+        const turnId = coerceString(candidate);
+        if (!turnId)
+            throw new Error(`${CODEX_APP_SERVER_PROVIDER} ${source} omitted active turn id`);
+        if (!activeTurnId) {
+            activeTurnId = turnId;
+            activeTurnSource = source;
+            return turnId;
+        }
+        if (activeTurnId !== turnId) {
+            throw new Error(`${CODEX_APP_SERVER_PROVIDER} active turn id mismatch: ${activeTurnSource ?? "first"}=${activeTurnId}, ${source}=${turnId}`);
+        }
+        return activeTurnId;
+    };
+    appendDebugLog(`startCodexAppServer: executable=${executable} model=${options.model ?? "default"} mode=${resumeThreadId ? "resume" : "fresh"}`, { cwd, section: CODEX_APP_SERVER_PROVIDER });
+    const submitSteer = async (tell, turnId) => {
+        // turn/steer response {turnId} = enqueue acceptance (submitted), not consumption.
+        // clientUserMessageId = tell.id for later delivered proof via userMessage item clientId.
+        // tell.text is already core-rendered; send byte-for-byte — never parse or rewrite.
+        const ack = await server.request("turn/steer", {
+            threadId: activeThreadId,
+            expectedTurnId: turnId,
+            clientUserMessageId: tell.id,
+            input: [{ type: "text", text: tell.text }],
+        });
+        const acknowledgedTurnId = coerceString(ack.turnId) ?? turnId;
+        if (acknowledgedTurnId !== turnId) {
+            throw new Error(`${CODEX_APP_SERVER_PROVIDER} turn/steer acknowledgement mismatched active turn: expected=${turnId}, actual=${acknowledgedTurnId}`);
+        }
+        if (options.onEvidence) {
+            emitProviderEvidence(options.onEvidence, {
+                type: "ack",
+                provider: CODEX_APP_SERVER_PROVIDER,
+                fence: { kind: "turn", turnId: acknowledgedTurnId },
+                outbound: "steer",
+            }, builderDiagnostic);
+        }
+        return { fence: { kind: "turn", turnId: acknowledgedTurnId } };
+    };
+    const startTellTurn = async (tell) => {
+        const started = await server.request("turn/start", {
+            threadId: activeThreadId,
+            input: [{ type: "text", text: tell.text }],
+            ...(options.model ? { model: options.model } : {}),
+            ...(tell.effort ? { effort: tell.effort } : {}),
+            ...(!configOwnsApprovalPolicy(options.config) ? { approvalPolicy: CODEX_APP_SERVER_TURN_APPROVAL_POLICY } : {}),
+            ...(!configOwnsSandboxPolicy(options.config) ? { sandboxPolicy: buildCodexAppServerDefaultSandboxPolicy(cwd) } : {}),
+        });
+        const startedTurn = started && typeof started === "object"
+            ? (started.turn ?? undefined)
+            : undefined;
+        const newTurnId = recordActiveTurnId(startedTurn?.id, "response");
+        if (options.onEvidence)
+            emitProviderEvidence(options.onEvidence, { type: "ack", provider: CODEX_APP_SERVER_PROVIDER, fence: { kind: "turn", turnId: newTurnId }, outbound: "run" }, builderDiagnostic);
+        return { fence: { kind: "turn", turnId: newTurnId } };
+    };
+    const drainPendingTells = async () => {
+        if (drainingTells)
+            return;
+        drainingTells = true;
+        try {
+            while (pendingTells.length > 0 && server && activeThreadId) {
+                const pending = pendingTells[0];
+                if (pending.tell.effort && activeTurnId)
+                    return;
+                if (!pending.tell.effort && activeTurnId && !activeTurnAcceptingSteer)
+                    return;
+                pendingTells.shift();
+                try {
+                    const ack = activeTurnId
+                        ? await submitSteer(pending.tell, activeTurnId)
+                        : await startTellTurn(pending.tell);
+                    pending.resolve(ack);
+                }
+                catch (error) {
+                    pending.reject(error);
+                    failActiveTurn?.(error);
+                    return;
+                }
+            }
+        }
+        finally {
+            drainingTells = false;
+        }
+    };
+    const enqueue = async (tell) => {
+        if (!server || !activeThreadId) {
+            throw new Error(`${CODEX_APP_SERVER_PROVIDER} cannot steer: no active turn`);
+        }
+        return await new Promise((resolve, reject) => {
+            pendingTells.push({ tell, resolve, reject });
+            void drainPendingTells();
+        });
+    };
+    return createProjectionDriver({
+        steerMode: "mid-execution",
+        enqueue,
+        async abort() {
+            interruptRequested = true;
+            if (server && activeThreadId && activeTurnId) {
+                try {
+                    // RPC acknowledgement is NOT terminal proof; wait for turn/completed interrupted.
+                    await server.request("turn/interrupt", {
+                        threadId: activeThreadId,
+                        turnId: activeTurnId,
+                    });
+                }
+                catch {
+                    // idle interrupt may error; still rely on process teardown
+                }
+            }
+            await server?.close();
+        },
+        async run(builder) {
+            builderDiagnostic = (text) => builder.emit({ type: "diagnostic", text });
+            const env = buildSubagentEnv();
+            server = new CodexAppServerProcess(executable, env, options.codexHome, options.onEvidence, (text) => builder.emit({ type: "diagnostic", text }));
+            const turnCompleted = new Promise((resolve, reject) => {
+                let unsubNotifications = () => { };
+                let unsubServerRequest = () => { };
+                let settled = false;
+                const failTurn = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    rejectPendingTells(error);
+                    const message = error instanceof Error ? error.message : String(error);
+                    builder.emit({ type: "diagnostic", text: message });
+                    builder.emit({ type: "fail", message });
+                    unsubNotifications();
+                    unsubServerRequest();
+                    reject(error);
+                };
+                const failServerRequest = (request) => {
+                    // Policy A forbids interactive server→client requests. Fail immediately with named diagnostic.
+                    const message = `${CODEX_APP_SERVER_PROVIDER} unexpected server request '${request.method}' (id=${String(request.id)}); non-interactive policy forbids server→client requests`;
+                    failTurn(new Error(message));
+                };
+                unsubServerRequest = server.onServerRequest((request) => {
+                    failServerRequest(request);
+                });
+                unsubNotifications = server.onNotification((notification) => {
+                    try {
+                        builder.emit({ type: "output", value: notification });
+                        if (notification.method === "item/agentMessage/delta") {
+                            const delta = coerceString(notification.params?.delta);
+                            if (delta) {
+                                lastAgentMessage = `${lastAgentMessage}${delta}`;
+                                builder.emit({ type: "message", text: lastAgentMessage });
+                            }
+                        }
+                        if (notification.method === "item/completed") {
+                            const item = notification.params?.item;
+                            if (item && (item.type === "agentMessage" || item.type === "agent_message")) {
+                                const text = coerceString(item.text);
+                                if (text) {
+                                    lastAgentMessage = text;
+                                    builder.emit({ type: "message", text });
+                                }
+                            }
+                        }
+                        if (notification.method === "turn/started") {
+                            const turn = notification.params?.turn;
+                            const turnId = recordActiveTurnId(turn?.id, "notification");
+                            activeTurnAcceptingSteer = true;
+                            const checkpoint = { fence: { kind: "turn", turnId } };
+                            if (options.onEvidence) {
+                                emitProviderEvidence(options.onEvidence, {
+                                    type: "checkpoint",
+                                    provider: CODEX_APP_SERVER_PROVIDER,
+                                    ...checkpoint,
+                                    source: "notification",
+                                }, builderDiagnostic);
+                            }
+                            // turn/start may respond before the server has installed its active
+                            // turn. The native notification is the first steer-safe boundary.
+                            options.onSyncCheckpoint?.({ enqueue }, checkpoint);
+                            void drainPendingTells();
+                        }
+                        if (notification.method === "turn/completed") {
+                            const turn = notification.params?.turn ?? {};
+                            const status = coerceString(turn.status) ?? "unknown";
+                            // Either response or notification may mint the turn fence first;
+                            // every later native source must agree with it.
+                            const turnId = recordActiveTurnId(turn.id, "notification");
+                            // This must stay in the native notification call stack: the harness
+                            // checkpoint and its observer evidence describe this exact crossing.
+                            if (status === "completed") {
+                                activeTurnAcceptingSteer = false;
+                                activeTurnId = undefined;
+                                activeTurnSource = undefined;
+                                const checkpoint = { fence: { kind: "turn", turnId } };
+                                if (options.onEvidence) {
+                                    emitProviderEvidence(options.onEvidence, {
+                                        type: "checkpoint",
+                                        provider: CODEX_APP_SERVER_PROVIDER,
+                                        ...checkpoint,
+                                        source: "notification",
+                                    }, builderDiagnostic);
+                                }
+                                options.onSyncCheckpoint?.({ enqueue }, checkpoint);
+                                void drainPendingTells();
+                                if (pendingTells.length > 0 || drainingTells) {
+                                    return;
+                                }
+                            }
+                            if (settled)
+                                return;
+                            settled = true;
+                            unsubNotifications();
+                            unsubServerRequest();
+                            resolve({ status, turn });
+                        }
+                        if (notification.method === "error") {
+                            const message = coerceString(notification.params?.message) ?? `${CODEX_APP_SERVER_PROVIDER} error`;
+                            builder.emit({ type: "diagnostic", text: message });
+                        }
+                    }
+                    catch (error) {
+                        // Notification listeners run outside the driver's await chain;
+                        // convert validation failures into the controlled completion path.
+                        failTurn(error);
+                    }
+                });
+                failActiveTurn = failTurn;
+                builder.signal.addEventListener("abort", () => {
+                    unsubNotifications();
+                    unsubServerRequest();
+                    failTurn(createAbortError(`${CODEX_APP_SERVER_PROVIDER} exec cancelled by client`));
+                }, { once: true });
+            });
+            // Abort can settle this before initialization reaches the await below.
+            // Attach a handler immediately while preserving the original awaited error.
+            turnCompleted.catch(() => undefined);
+            try {
+                const initResult = await server.request("initialize", {
+                    clientInfo: {
+                        name: "keiyaku",
+                        title: "keiyaku",
+                        version: "0.0.0",
+                    },
+                    capabilities: {
+                        experimentalApi: false,
+                        requestAttestation: false,
+                    },
+                });
+                const version = extractVersionFromInitialize(initResult);
+                if (isCodexAppServerVersionBelowMinimum(version)) {
+                    const message = `${CODEX_APP_SERVER_PROVIDER} refused: initialize version '${version}' is below minimum supported version 0.143.0`;
+                    builder.emit({ type: "fail", message });
+                    throw new Error(message);
+                }
+                const initRecord = (initResult && typeof initResult === "object" ? initResult : {});
+                const serverCodexHome = coerceString(initRecord.codexHome) ?? options.codexHome;
+                server.notify("initialized");
+                const threadParams = {
+                    cwd,
+                    ...(options.model ? { model: options.model } : {}),
+                    ...(options.config ? { config: options.config } : {}),
+                    ...(options.developerInstructions ? { developerInstructions: options.developerInstructions } : {}),
+                };
+                const threadResult = resumeThreadId
+                    ? await server.request("thread/resume", {
+                        threadId: resumeThreadId,
+                        ...threadParams,
+                    })
+                    : await server.request("thread/start", threadParams);
+                const thread = threadResult && typeof threadResult === "object"
+                    ? (threadResult.thread ??
+                        threadResult)
+                    : undefined;
+                activeThreadId = coerceString(thread?.id) ?? resumeThreadId;
+                if (!activeThreadId) {
+                    const message = `${CODEX_APP_SERVER_PROVIDER} exec could not determine thread id`;
+                    builder.emit({ type: "fail", message });
+                    throw new Error(message);
+                }
+                if (options.onEvidence)
+                    emitProviderEvidence(options.onEvidence, { type: "session", provider: CODEX_APP_SERVER_PROVIDER, threadId: activeThreadId }, builderDiagnostic);
+                // Policy A defaults, but omit when config.* already owns that surface (thread/start config wins).
+                const turnStartParams = {
+                    threadId: activeThreadId,
+                    input: [{ type: "text", text: prompt }],
+                    ...(options.model ? { model: options.model } : {}),
+                    ...(options.effort ? { effort: options.effort } : {}),
+                };
+                if (!configOwnsApprovalPolicy(options.config)) {
+                    turnStartParams.approvalPolicy = CODEX_APP_SERVER_TURN_APPROVAL_POLICY;
+                }
+                if (!configOwnsSandboxPolicy(options.config)) {
+                    turnStartParams.sandboxPolicy = buildCodexAppServerDefaultSandboxPolicy(cwd);
+                }
+                activeTurnId = undefined;
+                activeTurnSource = undefined;
+                activeTurnAcceptingSteer = false;
+                const turnStart = await server.request("turn/start", turnStartParams);
+                const turn = turnStart && typeof turnStart === "object"
+                    ? (turnStart.turn ?? undefined)
+                    : undefined;
+                recordActiveTurnId(turn?.id, "response");
+                if (options.onEvidence)
+                    emitProviderEvidence(options.onEvidence, { type: "checkpoint", provider: CODEX_APP_SERVER_PROVIDER, fence: { kind: "turn", turnId: activeTurnId }, source: "response" }, builderDiagnostic);
+                const completed = await turnCompleted;
+                if (completed.status === "interrupted" || interruptRequested) {
+                    throw createAbortError(`${CODEX_APP_SERVER_PROVIDER} turn interrupted`);
+                }
+                if (completed.status === "failed") {
+                    const message = `${CODEX_APP_SERVER_PROVIDER} turn failed`;
+                    builder.emit({ type: "fail", message });
+                    throw new Error(message);
+                }
+                if (completed.status !== "completed") {
+                    const message = `${CODEX_APP_SERVER_PROVIDER} turn ended with status '${completed.status}'`;
+                    builder.emit({ type: "fail", message });
+                    throw new Error(message);
+                }
+                // Successful turn/completed is consumption evidence; interrupt ack alone is not terminal proof.
+                const session = {
+                    provider: "codex-app-server",
+                    version: SUBAGENT_SESSION_VERSION,
+                    handle: {
+                        threadId: activeThreadId,
+                        ...(serverCodexHome ? { codexHome: serverCodexHome } : {}),
+                    },
+                };
+                const finalMessage = lastAgentMessage;
+                builder.emit({ type: "done", finalMessage, session });
+                return { finalMessage, session };
+            }
+            finally {
+                rejectPendingTells(new Error(`${CODEX_APP_SERVER_PROVIDER} execution ended before queued tell acceptance`));
+                await server?.close();
+                server = undefined;
+            }
+        },
+    });
+}