@navels/neal 0.1.0

package/dist/neal/providers/openai-codex.js

@@ -0,0 +1,1014 @@
+import { Codex } from '@openai/codex-sdk';
+import { runStructuredJsonProtocol } from '../agents/structured-json.js';
+import { NealProviderError } from './types.js';
+const OPENAI_CODEX_PROVIDER_ID = 'openai-codex';
+class CodexInactivityTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`Codex timed out after ${Math.round(timeoutMs / 1000)}s without progress`);
+        this.name = 'CodexInactivityTimeoutError';
+    }
+}
+// In-round transient (`api_error`) retries back off exponentially: 500 ms
+// base, doubling per retry, capped at 5 s — the same schedule as the
+// generic-agentic adapter. `sleep` is injectable through the adapter options
+// so tests observe the delays without wall-clock waiting.
+const API_RETRY_BASE_DELAY_MS = 500;
+const API_RETRY_MAX_DELAY_MS = 5_000;
+function defaultSleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+function getApiRetryDelayMs(retryCount) {
+    return Math.min(API_RETRY_BASE_DELAY_MS * 2 ** (retryCount - 1), API_RETRY_MAX_DELAY_MS);
+}
+async function nextWithTimeout(promise, timeoutMs, onTimeout) {
+    return await new Promise((resolvePromise, rejectPromise) => {
+        const timer = setTimeout(() => {
+            onTimeout?.();
+            rejectPromise(new CodexInactivityTimeoutError(timeoutMs));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolvePromise(value);
+        }, (error) => {
+            clearTimeout(timer);
+            rejectPromise(error);
+        });
+    });
+}
+// Propagates an external caller-owned abort signal into the adapter's
+// internal per-turn AbortController so orchestration-level supervision can
+// cancel an in-flight Codex turn. Repair threads use their own controllers
+// and are intentionally not linked; repairs are short, prompt-only turns.
+function linkExternalAbortSignal(signal, abortController) {
+    if (!signal) {
+        return;
+    }
+    if (signal.aborted) {
+        abortController.abort(signal.reason);
+        return;
+    }
+    signal.addEventListener('abort', () => abortController.abort(signal.reason), { once: true });
+}
+function isTransientCodexApiFailure(message) {
+    const text = message.toLowerCase();
+    return (text.includes('api_error') ||
+        text.includes('api error') ||
+        text.includes('internal server error') ||
+        text.includes('overloaded') ||
+        text.includes('at capacity') ||
+        text.includes('rate limit') ||
+        text.includes('temporar') ||
+        text.includes('try again'));
+}
+function inferCodexErrorKind(error, message, fallback) {
+    const text = message.toLowerCase();
+    if (error instanceof CodexInactivityTimeoutError || /\btimed out after\b/i.test(message)) {
+        return 'timeout';
+    }
+    if (text.includes('permission') || text.includes('denied') || text.includes('forbidden') || text.includes('not authorized')) {
+        return 'permission_denied';
+    }
+    if (text.includes('property_name_above_max_length') ||
+        text.includes('orphan function call output') ||
+        text.includes('failed to record rollout items') ||
+        text.includes('session unavailable') ||
+        text.includes('session not found') ||
+        text.includes('thread not found')) {
+        return 'session_unavailable';
+    }
+    if (isTransientCodexApiFailure(message)) {
+        return 'api_error';
+    }
+    return fallback;
+}
+function isRetryableCodexError(kind, message) {
+    return kind === 'timeout' || kind === 'session_unavailable' || (kind === 'api_error' && isTransientCodexApiFailure(message));
+}
+function isCodexReconnectProgressMessage(message) {
+    return /^reconnecting\.\.\.\s*\d+\/\d+\b/i.test(message.trim());
+}
+function createCodexProviderError(args) {
+    const kind = args.kind ?? inferCodexErrorKind(args.cause, args.message, 'provider_failed');
+    return new NealProviderError({
+        message: args.message,
+        provider: OPENAI_CODEX_PROVIDER_ID,
+        role: args.role,
+        sessionHandle: args.sessionHandle,
+        kind,
+        retryable: args.retryable ?? isRetryableCodexError(kind, args.message),
+        cause: args.cause,
+    });
+}
+function observeCodexFailure(args) {
+    return {
+        message: args.message,
+        kind: args.kind ?? inferCodexErrorKind(args.cause, args.message, 'provider_failed'),
+        source: args.source,
+        cause: args.cause,
+    };
+}
+function isGenericCodexProcessFailure(message) {
+    const text = message.toLowerCase();
+    return text.includes('codex exec exited') || text.includes('reading prompt from stdin') || text.includes('exited with code');
+}
+function shouldReplaceCodexFailure(current, next) {
+    if (!current) {
+        return true;
+    }
+    return isGenericCodexProcessFailure(current.message) || !isGenericCodexProcessFailure(next.message);
+}
+function createCodexProviderErrorFromObservedFailure(failure, args) {
+    const cause = args.cause === undefined
+        ? failure.cause
+        : {
+            source: failure.source,
+            providerCause: failure.cause,
+            iteratorCause: args.cause,
+        };
+    return createCodexProviderError({
+        message: failure.message,
+        role: args.role,
+        sessionHandle: args.sessionHandle,
+        kind: failure.kind,
+        cause,
+    });
+}
+function normalizeCodexProviderError(error, args) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (error instanceof NealProviderError) {
+        if (error.sessionHandle || !args.sessionHandle) {
+            return error;
+        }
+        return createCodexProviderError({
+            message: error.message,
+            role: error.role,
+            sessionHandle: args.sessionHandle,
+            kind: error.kind,
+            retryable: error.retryable,
+            cause: error,
+        });
+    }
+    return createCodexProviderError({
+        message,
+        role: args.role,
+        sessionHandle: args.sessionHandle,
+        kind: args.kind,
+        cause: error,
+    });
+}
+function summarizeItem(item) {
+    switch (item.type) {
+        case 'command_execution':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                status: item.status,
+                command: item.command,
+                outputLength: item.aggregated_output.length,
+                exitCode: item.exit_code,
+            };
+        case 'file_change':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                status: item.status,
+                files: item.changes.map((change) => change.path),
+            };
+        case 'mcp_tool_call':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                status: item.status,
+                server: item.server,
+                tool: item.tool,
+            };
+        case 'web_search':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                query: item.query,
+            };
+        case 'todo_list':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                completed: item.items.filter((todo) => todo.completed).length,
+                total: item.items.length,
+            };
+        case 'reasoning':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                textLength: item.text.length,
+            };
+        case 'agent_message':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                textLength: item.text.length,
+            };
+        case 'error':
+            return {
+                itemId: item.id,
+                itemType: item.type,
+                message: item.message,
+            };
+    }
+}
+function buildCodexThreadOptions(args) {
+    return {
+        ...(args.model ? { model: args.model } : {}),
+        ...(args.effort ? { modelReasoningEffort: args.effort } : {}),
+        approvalPolicy: 'never',
+        sandboxMode: args.sandboxMode ?? 'danger-full-access',
+        workingDirectory: args.cwd,
+        skipGitRepoCheck: args.skipGitRepoCheck ?? false,
+    };
+}
+function createCodexThread(args) {
+    const codex = new Codex();
+    const threadOptions = buildCodexThreadOptions({
+        cwd: args.cwd,
+        model: args.model,
+        effort: args.effort,
+        skipGitRepoCheck: args.skipGitRepoCheck,
+        sandboxMode: args.sandboxMode,
+    });
+    return args.sessionHandle
+        ? codex.resumeThread(args.sessionHandle, threadOptions)
+        : codex.startThread(threadOptions);
+}
+async function emitProviderEvent(events, event) {
+    await events?.(event);
+}
+async function emitCodexStreamError(args) {
+    if (isCodexReconnectProgressMessage(args.message)) {
+        await emitProviderEvent(args.events, {
+            type: 'tool_progress',
+            provider: OPENAI_CODEX_PROVIDER_ID,
+            role: args.role,
+            label: args.label,
+            sessionHandle: args.sessionHandle,
+            toolName: 'codex_stream',
+            message: args.message,
+            isError: true,
+            providerData: { sdkEventType: 'error', nonFatal: true },
+        });
+        return false;
+    }
+    await emitProviderEvent(args.events, {
+        type: 'provider_error',
+        provider: OPENAI_CODEX_PROVIDER_ID,
+        role: args.role,
+        label: args.label,
+        sessionHandle: args.sessionHandle,
+        message: args.message,
+        providerData: { sdkEventType: 'error' },
+    });
+    return true;
+}
+async function consumeCodexTurn(turn, cwd, inactivityTimeoutMs, events, onSessionStarted, abortController) {
+    let finalResponse = '';
+    let observedFailure = null;
+    let sessionHandle = null;
+    const iterator = turn.events[Symbol.asyncIterator]();
+    while (true) {
+        let next;
+        try {
+            next = await nextWithTimeout(iterator.next(), inactivityTimeoutMs, () => abortController?.abort());
+        }
+        catch (error) {
+            if (observedFailure) {
+                throw createCodexProviderErrorFromObservedFailure(observedFailure, {
+                    role: 'coder',
+                    sessionHandle,
+                    cause: error,
+                });
+            }
+            throw normalizeCodexProviderError(error, {
+                role: 'coder',
+                sessionHandle,
+            });
+        }
+        if (next.done) {
+            break;
+        }
+        const event = next.value;
+        switch (event.type) {
+            case 'thread.started':
+                sessionHandle = event.thread_id;
+                await emitProviderEvent(events, {
+                    type: 'session_started',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    sessionHandle: event.thread_id,
+                    providerData: { sdkEventType: event.type },
+                });
+                await onSessionStarted?.(event.thread_id);
+                break;
+            case 'turn.started':
+                await emitProviderEvent(events, {
+                    type: 'turn_started',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    sessionHandle,
+                    providerData: { sdkEventType: event.type },
+                });
+                break;
+            case 'item.started':
+                await emitProviderEvent(events, {
+                    type: 'tool_started',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    sessionHandle,
+                    itemId: summarizeItem(event.item).itemId,
+                    toolName: event.item.type,
+                    providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                });
+                break;
+            case 'item.updated':
+                await emitProviderEvent(events, {
+                    type: 'tool_progress',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    sessionHandle,
+                    itemId: summarizeItem(event.item).itemId,
+                    toolName: event.item.type,
+                    providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                });
+                break;
+            case 'item.completed':
+                if (event.item.type === 'command_execution') {
+                    await emitProviderEvent(events, {
+                        type: 'command_completed',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'coder',
+                        sessionHandle,
+                        itemId: event.item.id,
+                        command: event.item.command,
+                        status: event.item.status,
+                        exitCode: event.item.exit_code ?? null,
+                        output: event.item.aggregated_output,
+                        outputLength: event.item.aggregated_output.length,
+                        cwd,
+                        providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                    });
+                }
+                else if (event.item.type === 'file_change' && event.item.changes.length > 0) {
+                    const files = event.item.changes.map((change) => change.path);
+                    await emitProviderEvent(events, {
+                        type: 'file_changed',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'coder',
+                        sessionHandle,
+                        files,
+                        providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                    });
+                }
+                else if (event.item.type === 'agent_message') {
+                    finalResponse = event.item.text;
+                }
+                break;
+            case 'turn.completed':
+                await emitProviderEvent(events, {
+                    type: 'turn_completed',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    sessionHandle,
+                    usage: event.usage,
+                    providerData: { sdkEventType: event.type },
+                });
+                if (event.usage !== undefined) {
+                    await emitProviderEvent(events, {
+                        type: 'usage_reported',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'coder',
+                        sessionHandle,
+                        usage: event.usage,
+                        providerData: { sdkEventType: event.type },
+                    });
+                }
+                break;
+            case 'turn.failed':
+                {
+                    const nextFailure = observeCodexFailure({
+                        message: event.error.message,
+                        source: event.type,
+                        cause: event.error,
+                    });
+                    if (shouldReplaceCodexFailure(observedFailure, nextFailure)) {
+                        observedFailure = nextFailure;
+                        await emitProviderEvent(events, {
+                            type: 'provider_error',
+                            provider: OPENAI_CODEX_PROVIDER_ID,
+                            role: 'coder',
+                            sessionHandle,
+                            message: event.error.message,
+                            providerData: { sdkEventType: event.type },
+                        });
+                    }
+                }
+                break;
+            case 'error':
+                {
+                    const nextFailure = observeCodexFailure({
+                        message: event.message,
+                        source: event.type,
+                        cause: event,
+                    });
+                    if (shouldReplaceCodexFailure(observedFailure, nextFailure)) {
+                        if (await emitCodexStreamError({
+                            events,
+                            role: 'coder',
+                            sessionHandle,
+                            message: event.message,
+                        })) {
+                            observedFailure = nextFailure;
+                        }
+                    }
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    if (observedFailure) {
+        throw createCodexProviderErrorFromObservedFailure(observedFailure, {
+            role: 'coder',
+            sessionHandle,
+        });
+    }
+    return { finalResponse, sessionHandle };
+}
+async function consumeCodexAdvisorTurn(turn, cwd, label, inactivityTimeoutMs, events, abortController) {
+    let finalResponse = '';
+    let observedFailure = null;
+    let sessionHandle = null;
+    const iterator = turn.events[Symbol.asyncIterator]();
+    while (true) {
+        let next;
+        try {
+            next = await nextWithTimeout(iterator.next(), inactivityTimeoutMs, () => abortController?.abort());
+        }
+        catch (error) {
+            if (observedFailure) {
+                throw createCodexProviderErrorFromObservedFailure(observedFailure, {
+                    role: 'structured-advisor',
+                    sessionHandle,
+                    cause: error,
+                });
+            }
+            throw normalizeCodexProviderError(error, {
+                role: 'structured-advisor',
+                sessionHandle,
+            });
+        }
+        if (next.done) {
+            break;
+        }
+        const event = next.value;
+        switch (event.type) {
+            case 'thread.started':
+                sessionHandle = event.thread_id;
+                await emitProviderEvent(events, {
+                    type: 'session_started',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label,
+                    sessionHandle: event.thread_id,
+                    providerData: { sdkEventType: event.type },
+                });
+                break;
+            case 'turn.started':
+                await emitProviderEvent(events, {
+                    type: 'turn_started',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label,
+                    sessionHandle,
+                    providerData: { sdkEventType: event.type },
+                });
+                break;
+            case 'item.started':
+                await emitProviderEvent(events, {
+                    type: 'tool_started',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label,
+                    sessionHandle,
+                    itemId: summarizeItem(event.item).itemId,
+                    toolName: event.item.type,
+                    providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                });
+                break;
+            case 'item.updated':
+                await emitProviderEvent(events, {
+                    type: 'tool_progress',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label,
+                    sessionHandle,
+                    itemId: summarizeItem(event.item).itemId,
+                    toolName: event.item.type,
+                    providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                });
+                break;
+            case 'item.completed':
+                if (event.item.type === 'command_execution') {
+                    await emitProviderEvent(events, {
+                        type: 'command_completed',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'structured-advisor',
+                        label,
+                        sessionHandle,
+                        itemId: event.item.id,
+                        command: event.item.command,
+                        status: event.item.status,
+                        exitCode: event.item.exit_code ?? null,
+                        output: event.item.aggregated_output,
+                        outputLength: event.item.aggregated_output.length,
+                        cwd,
+                        providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                    });
+                }
+                else if (event.item.type === 'file_change' && event.item.changes.length > 0) {
+                    const files = event.item.changes.map((change) => change.path);
+                    await emitProviderEvent(events, {
+                        type: 'file_changed',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'structured-advisor',
+                        label,
+                        sessionHandle,
+                        files,
+                        providerData: { sdkEventType: event.type, item: summarizeItem(event.item) },
+                    });
+                }
+                else if (event.item.type === 'agent_message') {
+                    finalResponse = event.item.text;
+                }
+                break;
+            case 'turn.completed':
+                await emitProviderEvent(events, {
+                    type: 'turn_completed',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label,
+                    sessionHandle,
+                    usage: event.usage,
+                    providerData: { sdkEventType: event.type },
+                });
+                if (event.usage !== undefined) {
+                    await emitProviderEvent(events, {
+                        type: 'usage_reported',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'structured-advisor',
+                        label,
+                        sessionHandle,
+                        usage: event.usage,
+                        providerData: { sdkEventType: event.type },
+                    });
+                }
+                break;
+            case 'turn.failed':
+                {
+                    const nextFailure = observeCodexFailure({
+                        message: event.error.message,
+                        source: event.type,
+                        cause: event.error,
+                    });
+                    if (shouldReplaceCodexFailure(observedFailure, nextFailure)) {
+                        observedFailure = nextFailure;
+                        await emitProviderEvent(events, {
+                            type: 'provider_error',
+                            provider: OPENAI_CODEX_PROVIDER_ID,
+                            role: 'structured-advisor',
+                            label,
+                            sessionHandle,
+                            message: event.error.message,
+                            providerData: { sdkEventType: event.type },
+                        });
+                    }
+                }
+                break;
+            case 'error':
+                {
+                    const nextFailure = observeCodexFailure({
+                        message: event.message,
+                        source: event.type,
+                        cause: event,
+                    });
+                    if (shouldReplaceCodexFailure(observedFailure, nextFailure)) {
+                        if (await emitCodexStreamError({
+                            events,
+                            role: 'structured-advisor',
+                            label,
+                            sessionHandle,
+                            message: event.message,
+                        })) {
+                            observedFailure = nextFailure;
+                        }
+                    }
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    if (observedFailure) {
+        throw createCodexProviderErrorFromObservedFailure(observedFailure, {
+            role: 'structured-advisor',
+            sessionHandle,
+        });
+    }
+    return { finalResponse, sessionHandle };
+}
+function parseCodexStructuredOutput(finalResponse, label, sessionHandle) {
+    try {
+        return JSON.parse(finalResponse);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw createCodexProviderError({
+            message: `Codex ${label} returned invalid structured output: ${message}`,
+            role: 'structured-advisor',
+            sessionHandle,
+            kind: 'structured_output_invalid',
+            cause: error,
+        });
+    }
+}
+function buildCodexStructuredAdvisorRunOptions(args, signal) {
+    if (args.structuredJsonProtocol?.protocol === 'neal-json-block-v1') {
+        return { signal };
+    }
+    return {
+        outputSchema: args.schema,
+        signal,
+    };
+}
+// Best-effort `toolPolicy` enforcement for Codex coder turns. The Codex SDK
+// has no per-tool-call hook, so `allowedWritePaths` cannot be enforced at
+// path granularity; sandbox modes are the strongest mechanical lever it
+// offers. A jailed plan-authoring turn (allowRun false + allowedWritePaths)
+// runs under 'workspace-write' so writes are confined to the workspace
+// sandbox. Residual gap: shell still runs inside that sandbox and can write
+// any workspace path, not just the allowlisted plan document — documented in
+// docs/providers.md. Policy-free coder rounds keep 'danger-full-access'
+// because scope verification legitimately runs arbitrary commands.
+function getCodexCoderSandboxMode(toolPolicy) {
+    return toolPolicy?.allowRun === false && toolPolicy.allowedWritePaths
+        ? 'workspace-write'
+        : 'danger-full-access';
+}
+class OpenAICodexCoderAdapter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async runPrompt(args) {
+        let thread = null;
+        try {
+            const createThread = this.options.createThread ?? createCodexThread;
+            thread = createThread({
+                cwd: args.cwd,
+                sessionHandle: args.resumeHandle,
+                model: this.options.model ?? undefined,
+                effort: this.options.effort ?? undefined,
+                skipGitRepoCheck: args.skipGitRepoCheck,
+                sandboxMode: getCodexCoderSandboxMode(args.toolPolicy),
+            });
+            const abortController = new AbortController();
+            linkExternalAbortSignal(args.signal, abortController);
+            const streamedTurn = await thread.runStreamed(args.prompt, {
+                ...(args.outputSchema ? { outputSchema: args.outputSchema } : {}),
+                signal: abortController.signal,
+            });
+            const result = await consumeCodexTurn(streamedTurn, args.cwd, args.inactivityTimeoutMs, args.events, args.onSessionStarted, abortController);
+            if (args.outputSchema) {
+                await emitProviderEvent(args.events, {
+                    type: 'structured_output_received',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    sessionHandle: thread.id,
+                });
+            }
+            return {
+                sessionHandle: thread.id,
+                finalResponse: result.finalResponse,
+            };
+        }
+        catch (error) {
+            const providerError = normalizeCodexProviderError(error, {
+                role: 'coder',
+                sessionHandle: thread?.id ?? args.resumeHandle ?? null,
+            });
+            await emitProviderEvent(args.events, {
+                type: 'provider_error',
+                provider: OPENAI_CODEX_PROVIDER_ID,
+                role: 'coder',
+                sessionHandle: providerError.sessionHandle,
+                message: providerError.message,
+                errorKind: providerError.kind,
+            });
+            throw providerError;
+        }
+    }
+    async runStructuredPrompt(args) {
+        const sleep = this.options.sleep ?? defaultSleep;
+        let apiRetryCount = 0;
+        const apiRetryLimit = args.apiRetryLimit ?? 0;
+        while (true) {
+            let thread = null;
+            try {
+                const createThread = this.options.createThread ?? createCodexThread;
+                thread = createThread({
+                    cwd: args.cwd,
+                    sessionHandle: args.resumeHandle,
+                    model: this.options.model ?? undefined,
+                    effort: this.options.effort ?? undefined,
+                    skipGitRepoCheck: args.skipGitRepoCheck,
+                    sandboxMode: getCodexCoderSandboxMode(args.toolPolicy),
+                });
+                const abortController = new AbortController();
+                linkExternalAbortSignal(args.signal, abortController);
+                return await runStructuredJsonProtocol({
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    label: args.label,
+                    protocol: args.structuredJsonProtocol,
+                    prompt: args.prompt,
+                    events: args.events,
+                    initialSessionHandle: args.resumeHandle ?? null,
+                    runInitial: async (prompt) => {
+                        const streamedTurn = await thread.runStreamed(prompt, {
+                            signal: abortController.signal,
+                        });
+                        const result = await consumeCodexTurn(streamedTurn, args.cwd, args.inactivityTimeoutMs, args.events, args.onSessionStarted, abortController);
+                        return {
+                            assistantText: result.finalResponse,
+                            sessionHandle: thread.id,
+                        };
+                    },
+                    runRepair: async (prompt) => {
+                        // Repair runs on a fresh prompt-only thread whose prompt forbids
+                        // tool use entirely, so nothing in the repair flow needs write
+                        // access; the read-only sandbox enforces that mechanically
+                        // (mirroring the structured-advisor repair thread).
+                        const repairThread = createThread({
+                            cwd: args.cwd,
+                            model: this.options.model ?? undefined,
+                            effort: this.options.effort ?? undefined,
+                            skipGitRepoCheck: true,
+                            sandboxMode: 'read-only',
+                        });
+                        const repairAbortController = new AbortController();
+                        const streamedTurn = await repairThread.runStreamed(prompt, {
+                            signal: repairAbortController.signal,
+                        });
+                        const result = await consumeCodexTurn(streamedTurn, args.cwd, args.inactivityTimeoutMs, args.events, undefined, repairAbortController);
+                        return {
+                            assistantText: result.finalResponse,
+                            sessionHandle: repairThread.id,
+                        };
+                    },
+                    createProviderError: (errorArgs) => createCodexProviderError({
+                        message: errorArgs.message,
+                        role: 'coder',
+                        sessionHandle: errorArgs.sessionHandle,
+                        kind: errorArgs.kind,
+                        retryable: false,
+                        cause: errorArgs.cause,
+                    }),
+                });
+            }
+            catch (error) {
+                const providerError = normalizeCodexProviderError(error, {
+                    role: 'coder',
+                    sessionHandle: thread?.id ?? args.resumeHandle ?? null,
+                });
+                // Bounded in-round retry for transient provider failures, mirroring
+                // the Claude structured-coder loop: only retryable `api_error` kinds
+                // burn budget and a caller abort never does. Each retry starts a
+                // fresh thread; per the adapter contract resumed sessions pass 0.
+                if (providerError.kind === 'api_error' &&
+                    providerError.retryable &&
+                    apiRetryCount < apiRetryLimit &&
+                    !args.signal?.aborted) {
+                    apiRetryCount += 1;
+                    await emitProviderEvent(args.events, {
+                        type: 'tool_progress',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'coder',
+                        label: args.label,
+                        sessionHandle: providerError.sessionHandle,
+                        toolName: 'api_retry',
+                        message: `transient Codex failure; retrying ${args.label} (${apiRetryCount}/${apiRetryLimit})`,
+                        isError: true,
+                        providerData: {
+                            retryCount: apiRetryCount,
+                            retryLimit: apiRetryLimit,
+                            message: providerError.message,
+                        },
+                    });
+                    await sleep(getApiRetryDelayMs(apiRetryCount));
+                    continue;
+                }
+                await emitProviderEvent(args.events, {
+                    type: 'provider_error',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'coder',
+                    label: args.label,
+                    sessionHandle: providerError.sessionHandle,
+                    message: providerError.message,
+                    errorKind: providerError.kind,
+                });
+                throw providerError;
+            }
+        }
+    }
+}
+class OpenAICodexStructuredAdvisorAdapter {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async runStructuredRound(args) {
+        const createThread = this.options.createThread ?? createCodexThread;
+        const sleep = this.options.sleep ?? defaultSleep;
+        let apiRetryCount = 0;
+        const apiRetryLimit = args.apiRetryLimit;
+        while (true) {
+            let thread = null;
+            try {
+                thread = createThread({
+                    cwd: args.cwd,
+                    sessionHandle: args.resumeHandle,
+                    model: this.options.model ?? undefined,
+                    effort: this.options.effort ?? undefined,
+                    skipGitRepoCheck: args.skipGitRepoCheck,
+                    sandboxMode: 'read-only',
+                });
+                const abortController = new AbortController();
+                linkExternalAbortSignal(args.signal, abortController);
+                if (args.structuredJsonProtocol?.protocol === 'neal-json-block-v1') {
+                    return await runStructuredJsonProtocol({
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'structured-advisor',
+                        label: args.label,
+                        protocol: args.structuredJsonProtocol,
+                        prompt: args.prompt,
+                        events: args.events,
+                        initialSessionHandle: args.resumeHandle ?? null,
+                        runInitial: async (prompt) => {
+                            const streamedTurn = await thread.runStreamed(prompt, {
+                                signal: abortController.signal,
+                            });
+                            const result = await consumeCodexAdvisorTurn(streamedTurn, args.cwd, args.label, args.inactivityTimeoutMs, args.events, abortController);
+                            return {
+                                assistantText: result.finalResponse,
+                                sessionHandle: thread.id ?? result.sessionHandle ?? null,
+                            };
+                        },
+                        runRepair: async (prompt) => {
+                            const repairThread = createThread({
+                                cwd: args.cwd,
+                                model: this.options.model ?? undefined,
+                                effort: this.options.effort ?? undefined,
+                                skipGitRepoCheck: true,
+                                sandboxMode: 'read-only',
+                            });
+                            const repairAbortController = new AbortController();
+                            const streamedTurn = await repairThread.runStreamed(prompt, {
+                                signal: repairAbortController.signal,
+                            });
+                            const result = await consumeCodexAdvisorTurn(streamedTurn, args.cwd, args.label, args.inactivityTimeoutMs, args.events, repairAbortController);
+                            return {
+                                assistantText: result.finalResponse,
+                                sessionHandle: repairThread.id ?? result.sessionHandle ?? null,
+                            };
+                        },
+                        createProviderError: (errorArgs) => createCodexProviderError({
+                            message: errorArgs.message,
+                            role: 'structured-advisor',
+                            sessionHandle: errorArgs.sessionHandle,
+                            kind: errorArgs.kind,
+                            retryable: false,
+                            cause: errorArgs.cause,
+                        }),
+                    });
+                }
+                const streamedTurn = await thread.runStreamed(args.prompt, buildCodexStructuredAdvisorRunOptions(args, abortController.signal));
+                const result = await consumeCodexAdvisorTurn(streamedTurn, args.cwd, args.label, args.inactivityTimeoutMs, args.events, abortController);
+                const structured = parseCodexStructuredOutput(result.finalResponse, args.label, thread.id);
+                await emitProviderEvent(args.events, {
+                    type: 'structured_output_received',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label: args.label,
+                    sessionHandle: thread.id,
+                });
+                return {
+                    sessionHandle: thread.id,
+                    structured,
+                };
+            }
+            catch (error) {
+                const providerError = normalizeCodexProviderError(error, {
+                    role: 'structured-advisor',
+                    sessionHandle: thread?.id ?? args.resumeHandle ?? null,
+                });
+                // Bounded in-round retry for transient provider failures, mirroring
+                // the Claude advisor rounds: only retryable `api_error` kinds burn
+                // budget and a caller abort never does. Each retry starts a fresh
+                // thread; per the adapter contract resumed sessions pass 0.
+                if (providerError.kind === 'api_error' &&
+                    providerError.retryable &&
+                    apiRetryCount < apiRetryLimit &&
+                    !args.signal?.aborted) {
+                    apiRetryCount += 1;
+                    await emitProviderEvent(args.events, {
+                        type: 'tool_progress',
+                        provider: OPENAI_CODEX_PROVIDER_ID,
+                        role: 'structured-advisor',
+                        label: args.label,
+                        sessionHandle: providerError.sessionHandle,
+                        toolName: 'api_retry',
+                        message: `transient Codex failure; retrying ${args.label} (${apiRetryCount}/${apiRetryLimit})`,
+                        isError: true,
+                        providerData: {
+                            retryCount: apiRetryCount,
+                            retryLimit: apiRetryLimit,
+                            message: providerError.message,
+                        },
+                    });
+                    await sleep(getApiRetryDelayMs(apiRetryCount));
+                    continue;
+                }
+                await emitProviderEvent(args.events, {
+                    type: 'provider_error',
+                    provider: OPENAI_CODEX_PROVIDER_ID,
+                    role: 'structured-advisor',
+                    label: args.label,
+                    sessionHandle: providerError.sessionHandle,
+                    message: providerError.message,
+                    errorKind: providerError.kind,
+                });
+                throw providerError;
+            }
+        }
+    }
+}
+export function createOpenAICodexCoderAdapter(options = {}) {
+    return new OpenAICodexCoderAdapter(options);
+}
+export function createOpenAICodexStructuredAdvisorAdapter(options = {}) {
+    return new OpenAICodexStructuredAdvisorAdapter(options);
+}
+export const openAICodexProviderDefinition = {
+    id: 'openai-codex',
+    displayName: 'OpenAI Codex',
+    capabilities: {
+        coder: {
+            supported: true,
+            toolAccess: {
+                read: true,
+                write: true,
+                shell: true,
+            },
+            supportsSessionResume: true,
+            supportsModelOverride: true,
+            supportsStructuredOutput: true,
+            usageReporting: 'opportunistic',
+            supportedEfforts: ['minimal', 'low', 'medium', 'high', 'xhigh'],
+        },
+        'structured-advisor': {
+            supported: true,
+            // Reviewers run read-only: no write, no shell. The structured-advisor
+            // thread (primary and repair) runs under the SDK read-only sandbox so a
+            // reviewer can inspect the checkout but never mutate it or run commands.
+            toolAccess: {
+                read: true,
+                write: false,
+                shell: false,
+            },
+            supportsSessionResume: true,
+            supportsModelOverride: true,
+            supportsStructuredOutput: true,
+            usageReporting: 'opportunistic',
+            supportedEfforts: ['minimal', 'low', 'medium', 'high', 'xhigh'],
+        },
+    },
+    createCoderAdapter: createOpenAICodexCoderAdapter,
+    createStructuredAdvisorAdapter: createOpenAICodexStructuredAdvisorAdapter,
+};
+export const openAICodexProviderTestHooks = {
+    buildCodexStructuredAdvisorRunOptions,
+    buildCodexThreadOptions,
+    createCoderAdapterWithThreadFactory: (createThread, options) => new OpenAICodexCoderAdapter({ ...options, createThread }),
+    createStructuredAdvisorAdapterWithThreadFactory: (createThread, options) => new OpenAICodexStructuredAdvisorAdapter({ ...options, createThread }),
+    consumeCodexTurn,
+    consumeCodexAdvisorTurn,
+    parseCodexStructuredOutput,
+};