@mindexec/cli 0.2.476 → 0.2.478

package/codex-runtime.js

@@ -1,1608 +1,1608 @@
-import { promises as fs, readFileSync } from 'fs';
-import path from 'path';
-import os from 'os';
-import { exec, spawn } from 'child_process';
-import { promisify } from 'util';
-import crypto from 'crypto';
-
-const execAsync = promisify(exec);
-
-const PROVIDER_KIND = Object.freeze({
-    typeScriptSdk: 'TypeScriptSdk',
-    appServerJsonRpc: 'AppServerJsonRpc',
-    legacyExec: 'LegacyExec',
-    unavailable: 'Unavailable'
-});
-
-const SDK_SANDBOX_BY_API_VALUE = Object.freeze({
-    read_only: 'read-only',
-    'read-only': 'read-only',
-    readonly: 'read-only',
-    workspace_write: 'workspace-write',
-    'workspace-write': 'workspace-write',
-    workspacewrite: 'workspace-write',
-    full_access: 'danger-full-access',
-    fullaccess: 'danger-full-access',
-    danger_full_access: 'danger-full-access',
-    'danger-full-access': 'danger-full-access'
-});
-
-const API_SANDBOX_BY_SDK_VALUE = Object.freeze({
-    'read-only': 'read_only',
-    'workspace-write': 'workspace_write',
-    'danger-full-access': 'full_access'
-});
-
-const DEFAULT_TIMEOUT_MS = 8 * 60 * 1000;
-const CODEX_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
-const MAX_LOG_CHARS = 4000;
-const MAX_EVENT_LOG = 120;
-const MAX_IMAGE_REFERENCE_COUNT = 8;
-const MAX_IMAGE_REFERENCE_BYTES = 40 * 1024 * 1024;
-const MAX_GENERATED_IMAGE_BYTES = 50 * 1024 * 1024;
-const TEMP_DIR = '.ai/codex';
-const CODEX_RUNTIME_HOME_ENV = 'MINDEXEC_CODEX_HOME';
-const CODEX_RUNTIME_CONFIG_MARKER = '# Generated by MindExec LocalBridge for isolated AI node runs.';
-const CODEX_TARGET_BY_PLATFORM = Object.freeze({
-    'win32:x64': {
-        packageName: '@openai/codex-win32-x64',
-        targetTriple: 'x86_64-pc-windows-msvc',
-        binaryName: 'codex.exe'
-    },
-    'win32:arm64': {
-        packageName: '@openai/codex-win32-arm64',
-        targetTriple: 'aarch64-pc-windows-msvc',
-        binaryName: 'codex.exe'
-    },
-    'darwin:x64': {
-        packageName: '@openai/codex-darwin-x64',
-        targetTriple: 'x86_64-apple-darwin',
-        binaryName: 'codex'
-    },
-    'darwin:arm64': {
-        packageName: '@openai/codex-darwin-arm64',
-        targetTriple: 'aarch64-apple-darwin',
-        binaryName: 'codex'
-    },
-    'linux:x64': {
-        packageName: '@openai/codex-linux-x64',
-        targetTriple: 'x86_64-unknown-linux-musl',
-        binaryName: 'codex'
-    },
-    'linux:arm64': {
-        packageName: '@openai/codex-linux-arm64',
-        targetTriple: 'aarch64-unknown-linux-musl',
-        binaryName: 'codex'
-    }
-});
-
-let cachedSdkModule = null;
-let cachedSdkLoadError = null;
-let cachedLegacyAvailability = null;
-let cachedLegacyAvailabilityExpiresAt = 0;
-
-function safeReadPackageVersion(packageRoot, packageName) {
-    try {
-        const packageJsonPath = path.join(packageRoot, 'node_modules', ...packageName.split('/'), 'package.json');
-        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
-        return parsed.version || null;
-    } catch {
-        return null;
-    }
-}
-
-async function loadCodexSdk() {
-    if (cachedSdkModule) {
-        return cachedSdkModule;
-    }
-
-    try {
-        cachedSdkModule = await import('@openai/codex-sdk');
-        cachedSdkLoadError = null;
-        return cachedSdkModule;
-    } catch (err) {
-        cachedSdkLoadError = err?.message || String(err);
-        return null;
-    }
-}
-
-function normalizeProviderKind(value) {
-    const normalized = String(value || '').trim().toLowerCase();
-    if (!normalized || normalized === 'auto' || normalized === 'sdk') {
-        return '';
-    }
-
-    if (normalized === 'typescriptsdk' || normalized === 'typescript-sdk' || normalized === 'type_script_sdk') {
-        return PROVIDER_KIND.typeScriptSdk;
-    }
-
-    if (normalized === 'legacyexec' || normalized === 'legacy-exec' || normalized === 'exec') {
-        return PROVIDER_KIND.legacyExec;
-    }
-
-    if (normalized === 'appserverjsonrpc' || normalized === 'app-server-json-rpc') {
-        return PROVIDER_KIND.appServerJsonRpc;
-    }
-
-    return '';
-}
-
-function resolveUserCodexHome() {
-    const configured = String(process.env.CODEX_HOME || '').trim();
-    return path.resolve(configured || path.join(os.homedir(), '.codex'));
-}
-
-export function resolveCodexRuntimeHome() {
-    const configured = String(process.env[CODEX_RUNTIME_HOME_ENV] || '').trim();
-    return path.resolve(configured || resolveUserCodexHome());
-}
-
-function usesExplicitIsolatedCodexHome() {
-    return String(process.env[CODEX_RUNTIME_HOME_ENV] || '').trim().length > 0;
-}
-
-function buildCodexSdkConfigOverrides(additional = {}) {
-    return {
-        mcp_servers: {},
-        ...additional
-    };
-}
-
-export async function ensureCodexRuntimeHome() {
-    const runtimeHome = resolveCodexRuntimeHome();
-    await fs.mkdir(runtimeHome, { recursive: true });
-    await fs.mkdir(path.join(runtimeHome, 'sessions'), { recursive: true });
-    await fs.mkdir(path.join(runtimeHome, 'generated_images'), { recursive: true });
-
-    if (!usesExplicitIsolatedCodexHome()) {
-        return runtimeHome;
-    }
-
-    const configPath = path.join(runtimeHome, 'config.toml');
-    let shouldWriteConfig = true;
-    try {
-        const existing = await fs.readFile(configPath, 'utf8');
-        shouldWriteConfig = existing.trim().length === 0 || existing.includes(CODEX_RUNTIME_CONFIG_MARKER);
-    } catch {
-        shouldWriteConfig = true;
-    }
-
-    if (shouldWriteConfig) {
-        await fs.writeFile(
-            configPath,
-            `${CODEX_RUNTIME_CONFIG_MARKER}\n# User MCP server definitions are intentionally not inherited here.\n# LocalBridge passes model, sandbox, and reasoning options per run.\n`,
-            'utf8'
-        );
-    }
-
-    return runtimeHome;
-}
-
-export function buildCodexChildEnv() {
-    const env = {};
-    for (const [key, value] of Object.entries(process.env)) {
-        if (value !== undefined) {
-            env[key] = value;
-        }
-    }
-
-    env.CODEX_HOME = resolveCodexRuntimeHome();
-    if (usesExplicitIsolatedCodexHome()) {
-        env.MINDEXEC_CODEX_ISOLATED_HOME = '1';
-    } else {
-        delete env.MINDEXEC_CODEX_ISOLATED_HOME;
-    }
-    return env;
-}
-
-function resolveBundledCodexExecutable(packageRoot) {
-    const target = CODEX_TARGET_BY_PLATFORM[`${process.platform}:${process.arch}`];
-    if (!target) {
-        throw new Error(`Unsupported Codex login platform: ${process.platform} (${process.arch}).`);
-    }
-
-    return path.join(
-        packageRoot,
-        'node_modules',
-        ...target.packageName.split('/'),
-        'vendor',
-        target.targetTriple,
-        'bin',
-        target.binaryName);
-}
-
-function runBundledCodexCommand(packageRoot, args, timeoutMs = CODEX_LOGIN_TIMEOUT_MS) {
-    return new Promise((resolve) => {
-        let executablePath;
-        try {
-            executablePath = resolveBundledCodexExecutable(packageRoot);
-        } catch (err) {
-            resolve({ success: false, exitCode: -1, stdout: '', stderr: '', error: err?.message || String(err) });
-            return;
-        }
-
-        const child = spawn(executablePath, args, {
-            env: buildCodexChildEnv(),
-            windowsHide: true,
-            stdio: ['ignore', 'pipe', 'pipe']
-        });
-        let stdout = '';
-        let stderr = '';
-        let settled = false;
-        let timeout = null;
-
-        const finish = (result) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            if (timeout) {
-                clearTimeout(timeout);
-            }
-            resolve({
-                success: result.exitCode === 0,
-                exitCode: result.exitCode,
-                stdout: truncateLog(stdout),
-                stderr: truncateLog(stderr),
-                error: result.error || ''
-            });
-        };
-
-        child.stdout?.on('data', chunk => {
-            stdout = truncateLog(`${stdout}${chunk}`, MAX_LOG_CHARS);
-        });
-        child.stderr?.on('data', chunk => {
-            stderr = truncateLog(`${stderr}${chunk}`, MAX_LOG_CHARS);
-        });
-        child.once('error', err => finish({ exitCode: -1, error: err?.message || String(err) }));
-        child.once('exit', code => finish({ exitCode: Number.isFinite(Number(code)) ? Number(code) : -1 }));
-
-        timeout = setTimeout(() => {
-            try {
-                child.kill();
-            } catch {
-                // Ignore a process that already exited while the timeout fired.
-            }
-            finish({ exitCode: -1, error: 'Codex browser login timed out.' });
-        }, timeoutMs);
-    });
-}
-
-function normalizeReasoningEffort(value) {
-    const normalized = String(value || '').trim().toLowerCase();
-    return ['minimal', 'low', 'medium', 'high', 'xhigh'].includes(normalized)
-        ? normalized
-        : 'medium';
-}
-
-function inferSandboxFromIntent(intent, prompt) {
-    const text = `${intent || ''}\n${prompt || ''}`.toLowerCase();
-    if (/(full[_ -]?access|unrestricted|danger[_ -]?full)/.test(text)) {
-        return 'workspace-write';
-    }
-
-    if (/(code[-_\s]?edit|project[-_\s]?fix|generate[-_\s]?files|implement|modify files|write files|patch|apply fix|refactor)/.test(text)) {
-        return 'workspace-write';
-    }
-
-    if (/(research|review|analy[sz]e|summari[sz]e|diagnose|inspect|audit|compare|read[-_\s]?only)/.test(text)) {
-        return 'read-only';
-    }
-
-    return 'workspace-write';
-}
-
-function normalizeSandbox(value, intent, prompt) {
-    const normalized = String(value || '').trim().toLowerCase();
-    if (normalized && SDK_SANDBOX_BY_API_VALUE[normalized]) {
-        return SDK_SANDBOX_BY_API_VALUE[normalized];
-    }
-
-    return inferSandboxFromIntent(intent, prompt);
-}
-
-function normalizeApprovalPolicy(value, sandboxMode) {
-    const normalized = String(value || '').trim().toLowerCase();
-    if (['on-request', 'on-failure', 'untrusted'].includes(normalized)) {
-        return normalized;
-    }
-
-    if (normalized === 'never' && sandboxMode !== 'danger-full-access') {
-        return 'on-request';
-    }
-
-    return 'on-request';
-}
-
-function normalizeOutputSchema(value) {
-    if (value == null) {
-        return undefined;
-    }
-
-    if (typeof value === 'object') {
-        return value;
-    }
-
-    const text = String(value || '').trim();
-    if (!text) {
-        return undefined;
-    }
-
-    return JSON.parse(text);
-}
-
-function truncateLog(value, maxChars = MAX_LOG_CHARS) {
-    const text = String(value ?? '');
-    if (text.length <= maxChars) {
-        return text;
-    }
-
-    return `${text.slice(0, maxChars)}...`;
-}
-
-function makeEmptyResult(overrides = {}) {
-    const now = new Date().toISOString();
-    return {
-        success: false,
-        providerKind: PROVIDER_KIND.unavailable,
-        threadId: '',
-        turnId: '',
-        finalResponse: '',
-        summary: '',
-        error: '',
-        status: 'failed',
-        startedAtUtc: now,
-        completedAtUtc: now,
-        sandboxMode: '',
-        changedFiles: [],
-        commandLogs: [],
-        approvalEvents: [],
-        toolEvents: [],
-        rawEventCount: 0,
-        ...overrides
-    };
-}
-
-function upsertToolEvent(result, event) {
-    const id = String(event?.id || '').trim();
-    const type = String(event?.type || '').trim();
-    const name = String(event?.name || '').trim();
-    const key = id || `${type}:${name}`;
-    const index = result.toolEvents.findIndex(existing =>
-        (String(existing?.id || '').trim() || `${existing?.type || ''}:${existing?.name || ''}`) === key);
-    if (index >= 0) {
-        result.toolEvents[index] = event;
-        return;
-    }
-
-    result.toolEvents.push(event);
-}
-
-function collectItem(result, item, eventType = '') {
-    if (!item || typeof item !== 'object') {
-        return;
-    }
-
-    if (item.type === 'agent_message' && typeof item.text === 'string') {
-        result.finalResponse = item.text;
-        return;
-    }
-
-    if (item.type === 'reasoning' && typeof item.text === 'string') {
-        result.summary = result.summary
-            ? `${result.summary}\n${item.text}`.trim()
-            : item.text.trim();
-        return;
-    }
-
-    if (item.type === 'file_change' && Array.isArray(item.changes)) {
-        for (const change of item.changes) {
-            const changePath = String(change?.path || '').trim();
-            if (!changePath) {
-                continue;
-            }
-
-            if (!result.changedFiles.some(existing => existing.path === changePath)) {
-                result.changedFiles.push({
-                    path: changePath,
-                    kind: String(change?.kind || '').trim(),
-                    status: String(item.status || '').trim()
-                });
-            }
-        }
-        return;
-    }
-
-    if (item.type === 'command_execution') {
-        result.commandLogs.push({
-            id: String(item.id || ''),
-            command: String(item.command || ''),
-            status: String(item.status || ''),
-            exitCode: Number.isFinite(Number(item.exit_code)) ? Number(item.exit_code) : null,
-            output: truncateLog(item.aggregated_output)
-        });
-        upsertToolEvent(result, {
-            id: String(item.id || ''),
-            type: 'command_execution',
-            name: String(item.command || '').trim() || 'Shell',
-            status: String(item.status || eventType || ''),
-            summary: truncateLog(item.aggregated_output, 1200)
-        });
-        return;
-    }
-
-    if (item.type === 'web_search') {
-        upsertToolEvent(result, {
-            id: String(item.id || ''),
-            type: 'web_search',
-            name: 'WebSearch',
-            status: eventType === 'item.completed' ? 'completed' : 'running',
-            summary: truncateLog(item.query, 1200)
-        });
-        return;
-    }
-
-    if (item.type === 'mcp_tool_call') {
-        const server = String(item.server || '').trim();
-        const tool = String(item.tool || '').trim();
-        upsertToolEvent(result, {
-            id: String(item.id || ''),
-            type: 'mcp_tool_call',
-            name: [server, tool].filter(Boolean).join('.') || 'MCP',
-            status: String(item.status || eventType || ''),
-            summary: item.error?.message
-                ? truncateLog(item.error.message, 1200)
-                : truncateLog(JSON.stringify(item.arguments ?? {}), 1200)
-        });
-        return;
-    }
-
-    if (item.type === 'todo_list') {
-        const items = Array.isArray(item.items) ? item.items : [];
-        upsertToolEvent(result, {
-            id: String(item.id || ''),
-            type: 'todo_list',
-            name: 'Plan',
-            status: eventType === 'item.completed' ? 'completed' : 'running',
-            summary: truncateLog(items.map(entry => `${entry?.completed ? '[x]' : '[ ]'} ${entry?.text || ''}`).join('\n'), 1200)
-        });
-        return;
-    }
-
-    if (String(item.type || '').toLowerCase().includes('approval')) {
-        result.approvalEvents.push({
-            id: String(item.id || ''),
-            type: String(item.type || ''),
-            status: String(item.status || ''),
-            summary: truncateLog(JSON.stringify(item), 1200)
-        });
-    }
-}
-
-function extractLegacyEvents(stdout, stderr) {
-    const result = {
-        finalResponse: '',
-        summary: '',
-        error: '',
-        threadId: '',
-        changedFiles: [],
-        commandLogs: [],
-        approvalEvents: [],
-        rawEventCount: 0
-    };
-
-    const lines = String(stdout || '')
-        .replace(/\r\n/g, '\n')
-        .replace(/\r/g, '\n')
-        .split('\n')
-        .filter(line => line.trim().length > 0);
-
-    for (const line of lines) {
-        let event;
-        try {
-            event = JSON.parse(line);
-        } catch {
-            continue;
-        }
-
-        result.rawEventCount += 1;
-        if (event.type === 'thread.started' && event.thread_id) {
-            result.threadId = String(event.thread_id);
-        }
-
-        if (event.type === 'turn.failed' && event.error?.message) {
-            result.error = String(event.error.message);
-        }
-
-        if (event.type === 'error' && event.message) {
-            result.error = String(event.message);
-        }
-
-        const item = event.item;
-        if (item?.type === 'agent_message' && typeof item.text === 'string') {
-            result.finalResponse = item.text;
-        } else if (item?.type === 'reasoning' && typeof item.text === 'string') {
-            result.summary = result.summary
-                ? `${result.summary}\n${item.text}`.trim()
-                : item.text.trim();
-        } else if (item?.type === 'file_change' && Array.isArray(item.changes)) {
-            for (const change of item.changes) {
-                const changePath = String(change?.path || '').trim();
-                if (changePath) {
-                    result.changedFiles.push({
-                        path: changePath,
-                        kind: String(change?.kind || ''),
-                        status: String(item.status || '')
-                    });
-                }
-            }
-        } else if (item?.type === 'command_execution') {
-            result.commandLogs.push({
-                id: String(item.id || ''),
-                command: String(item.command || ''),
-                status: String(item.status || ''),
-                exitCode: Number.isFinite(Number(item.exit_code)) ? Number(item.exit_code) : null,
-                output: truncateLog(item.aggregated_output)
-            });
-        }
-    }
-
-    if (!result.finalResponse && lines.length > 0) {
-        result.finalResponse = String(stdout || '').trim();
-    }
-
-    if (!result.error && stderr) {
-        result.error = String(stderr).trim();
-    }
-
-    return result;
-}
-
-function buildThreadOptions(body, workingDirectory) {
-    const prompt = String(body?.instruction || body?.prompt || '').trim();
-    const sandboxMode = normalizeSandbox(body?.sandbox || body?.sandboxMode, body?.intent || body?.nodeKind, prompt);
-    const approvalPolicy = normalizeApprovalPolicy(body?.approvalPolicy, sandboxMode);
-    const options = {
-        workingDirectory,
-        skipGitRepoCheck: true,
-        sandboxMode,
-        modelReasoningEffort: normalizeReasoningEffort(body?.reasoningEffort),
-        approvalPolicy
-    };
-
-    const model = String(body?.model || '').trim();
-    if (model) {
-        options.model = model;
-    }
-
-    if (body?.networkAccessEnabled !== undefined) {
-        options.networkAccessEnabled = Boolean(body.networkAccessEnabled);
-    }
-
-    const webSearchMode = String(body?.webSearchMode || '').trim().toLowerCase();
-    if (['disabled', 'cached', 'live'].includes(webSearchMode)) {
-        options.webSearchMode = webSearchMode;
-    }
-
-    return options;
-}
-
-function serializeThreadOptionsForStatus(options) {
-    return {
-        model: options?.model || null,
-        sandboxMode: API_SANDBOX_BY_SDK_VALUE[options?.sandboxMode] || options?.sandboxMode || null,
-        reasoningEffort: options?.modelReasoningEffort || null,
-        approvalPolicy: options?.approvalPolicy || null,
-        networkAccessEnabled: options?.networkAccessEnabled ?? null,
-        webSearchMode: options?.webSearchMode || null,
-        workingDirectory: options?.workingDirectory || null
-    };
-}
-
-async function checkSdkAvailability(packageRoot, sdkLoader = loadCodexSdk) {
-    const sdk = await sdkLoader();
-    return {
-        kind: PROVIDER_KIND.typeScriptSdk,
-        available: Boolean(sdk?.Codex),
-        version: safeReadPackageVersion(packageRoot, '@openai/codex-sdk'),
-        error: sdk?.Codex ? null : (cachedSdkLoadError || 'Codex SDK module did not export Codex.')
-    };
-}
-
-async function checkLegacyAvailability() {
-    const now = Date.now();
-    if (cachedLegacyAvailability && cachedLegacyAvailabilityExpiresAt > now) {
-        return cachedLegacyAvailability;
-    }
-
-    try {
-        const { stdout, stderr } = await execAsync('codex --version', {
-            timeout: 6000,
-            windowsHide: true,
-            maxBuffer: 512 * 1024
-        });
-        cachedLegacyAvailability = {
-            kind: PROVIDER_KIND.legacyExec,
-            available: true,
-            version: String(stdout || stderr || '').trim(),
-            error: null
-        };
-    } catch (err) {
-        cachedLegacyAvailability = {
-            kind: PROVIDER_KIND.legacyExec,
-            available: false,
-            version: null,
-            error: err?.message || String(err)
-        };
-    }
-
-    cachedLegacyAvailabilityExpiresAt = now + 30 * 1000;
-    return cachedLegacyAvailability;
-}
-
-function extractPrompt(body) {
-    const prompt = String(body?.instruction || body?.prompt || '').trim();
-    if (!prompt) {
-        const err = new Error('Codex prompt is required.');
-        err.statusCode = 400;
-        throw err;
-    }
-
-    return prompt;
-}
-
-function looksLikeCodexAuthenticationError(value) {
-    const text = String(value || '').toLowerCase();
-    return text.includes('invalid_refresh_token')
-        || text.includes('invalid refresh token')
-        || text.includes('login required')
-        || text.includes('not logged in')
-        || text.includes('please log out and sign in again')
-        || text.includes('could not parse your authentication token')
-        || text.includes('authrequired')
-        || text.includes('401 unauthorized');
-}
-
-function normalizeImageMimeType(value, fallback = 'image/png') {
-    const normalized = String(value || '').trim().toLowerCase();
-    return /^image\/[a-z0-9.+-]+$/.test(normalized) ? normalized : fallback;
-}
-
-function inferImageMimeType(buffer, fallback = 'image/png') {
-    if (!Buffer.isBuffer(buffer) || buffer.length < 4) {
-        return fallback;
-    }
-
-    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
-        return 'image/png';
-    }
-    if (buffer[0] === 0xff && buffer[1] === 0xd8) {
-        return 'image/jpeg';
-    }
-    if (buffer.slice(0, 3).toString('ascii') === 'GIF') {
-        return 'image/gif';
-    }
-    if (buffer.length >= 12
-        && buffer.slice(0, 4).toString('ascii') === 'RIFF'
-        && buffer.slice(8, 12).toString('ascii') === 'WEBP') {
-        return 'image/webp';
-    }
-
-    return fallback;
-}
-
-function normalizeGeneratedImageBase64(value, hintedMimeType = '') {
-    const text = String(value || '').trim();
-    if (!text) {
-        return null;
-    }
-
-    const dataUrlMatch = text.match(/^data:(image\/[a-z0-9.+-]+);base64,([a-z0-9+/=\r\n]+)$/i);
-    const base64 = (dataUrlMatch ? dataUrlMatch[2] : text).replace(/\s+/g, '');
-    if (base64.length < 32 || !/^[a-z0-9+/]+={0,2}$/i.test(base64)) {
-        return null;
-    }
-
-    try {
-        const bytes = Buffer.from(base64, 'base64');
-        if (!bytes.length || bytes.length > MAX_GENERATED_IMAGE_BYTES) {
-            return null;
-        }
-        const mimeType = inferImageMimeType(
-            bytes,
-            normalizeImageMimeType(dataUrlMatch?.[1] || hintedMimeType));
-        return { imageBase64: bytes.toString('base64'), mimeType };
-    } catch {
-        return null;
-    }
-}
-
-function extractGeneratedImageFromEvent(value, depth = 0, hintedMimeType = '') {
-    if (value == null || depth > 10) {
-        return null;
-    }
-
-    if (typeof value === 'string') {
-        return value.startsWith('data:image/')
-            ? normalizeGeneratedImageBase64(value, hintedMimeType)
-            : null;
-    }
-
-    if (Array.isArray(value)) {
-        for (const entry of value) {
-            const found = extractGeneratedImageFromEvent(entry, depth + 1, hintedMimeType);
-            if (found) {
-                return found;
-            }
-        }
-        return null;
-    }
-
-    if (typeof value !== 'object') {
-        return null;
-    }
-
-    const localMimeType = normalizeImageMimeType(
-        value.mime_type || value.mimeType || value.content_type || value.contentType,
-        hintedMimeType || 'image/png');
-    for (const key of ['b64_json', 'image_base64', 'imageBase64', 'base64']) {
-        if (typeof value[key] === 'string') {
-            const found = normalizeGeneratedImageBase64(value[key], localMimeType);
-            if (found) {
-                return found;
-            }
-        }
-    }
-
-    for (const key of ['result', 'output', 'image', 'images', 'data', 'payload', 'item']) {
-        if (value[key] != null) {
-            const found = extractGeneratedImageFromEvent(value[key], depth + 1, localMimeType);
-            if (found) {
-                return found;
-            }
-        }
-    }
-
-    return null;
-}
-
-function imageExtensionForReference(reference) {
-    const fileNameExtension = path.extname(String(reference?.fileName || '')).toLowerCase();
-    if (['.png', '.jpg', '.jpeg', '.webp', '.gif'].includes(fileNameExtension)) {
-        return fileNameExtension === '.jpeg' ? '.jpg' : fileNameExtension;
-    }
-
-    const mimeType = normalizeImageMimeType(reference?.mimeType);
-    if (mimeType === 'image/jpeg') return '.jpg';
-    if (mimeType === 'image/webp') return '.webp';
-    if (mimeType === 'image/gif') return '.gif';
-    return '.png';
-}
-
-async function writeSdkImageReferences(runtimeHome, references) {
-    const normalized = Array.isArray(references)
-        ? references.slice(0, MAX_IMAGE_REFERENCE_COUNT)
-        : [];
-    if (!normalized.length) {
-        return { directory: '', paths: [] };
-    }
-
-    const root = path.join(runtimeHome, 'image-inputs');
-    const directory = path.join(root, crypto.randomUUID());
-    await fs.mkdir(directory, { recursive: true });
-    const paths = [];
-    let totalBytes = 0;
-
-    try {
-        for (let index = 0; index < normalized.length; index += 1) {
-            const reference = normalized[index];
-            const bytes = Buffer.from(String(reference?.base64 || ''), 'base64');
-            totalBytes += bytes.length;
-            if (!bytes.length || totalBytes > MAX_IMAGE_REFERENCE_BYTES) {
-                throw new Error('Codex SDK image references are empty or exceed the 40 MB request limit.');
-            }
-
-            const filePath = path.join(directory, `reference-${index + 1}${imageExtensionForReference(reference)}`);
-            await fs.writeFile(filePath, bytes);
-            paths.push(filePath);
-        }
-
-        return { directory, paths };
-    } catch (err) {
-        await fs.rm(directory, { recursive: true, force: true }).catch(() => {});
-        throw err;
-    }
-}
-
-async function cleanupSdkImageReferences(runtimeHome, directory) {
-    if (!directory) {
-        return;
-    }
-
-    const root = path.resolve(runtimeHome, 'image-inputs');
-    const target = path.resolve(directory);
-    if (!target.startsWith(`${root}${path.sep}`)) {
-        return;
-    }
-    await fs.rm(target, { recursive: true, force: true }).catch(() => {});
-}
-
-function buildSdkImagePrompt(body, referenceCount) {
-    const prompt = extractPrompt(body);
-    const action = String(body?.action || '').trim().toLowerCase() === 'edit' || referenceCount > 0
-        ? 'edit'
-        : 'generate';
-    const size = String(body?.size || '').trim();
-    const quality = String(body?.quality || '').trim();
-    return [
-        action === 'edit'
-            ? `Use the image generation tool to edit the ${referenceCount} attached reference image(s).`
-            : 'Use the image generation tool to create one new image.',
-        prompt,
-        size ? `Requested output size: ${size}.` : '',
-        quality ? `Requested quality: ${quality}.` : '',
-        'Return exactly one generated image. Do not answer with instructions or prose.'
-    ].filter(Boolean).join('\n\n');
-}
-
-async function listGeneratedImageCandidates(directory, minimumMtimeMs, depth = 0) {
-    if (depth > 4) {
-        return [];
-    }
-
-    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
-    const candidates = [];
-    for (const entry of entries) {
-        const fullPath = path.join(directory, entry.name);
-        if (entry.isDirectory()) {
-            candidates.push(...await listGeneratedImageCandidates(fullPath, minimumMtimeMs, depth + 1));
-            continue;
-        }
-        if (!entry.isFile() || !/\.(png|jpe?g|webp|gif)$/i.test(entry.name)) {
-            continue;
-        }
-
-        const stat = await fs.stat(fullPath).catch(() => null);
-        if (stat && stat.size > 0 && stat.size <= MAX_GENERATED_IMAGE_BYTES && stat.mtimeMs >= minimumMtimeMs) {
-            candidates.push({ fullPath, mtimeMs: stat.mtimeMs });
-        }
-    }
-    return candidates;
-}
-
-async function recoverSdkGeneratedImage(runtimeHome, startedAtMs) {
-    const generatedRoot = path.join(runtimeHome, 'generated_images');
-    const minimumMtimeMs = startedAtMs - 15 * 1000;
-    for (let attempt = 0; attempt < 8; attempt += 1) {
-        const candidates = await listGeneratedImageCandidates(generatedRoot, minimumMtimeMs);
-        candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
-        if (candidates[0]) {
-            const bytes = await fs.readFile(candidates[0].fullPath);
-            return {
-                imageBase64: bytes.toString('base64'),
-                mimeType: inferImageMimeType(bytes)
-            };
-        }
-        await new Promise(resolve => setTimeout(resolve, 350));
-    }
-    return null;
-}
-
-export function createCodexRuntime(options) {
-    const packageRoot = options.packageRoot;
-    const resolveWorkingDirectory = options.resolveWorkingDirectory;
-    const getCurrentRuntime = options.getCurrentRuntime;
-    const getModelCatalog = options.getModelCatalog;
-    const log = typeof options.log === 'function' ? options.log : () => {};
-    const sdkLoader = typeof options.loadCodexSdk === 'function' ? options.loadCodexSdk : loadCodexSdk;
-    const prepareRuntimeHome = typeof options.ensureCodexRuntimeHome === 'function'
-        ? options.ensureCodexRuntimeHome
-        : ensureCodexRuntimeHome;
-    const childEnvFactory = typeof options.buildCodexChildEnv === 'function'
-        ? options.buildCodexChildEnv
-        : buildCodexChildEnv;
-
-    const threads = new Map();
-    const activeTurns = new Map();
-    let activeLoginPromise = null;
-
-    async function loginWithBundledCodex() {
-        if (typeof options.loginCodex === 'function') {
-            return options.loginCodex();
-        }
-
-        if (activeLoginPromise) {
-            return activeLoginPromise;
-        }
-
-        activeLoginPromise = (async () => {
-            await prepareRuntimeHome();
-            await runBundledCodexCommand(packageRoot, ['logout'], 15000).catch(() => null);
-            log('Codex SDK browser login start', { runtimeHome: resolveCodexRuntimeHome() });
-            const loginResult = await runBundledCodexCommand(packageRoot, ['login']);
-            log('Codex SDK browser login finish', {
-                success: loginResult.success,
-                exitCode: loginResult.exitCode,
-                error: loginResult.error || ''
-            });
-            return loginResult;
-        })().finally(() => {
-            activeLoginPromise = null;
-        });
-
-        return activeLoginPromise;
-    }
-
-    async function getCapabilities(options = {}) {
-        const [sdk, legacy, modelCatalog] = await Promise.all([
-            checkSdkAvailability(packageRoot, sdkLoader),
-            checkLegacyAvailability(),
-            getModelCatalog({ forceRefresh: Boolean(options.forceRefresh) })
-        ]);
-        const preferredProviderKind = sdk.available
-            ? PROVIDER_KIND.typeScriptSdk
-            : legacy.available
-                ? PROVIDER_KIND.legacyExec
-                : PROVIDER_KIND.unavailable;
-
-        return {
-            success: preferredProviderKind !== PROVIDER_KIND.unavailable,
-            preferredProviderKind,
-            providers: [
-                sdk,
-                {
-                    kind: PROVIDER_KIND.appServerJsonRpc,
-                    available: false,
-                    implemented: false,
-                    error: 'DTO scaffold only. Use TypeScriptSdk for LocalBridge execution.'
-                },
-                legacy
-            ],
-            sandboxModes: ['read_only', 'workspace_write', 'full_access'],
-            endpoints: [
-                'GET /api/codex/capabilities',
-                'POST /api/codex/thread/start',
-                'POST /api/codex/thread/run',
-                'POST /api/codex/thread/resume',
-                'POST /api/codex/thread/cancel',
-                'POST /api/codex/image/run',
-                'GET /api/codex/thread/{threadId}/status'
-            ],
-            runtime: getCurrentRuntime(),
-            models: modelCatalog.models || [],
-            modelCatalogSource: modelCatalog.source,
-            modelCatalogCommandSource: modelCatalog.commandSource || null,
-            modelCatalogUpdatedAt: modelCatalog.updatedAt,
-            modelCatalogRefreshAttemptedAt: modelCatalog.refreshAttemptedAt || null,
-            modelCatalogStale: modelCatalog.stale === true,
-            modelCatalogError: modelCatalog.error || null
-        };
-    }
-
-    async function resolveProvider(requestedProviderKind) {
-        const requested = normalizeProviderKind(requestedProviderKind);
-        const sdk = await checkSdkAvailability(packageRoot, sdkLoader);
-        const legacy = requested === PROVIDER_KIND.typeScriptSdk
-            ? null
-            : await checkLegacyAvailability();
-
-        if ((!requested || requested === PROVIDER_KIND.typeScriptSdk) && sdk.available) {
-            return PROVIDER_KIND.typeScriptSdk;
-        }
-
-        if ((!requested || requested === PROVIDER_KIND.legacyExec) && legacy?.available) {
-            return PROVIDER_KIND.legacyExec;
-        }
-
-        return PROVIDER_KIND.unavailable;
-    }
-
-    async function startThread(body = {}) {
-        const providerKind = await resolveProvider(body.providerKind || body.runtime);
-        const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
-        const threadOptions = buildThreadOptions(body, workingDirectory);
-        const now = new Date().toISOString();
-
-        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
-            const sdk = await sdkLoader();
-            await prepareRuntimeHome();
-            const codex = new sdk.Codex({
-                env: childEnvFactory(),
-                config: buildCodexSdkConfigOverrides()
-            });
-            const thread = codex.startThread(threadOptions);
-            const localThreadId = `local_${crypto.randomUUID()}`;
-            threads.set(localThreadId, {
-                providerKind,
-                thread,
-                createdAtUtc: now,
-                updatedAtUtc: now,
-                options: threadOptions,
-                officialThreadId: null,
-                lastStatus: 'created'
-            });
-
-            return makeEmptyResult({
-                success: true,
-                providerKind,
-                threadId: localThreadId,
-                status: 'created',
-                startedAtUtc: now,
-                completedAtUtc: now,
-                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
-            });
-        }
-
-        if (providerKind === PROVIDER_KIND.legacyExec) {
-            const localThreadId = `legacy_${crypto.randomUUID()}`;
-            threads.set(localThreadId, {
-                providerKind,
-                createdAtUtc: now,
-                updatedAtUtc: now,
-                options: threadOptions,
-                officialThreadId: localThreadId,
-                lastStatus: 'created'
-            });
-
-            return makeEmptyResult({
-                success: true,
-                providerKind,
-                threadId: localThreadId,
-                status: 'created',
-                startedAtUtc: now,
-                completedAtUtc: now,
-                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
-            });
-        }
-
-        return makeEmptyResult({
-            providerKind,
-            error: 'Codex local runtime is not available. Install LocalBridge dependencies or Codex CLI, then run codex login.'
-        });
-    }
-
-    async function getSdkThread(body, threadOptions) {
-        const requestedThreadId = String(body?.threadId || '').trim();
-        if (requestedThreadId && threads.has(requestedThreadId)) {
-            return {
-                key: requestedThreadId,
-                record: threads.get(requestedThreadId)
-            };
-        }
-
-        const sdk = await sdkLoader();
-        await prepareRuntimeHome();
-        const codex = new sdk.Codex({
-            env: childEnvFactory(),
-            config: buildCodexSdkConfigOverrides()
-        });
-        const officialId = requestedThreadId && !requestedThreadId.startsWith('local_')
-            ? requestedThreadId
-            : '';
-        const thread = officialId
-            ? codex.resumeThread(officialId, threadOptions)
-            : codex.startThread(threadOptions);
-        const key = officialId || `local_${crypto.randomUUID()}`;
-        const record = {
-            providerKind: PROVIDER_KIND.typeScriptSdk,
-            thread,
-            createdAtUtc: new Date().toISOString(),
-            updatedAtUtc: new Date().toISOString(),
-            options: threadOptions,
-            officialThreadId: officialId || null,
-            lastStatus: 'created'
-        };
-        threads.set(key, record);
-        return { key, record };
-    }
-
-    async function runSdkThread(body, workingDirectory, prompt, startedAtUtc) {
-        const threadOptions = buildThreadOptions(body, workingDirectory);
-        const { key, record } = await getSdkThread(body, threadOptions);
-        const turnId = `turn_${crypto.randomUUID()}`;
-        const abortController = new AbortController();
-        const activeKey = `${key}:${turnId}`;
-        activeTurns.set(activeKey, {
-            providerKind: PROVIDER_KIND.typeScriptSdk,
-            threadId: key,
-            turnId,
-            abortController,
-            startedAtUtc
-        });
-
-        const result = makeEmptyResult({
-            providerKind: PROVIDER_KIND.typeScriptSdk,
-            threadId: record.officialThreadId || key,
-            turnId,
-            status: 'running',
-            startedAtUtc,
-            completedAtUtc: '',
-            sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
-        });
-        let timeout = null;
-
-        try {
-            timeout = setTimeout(() => {
-                try {
-                    abortController.abort();
-                } catch {
-                    // Ignore duplicate aborts.
-                }
-            }, DEFAULT_TIMEOUT_MS);
-
-            log('Codex SDK run start', {
-                threadId: result.threadId,
-                turnId,
-                sandbox: result.sandboxMode,
-                cwd: workingDirectory
-            });
-
-            const outputSchema = normalizeOutputSchema(body.outputSchema || body.outputSchemaJson);
-            const { events } = await record.thread.runStreamed(prompt, {
-                outputSchema,
-                signal: abortController.signal
-            });
-
-            for await (const event of events) {
-                result.rawEventCount += 1;
-                if (result.rawEventCount <= MAX_EVENT_LOG) {
-                    record.lastEvent = event;
-                }
-
-                if (event.type === 'thread.started' && event.thread_id) {
-                    record.officialThreadId = String(event.thread_id);
-                    result.threadId = record.officialThreadId;
-                    threads.set(record.officialThreadId, record);
-                } else if (event.type === 'item.completed' || event.type === 'item.updated' || event.type === 'item.started') {
-                    collectItem(result, event.item, event.type);
-                } else if (event.type === 'turn.failed') {
-                    result.error = event.error?.message || 'Codex turn failed.';
-                    result.status = 'failed';
-                } else if (event.type === 'error') {
-                    result.error = event.message || 'Codex stream failed.';
-                    result.status = 'failed';
-                } else if (event.type === 'turn.completed') {
-                    result.status = 'completed';
-                }
-            }
-
-            if (!result.error && result.status !== 'failed') {
-                result.success = true;
-                result.status = result.status === 'running' ? 'completed' : result.status;
-            }
-
-            if (!result.finalResponse && result.success) {
-                result.finalResponse = result.summary;
-            }
-
-            if (!result.finalResponse && !result.error) {
-                result.error = 'Codex returned an empty response.';
-                result.status = 'failed';
-                result.success = false;
-            }
-        } catch (err) {
-            const aborted = abortController.signal.aborted;
-            result.error = aborted ? 'Codex turn was cancelled.' : (err?.message || String(err));
-            result.status = aborted ? 'cancelled' : 'failed';
-            result.success = false;
-        } finally {
-            if (timeout) {
-                clearTimeout(timeout);
-            }
-            result.completedAtUtc = new Date().toISOString();
-            record.updatedAtUtc = result.completedAtUtc;
-            record.lastStatus = result.status;
-            record.lastResult = result;
-            activeTurns.delete(activeKey);
-        }
-
-        return result;
-    }
-
-    async function runLegacyExec(body, workingDirectory, prompt, startedAtUtc) {
-        const threadOptions = buildThreadOptions(body, workingDirectory);
-        const turnId = `turn_${crypto.randomUUID()}`;
-        const threadId = String(body.threadId || `legacy_${crypto.randomUUID()}`);
-        const abortController = new AbortController();
-        const activeKey = `${threadId}:${turnId}`;
-        activeTurns.set(activeKey, {
-            providerKind: PROVIDER_KIND.legacyExec,
-            threadId,
-            turnId,
-            abortController,
-            startedAtUtc
-        });
-
-        const tempDir = path.join(workingDirectory, TEMP_DIR);
-        const schema = normalizeOutputSchema(body.outputSchema || body.outputSchemaJson);
-        let schemaPath = null;
-        await prepareRuntimeHome();
-        const args = [
-            'exec',
-            '-',
-            '--skip-git-repo-check',
-            '--json',
-            '--disable',
-            'plugins',
-            '--disable',
-            'shell_snapshot',
-            '-s',
-            threadOptions.sandboxMode,
-            '--config',
-            `model_reasoning_effort=${threadOptions.modelReasoningEffort}`,
-            '--config',
-            'mcp_servers={}'
-        ];
-        if (threadOptions.model) {
-            args.push('-m', threadOptions.model);
-        }
-
-        if (schema) {
-            await fs.mkdir(tempDir, { recursive: true });
-            schemaPath = path.join(tempDir, `${crypto.randomUUID()}.schema.json`);
-            await fs.writeFile(schemaPath, JSON.stringify(schema), 'utf8');
-            args.push('--output-schema', schemaPath);
-        }
-
-        const result = makeEmptyResult({
-            providerKind: PROVIDER_KIND.legacyExec,
-            threadId,
-            turnId,
-            status: 'running',
-            startedAtUtc,
-            completedAtUtc: '',
-            sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
-        });
-
-        try {
-            const childResult = await new Promise((resolve) => {
-                const child = spawn('codex', args, {
-                    cwd: workingDirectory,
-                    env: childEnvFactory(),
-                    windowsHide: true,
-                    signal: abortController.signal
-                });
-                let stdout = '';
-                let stderr = '';
-                let settled = false;
-                const timeout = setTimeout(() => {
-                    try {
-                        abortController.abort();
-                    } catch {
-                        // Ignore duplicate aborts.
-                    }
-                    try {
-                        child.kill('SIGTERM');
-                    } catch {
-                        // Ignore if already exited.
-                    }
-                }, DEFAULT_TIMEOUT_MS);
-
-                const settle = (payload) => {
-                    if (settled) return;
-                    settled = true;
-                    clearTimeout(timeout);
-                    resolve(payload);
-                };
-
-                child.stdout?.on('data', chunk => {
-                    stdout += chunk.toString();
-                });
-                child.stderr?.on('data', chunk => {
-                    stderr += chunk.toString();
-                });
-                child.on('error', err => {
-                    settle({ exitCode: -1, stdout, stderr, error: err?.message || String(err) });
-                });
-                child.on('close', code => {
-                    settle({ exitCode: Number.isFinite(code) ? code : -1, stdout, stderr, error: '' });
-                });
-                child.stdin?.write(prompt);
-                child.stdin?.end();
-            });
-
-            const parsed = extractLegacyEvents(childResult.stdout, childResult.stderr);
-            result.threadId = parsed.threadId || threadId;
-            result.finalResponse = parsed.finalResponse;
-            result.summary = parsed.summary;
-            result.changedFiles = parsed.changedFiles;
-            result.commandLogs = parsed.commandLogs;
-            result.approvalEvents = parsed.approvalEvents;
-            result.rawEventCount = parsed.rawEventCount;
-            result.error = childResult.error || parsed.error;
-            result.success = childResult.exitCode === 0 && Boolean(result.finalResponse);
-            result.status = result.success ? 'completed' : 'failed';
-            if (!result.error && !result.success) {
-                result.error = parsed.error || 'Codex legacy exec returned an empty response.';
-            }
-        } catch (err) {
-            const aborted = abortController.signal.aborted;
-            result.error = aborted ? 'Codex turn was cancelled.' : (err?.message || String(err));
-            result.status = aborted ? 'cancelled' : 'failed';
-            result.success = false;
-        } finally {
-            result.completedAtUtc = new Date().toISOString();
-            activeTurns.delete(activeKey);
-            if (schemaPath) {
-                await fs.unlink(schemaPath).catch(() => {});
-            }
-            threads.set(result.threadId, {
-                providerKind: PROVIDER_KIND.legacyExec,
-                createdAtUtc: startedAtUtc,
-                updatedAtUtc: result.completedAtUtc,
-                options: threadOptions,
-                officialThreadId: result.threadId,
-                lastStatus: result.status,
-                lastResult: result
-            });
-        }
-
-        return result;
-    }
-
-    async function runThread(body = {}) {
-        const prompt = extractPrompt(body);
-        const startedAtUtc = new Date().toISOString();
-        const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
-        const providerKind = await resolveProvider(body.providerKind || body.runtime);
-
-        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
-            return runSdkThread(body, workingDirectory, prompt, startedAtUtc);
-        }
-
-        if (providerKind === PROVIDER_KIND.legacyExec) {
-            return runLegacyExec(body, workingDirectory, prompt, startedAtUtc);
-        }
-
-        return makeEmptyResult({
-            providerKind,
-            startedAtUtc,
-            completedAtUtc: new Date().toISOString(),
-            error: 'Codex local runtime is not available. TypeScript SDK and legacy codex exec are unavailable.'
-        });
-    }
-
-    async function runSdkImageOnce(body = {}) {
-        const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
-        const runtimeHome = await prepareRuntimeHome();
-        const sdk = await sdkLoader();
-        if (!sdk?.Codex) {
-            return {
-                success: false,
-                providerKind: PROVIDER_KIND.unavailable,
-                imageBase64: '',
-                mimeType: '',
-                error: cachedSdkLoadError || 'Codex TypeScript SDK is unavailable.',
-                threadId: '',
-                authenticationRequired: false,
-                loginOpened: false
-            };
-        }
-
-        const references = await writeSdkImageReferences(runtimeHome, body.referenceImages);
-        const prompt = buildSdkImagePrompt(body, references.paths.length);
-        const threadOptions = buildThreadOptions({
-            ...body,
-            sandbox: 'read_only',
-            approvalPolicy: 'on-request',
-            reasoningEffort: 'low',
-            networkAccessEnabled: true,
-            webSearchMode: 'disabled'
-        }, workingDirectory);
-        const startedAtMs = Date.now();
-        let threadId = '';
-        let error = '';
-        let generatedImage = null;
-
-        try {
-            const codex = new sdk.Codex({
-                env: childEnvFactory(),
-                config: buildCodexSdkConfigOverrides({
-                    features: { image_generation: true }
-                })
-            });
-            const thread = codex.startThread(threadOptions);
-            const input = [
-                { type: 'text', text: prompt },
-                ...references.paths.map(referencePath => ({ type: 'local_image', path: referencePath }))
-            ];
-            const { events } = await thread.runStreamed(input);
-
-            for await (const event of events) {
-                if (event?.type === 'thread.started' && event.thread_id) {
-                    threadId = String(event.thread_id);
-                } else if (event?.type === 'turn.failed') {
-                    error = event.error?.message || 'Codex SDK image turn failed.';
-                } else if (event?.type === 'error') {
-                    error = event.message || 'Codex SDK image stream failed.';
-                }
-
-                generatedImage ||= extractGeneratedImageFromEvent(event);
-            }
-        } catch (err) {
-            error = err?.message || String(err);
-        } finally {
-            await cleanupSdkImageReferences(runtimeHome, references.directory);
-        }
-
-        const authenticationRequired = looksLikeCodexAuthenticationError(error);
-        if (!authenticationRequired) {
-            generatedImage ||= await recoverSdkGeneratedImage(runtimeHome, startedAtMs);
-        }
-        if (generatedImage) {
-            return {
-                success: true,
-                providerKind: PROVIDER_KIND.typeScriptSdk,
-                imageBase64: generatedImage.imageBase64,
-                mimeType: generatedImage.mimeType,
-                error: '',
-                threadId,
-                authenticationRequired: false,
-                loginOpened: false
-            };
-        }
-
-        return {
-            success: false,
-            providerKind: PROVIDER_KIND.typeScriptSdk,
-            imageBase64: '',
-            mimeType: '',
-            error: error || 'Codex SDK completed without returning an image.',
-            threadId,
-            authenticationRequired,
-            loginOpened: false
-        };
-    }
-
-    async function runImage(body = {}) {
-        extractPrompt(body);
-        const firstResult = await runSdkImageOnce(body);
-        if (!firstResult.authenticationRequired) {
-            return firstResult;
-        }
-
-        const loginResult = await loginWithBundledCodex();
-        const loginSucceeded = loginResult === true || loginResult?.success === true;
-        if (!loginSucceeded) {
-            return {
-                ...firstResult,
-                loginOpened: true,
-                error: loginResult?.error
-                    || 'Codex sign-in was not completed. Finish the browser login and retry.'
-            };
-        }
-
-        const retryResult = await runSdkImageOnce(body);
-        return {
-            ...retryResult,
-            loginOpened: true,
-            authenticationRequired: retryResult.authenticationRequired
-        };
-    }
-
-    async function resumeThread(body = {}) {
-        const providerKind = await resolveProvider(body.providerKind || body.runtime);
-        const threadId = String(body.threadId || '').trim();
-        if (!threadId) {
-            const err = new Error('threadId is required.');
-            err.statusCode = 400;
-            throw err;
-        }
-
-        if (threads.has(threadId)) {
-            const record = threads.get(threadId);
-            record.lastStatus = 'resumed';
-            record.updatedAtUtc = new Date().toISOString();
-            return makeEmptyResult({
-                success: true,
-                providerKind: record.providerKind,
-                threadId,
-                status: 'resumed',
-                sandboxMode: API_SANDBOX_BY_SDK_VALUE[record.options?.sandboxMode] || record.options?.sandboxMode || ''
-            });
-        }
-
-        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
-            const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
-            const threadOptions = buildThreadOptions(body, workingDirectory);
-            const sdk = await sdkLoader();
-            await prepareRuntimeHome();
-            const codex = new sdk.Codex({
-                env: childEnvFactory(),
-                config: buildCodexSdkConfigOverrides()
-            });
-            const thread = codex.resumeThread(threadId, threadOptions);
-            threads.set(threadId, {
-                providerKind,
-                thread,
-                createdAtUtc: new Date().toISOString(),
-                updatedAtUtc: new Date().toISOString(),
-                options: threadOptions,
-                officialThreadId: threadId,
-                lastStatus: 'resumed'
-            });
-            return makeEmptyResult({
-                success: true,
-                providerKind,
-                threadId,
-                status: 'resumed',
-                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
-            });
-        }
-
-        return makeEmptyResult({
-            providerKind,
-            threadId,
-            error: 'Thread resume is only supported by the TypeScript SDK provider.'
-        });
-    }
-
-    function cancelThread(body = {}) {
-        const threadId = String(body.threadId || '').trim();
-        const turnId = String(body.turnId || '').trim();
-        const matches = [];
-        for (const [key, turn] of activeTurns.entries()) {
-            if (threadId && turn.threadId !== threadId) {
-                continue;
-            }
-            if (turnId && turn.turnId !== turnId) {
-                continue;
-            }
-            matches.push([key, turn]);
-        }
-
-        for (const [, turn] of matches) {
-            try {
-                turn.abortController.abort();
-            } catch {
-                // Ignore duplicate aborts.
-            }
-        }
-
-        return {
-            success: matches.length > 0,
-            cancelled: matches.length,
-            threadId,
-            turnId,
-            status: matches.length > 0 ? 'cancel-requested' : 'not-found'
-        };
-    }
-
-    function getThreadStatus(threadId) {
-        const id = String(threadId || '').trim();
-        const record = threads.get(id);
-        const active = Array.from(activeTurns.values())
-            .filter(turn => turn.threadId === id || record?.officialThreadId === turn.threadId)
-            .map(turn => ({
-                providerKind: turn.providerKind,
-                threadId: turn.threadId,
-                turnId: turn.turnId,
-                startedAtUtc: turn.startedAtUtc,
-                status: 'running'
-            }));
-
-        return {
-            success: Boolean(record || active.length > 0),
-            threadId: id,
-            providerKind: record?.providerKind || active[0]?.providerKind || PROVIDER_KIND.unavailable,
-            officialThreadId: record?.officialThreadId || null,
-            status: active.length > 0 ? 'running' : (record?.lastStatus || 'not-found'),
-            createdAtUtc: record?.createdAtUtc || null,
-            updatedAtUtc: record?.updatedAtUtc || null,
-            options: serializeThreadOptionsForStatus(record?.options),
-            activeTurns: active,
-            lastResult: record?.lastResult || null
-        };
-    }
-
-    return {
-        providerKinds: PROVIDER_KIND,
-        getCapabilities,
-        startThread,
-        runThread,
-        runImage,
-        resumeThread,
-        cancelThread,
-        getThreadStatus
-    };
-}
+import { promises as fs, readFileSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { exec, spawn } from 'child_process';
+import { promisify } from 'util';
+import crypto from 'crypto';
+
+const execAsync = promisify(exec);
+
+const PROVIDER_KIND = Object.freeze({
+    typeScriptSdk: 'TypeScriptSdk',
+    appServerJsonRpc: 'AppServerJsonRpc',
+    legacyExec: 'LegacyExec',
+    unavailable: 'Unavailable'
+});
+
+const SDK_SANDBOX_BY_API_VALUE = Object.freeze({
+    read_only: 'read-only',
+    'read-only': 'read-only',
+    readonly: 'read-only',
+    workspace_write: 'workspace-write',
+    'workspace-write': 'workspace-write',
+    workspacewrite: 'workspace-write',
+    full_access: 'danger-full-access',
+    fullaccess: 'danger-full-access',
+    danger_full_access: 'danger-full-access',
+    'danger-full-access': 'danger-full-access'
+});
+
+const API_SANDBOX_BY_SDK_VALUE = Object.freeze({
+    'read-only': 'read_only',
+    'workspace-write': 'workspace_write',
+    'danger-full-access': 'full_access'
+});
+
+const DEFAULT_TIMEOUT_MS = 8 * 60 * 1000;
+const CODEX_LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_LOG_CHARS = 4000;
+const MAX_EVENT_LOG = 120;
+const MAX_IMAGE_REFERENCE_COUNT = 8;
+const MAX_IMAGE_REFERENCE_BYTES = 40 * 1024 * 1024;
+const MAX_GENERATED_IMAGE_BYTES = 50 * 1024 * 1024;
+const TEMP_DIR = '.ai/codex';
+const CODEX_RUNTIME_HOME_ENV = 'MINDEXEC_CODEX_HOME';
+const CODEX_RUNTIME_CONFIG_MARKER = '# Generated by MindExec LocalBridge for isolated AI node runs.';
+const CODEX_TARGET_BY_PLATFORM = Object.freeze({
+    'win32:x64': {
+        packageName: '@openai/codex-win32-x64',
+        targetTriple: 'x86_64-pc-windows-msvc',
+        binaryName: 'codex.exe'
+    },
+    'win32:arm64': {
+        packageName: '@openai/codex-win32-arm64',
+        targetTriple: 'aarch64-pc-windows-msvc',
+        binaryName: 'codex.exe'
+    },
+    'darwin:x64': {
+        packageName: '@openai/codex-darwin-x64',
+        targetTriple: 'x86_64-apple-darwin',
+        binaryName: 'codex'
+    },
+    'darwin:arm64': {
+        packageName: '@openai/codex-darwin-arm64',
+        targetTriple: 'aarch64-apple-darwin',
+        binaryName: 'codex'
+    },
+    'linux:x64': {
+        packageName: '@openai/codex-linux-x64',
+        targetTriple: 'x86_64-unknown-linux-musl',
+        binaryName: 'codex'
+    },
+    'linux:arm64': {
+        packageName: '@openai/codex-linux-arm64',
+        targetTriple: 'aarch64-unknown-linux-musl',
+        binaryName: 'codex'
+    }
+});
+
+let cachedSdkModule = null;
+let cachedSdkLoadError = null;
+let cachedLegacyAvailability = null;
+let cachedLegacyAvailabilityExpiresAt = 0;
+
+function safeReadPackageVersion(packageRoot, packageName) {
+    try {
+        const packageJsonPath = path.join(packageRoot, 'node_modules', ...packageName.split('/'), 'package.json');
+        const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+        return parsed.version || null;
+    } catch {
+        return null;
+    }
+}
+
+async function loadCodexSdk() {
+    if (cachedSdkModule) {
+        return cachedSdkModule;
+    }
+
+    try {
+        cachedSdkModule = await import('@openai/codex-sdk');
+        cachedSdkLoadError = null;
+        return cachedSdkModule;
+    } catch (err) {
+        cachedSdkLoadError = err?.message || String(err);
+        return null;
+    }
+}
+
+function normalizeProviderKind(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (!normalized || normalized === 'auto' || normalized === 'sdk') {
+        return '';
+    }
+
+    if (normalized === 'typescriptsdk' || normalized === 'typescript-sdk' || normalized === 'type_script_sdk') {
+        return PROVIDER_KIND.typeScriptSdk;
+    }
+
+    if (normalized === 'legacyexec' || normalized === 'legacy-exec' || normalized === 'exec') {
+        return PROVIDER_KIND.legacyExec;
+    }
+
+    if (normalized === 'appserverjsonrpc' || normalized === 'app-server-json-rpc') {
+        return PROVIDER_KIND.appServerJsonRpc;
+    }
+
+    return '';
+}
+
+function resolveUserCodexHome() {
+    const configured = String(process.env.CODEX_HOME || '').trim();
+    return path.resolve(configured || path.join(os.homedir(), '.codex'));
+}
+
+export function resolveCodexRuntimeHome() {
+    const configured = String(process.env[CODEX_RUNTIME_HOME_ENV] || '').trim();
+    return path.resolve(configured || resolveUserCodexHome());
+}
+
+function usesExplicitIsolatedCodexHome() {
+    return String(process.env[CODEX_RUNTIME_HOME_ENV] || '').trim().length > 0;
+}
+
+function buildCodexSdkConfigOverrides(additional = {}) {
+    return {
+        mcp_servers: {},
+        ...additional
+    };
+}
+
+export async function ensureCodexRuntimeHome() {
+    const runtimeHome = resolveCodexRuntimeHome();
+    await fs.mkdir(runtimeHome, { recursive: true });
+    await fs.mkdir(path.join(runtimeHome, 'sessions'), { recursive: true });
+    await fs.mkdir(path.join(runtimeHome, 'generated_images'), { recursive: true });
+
+    if (!usesExplicitIsolatedCodexHome()) {
+        return runtimeHome;
+    }
+
+    const configPath = path.join(runtimeHome, 'config.toml');
+    let shouldWriteConfig = true;
+    try {
+        const existing = await fs.readFile(configPath, 'utf8');
+        shouldWriteConfig = existing.trim().length === 0 || existing.includes(CODEX_RUNTIME_CONFIG_MARKER);
+    } catch {
+        shouldWriteConfig = true;
+    }
+
+    if (shouldWriteConfig) {
+        await fs.writeFile(
+            configPath,
+            `${CODEX_RUNTIME_CONFIG_MARKER}\n# User MCP server definitions are intentionally not inherited here.\n# LocalBridge passes model, sandbox, and reasoning options per run.\n`,
+            'utf8'
+        );
+    }
+
+    return runtimeHome;
+}
+
+export function buildCodexChildEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+
+    env.CODEX_HOME = resolveCodexRuntimeHome();
+    if (usesExplicitIsolatedCodexHome()) {
+        env.MINDEXEC_CODEX_ISOLATED_HOME = '1';
+    } else {
+        delete env.MINDEXEC_CODEX_ISOLATED_HOME;
+    }
+    return env;
+}
+
+function resolveBundledCodexExecutable(packageRoot) {
+    const target = CODEX_TARGET_BY_PLATFORM[`${process.platform}:${process.arch}`];
+    if (!target) {
+        throw new Error(`Unsupported Codex login platform: ${process.platform} (${process.arch}).`);
+    }
+
+    return path.join(
+        packageRoot,
+        'node_modules',
+        ...target.packageName.split('/'),
+        'vendor',
+        target.targetTriple,
+        'bin',
+        target.binaryName);
+}
+
+function runBundledCodexCommand(packageRoot, args, timeoutMs = CODEX_LOGIN_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        let executablePath;
+        try {
+            executablePath = resolveBundledCodexExecutable(packageRoot);
+        } catch (err) {
+            resolve({ success: false, exitCode: -1, stdout: '', stderr: '', error: err?.message || String(err) });
+            return;
+        }
+
+        const child = spawn(executablePath, args, {
+            env: buildCodexChildEnv(),
+            windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe']
+        });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        let timeout = null;
+
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            resolve({
+                success: result.exitCode === 0,
+                exitCode: result.exitCode,
+                stdout: truncateLog(stdout),
+                stderr: truncateLog(stderr),
+                error: result.error || ''
+            });
+        };
+
+        child.stdout?.on('data', chunk => {
+            stdout = truncateLog(`${stdout}${chunk}`, MAX_LOG_CHARS);
+        });
+        child.stderr?.on('data', chunk => {
+            stderr = truncateLog(`${stderr}${chunk}`, MAX_LOG_CHARS);
+        });
+        child.once('error', err => finish({ exitCode: -1, error: err?.message || String(err) }));
+        child.once('exit', code => finish({ exitCode: Number.isFinite(Number(code)) ? Number(code) : -1 }));
+
+        timeout = setTimeout(() => {
+            try {
+                child.kill();
+            } catch {
+                // Ignore a process that already exited while the timeout fired.
+            }
+            finish({ exitCode: -1, error: 'Codex browser login timed out.' });
+        }, timeoutMs);
+    });
+}
+
+function normalizeReasoningEffort(value) {
+    const normalized = String(value || '').trim().toLowerCase();
+    return ['minimal', 'low', 'medium', 'high', 'xhigh'].includes(normalized)
+        ? normalized
+        : 'medium';
+}
+
+function inferSandboxFromIntent(intent, prompt) {
+    const text = `${intent || ''}\n${prompt || ''}`.toLowerCase();
+    if (/(full[_ -]?access|unrestricted|danger[_ -]?full)/.test(text)) {
+        return 'workspace-write';
+    }
+
+    if (/(code[-_\s]?edit|project[-_\s]?fix|generate[-_\s]?files|implement|modify files|write files|patch|apply fix|refactor)/.test(text)) {
+        return 'workspace-write';
+    }
+
+    if (/(research|review|analy[sz]e|summari[sz]e|diagnose|inspect|audit|compare|read[-_\s]?only)/.test(text)) {
+        return 'read-only';
+    }
+
+    return 'workspace-write';
+}
+
+function normalizeSandbox(value, intent, prompt) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (normalized && SDK_SANDBOX_BY_API_VALUE[normalized]) {
+        return SDK_SANDBOX_BY_API_VALUE[normalized];
+    }
+
+    return inferSandboxFromIntent(intent, prompt);
+}
+
+function normalizeApprovalPolicy(value, sandboxMode) {
+    const normalized = String(value || '').trim().toLowerCase();
+    if (['on-request', 'on-failure', 'untrusted'].includes(normalized)) {
+        return normalized;
+    }
+
+    if (normalized === 'never' && sandboxMode !== 'danger-full-access') {
+        return 'on-request';
+    }
+
+    return 'on-request';
+}
+
+function normalizeOutputSchema(value) {
+    if (value == null) {
+        return undefined;
+    }
+
+    if (typeof value === 'object') {
+        return value;
+    }
+
+    const text = String(value || '').trim();
+    if (!text) {
+        return undefined;
+    }
+
+    return JSON.parse(text);
+}
+
+function truncateLog(value, maxChars = MAX_LOG_CHARS) {
+    const text = String(value ?? '');
+    if (text.length <= maxChars) {
+        return text;
+    }
+
+    return `${text.slice(0, maxChars)}...`;
+}
+
+function makeEmptyResult(overrides = {}) {
+    const now = new Date().toISOString();
+    return {
+        success: false,
+        providerKind: PROVIDER_KIND.unavailable,
+        threadId: '',
+        turnId: '',
+        finalResponse: '',
+        summary: '',
+        error: '',
+        status: 'failed',
+        startedAtUtc: now,
+        completedAtUtc: now,
+        sandboxMode: '',
+        changedFiles: [],
+        commandLogs: [],
+        approvalEvents: [],
+        toolEvents: [],
+        rawEventCount: 0,
+        ...overrides
+    };
+}
+
+function upsertToolEvent(result, event) {
+    const id = String(event?.id || '').trim();
+    const type = String(event?.type || '').trim();
+    const name = String(event?.name || '').trim();
+    const key = id || `${type}:${name}`;
+    const index = result.toolEvents.findIndex(existing =>
+        (String(existing?.id || '').trim() || `${existing?.type || ''}:${existing?.name || ''}`) === key);
+    if (index >= 0) {
+        result.toolEvents[index] = event;
+        return;
+    }
+
+    result.toolEvents.push(event);
+}
+
+function collectItem(result, item, eventType = '') {
+    if (!item || typeof item !== 'object') {
+        return;
+    }
+
+    if (item.type === 'agent_message' && typeof item.text === 'string') {
+        result.finalResponse = item.text;
+        return;
+    }
+
+    if (item.type === 'reasoning' && typeof item.text === 'string') {
+        result.summary = result.summary
+            ? `${result.summary}\n${item.text}`.trim()
+            : item.text.trim();
+        return;
+    }
+
+    if (item.type === 'file_change' && Array.isArray(item.changes)) {
+        for (const change of item.changes) {
+            const changePath = String(change?.path || '').trim();
+            if (!changePath) {
+                continue;
+            }
+
+            if (!result.changedFiles.some(existing => existing.path === changePath)) {
+                result.changedFiles.push({
+                    path: changePath,
+                    kind: String(change?.kind || '').trim(),
+                    status: String(item.status || '').trim()
+                });
+            }
+        }
+        return;
+    }
+
+    if (item.type === 'command_execution') {
+        result.commandLogs.push({
+            id: String(item.id || ''),
+            command: String(item.command || ''),
+            status: String(item.status || ''),
+            exitCode: Number.isFinite(Number(item.exit_code)) ? Number(item.exit_code) : null,
+            output: truncateLog(item.aggregated_output)
+        });
+        upsertToolEvent(result, {
+            id: String(item.id || ''),
+            type: 'command_execution',
+            name: String(item.command || '').trim() || 'Shell',
+            status: String(item.status || eventType || ''),
+            summary: truncateLog(item.aggregated_output, 1200)
+        });
+        return;
+    }
+
+    if (item.type === 'web_search') {
+        upsertToolEvent(result, {
+            id: String(item.id || ''),
+            type: 'web_search',
+            name: 'WebSearch',
+            status: eventType === 'item.completed' ? 'completed' : 'running',
+            summary: truncateLog(item.query, 1200)
+        });
+        return;
+    }
+
+    if (item.type === 'mcp_tool_call') {
+        const server = String(item.server || '').trim();
+        const tool = String(item.tool || '').trim();
+        upsertToolEvent(result, {
+            id: String(item.id || ''),
+            type: 'mcp_tool_call',
+            name: [server, tool].filter(Boolean).join('.') || 'MCP',
+            status: String(item.status || eventType || ''),
+            summary: item.error?.message
+                ? truncateLog(item.error.message, 1200)
+                : truncateLog(JSON.stringify(item.arguments ?? {}), 1200)
+        });
+        return;
+    }
+
+    if (item.type === 'todo_list') {
+        const items = Array.isArray(item.items) ? item.items : [];
+        upsertToolEvent(result, {
+            id: String(item.id || ''),
+            type: 'todo_list',
+            name: 'Plan',
+            status: eventType === 'item.completed' ? 'completed' : 'running',
+            summary: truncateLog(items.map(entry => `${entry?.completed ? '[x]' : '[ ]'} ${entry?.text || ''}`).join('\n'), 1200)
+        });
+        return;
+    }
+
+    if (String(item.type || '').toLowerCase().includes('approval')) {
+        result.approvalEvents.push({
+            id: String(item.id || ''),
+            type: String(item.type || ''),
+            status: String(item.status || ''),
+            summary: truncateLog(JSON.stringify(item), 1200)
+        });
+    }
+}
+
+function extractLegacyEvents(stdout, stderr) {
+    const result = {
+        finalResponse: '',
+        summary: '',
+        error: '',
+        threadId: '',
+        changedFiles: [],
+        commandLogs: [],
+        approvalEvents: [],
+        rawEventCount: 0
+    };
+
+    const lines = String(stdout || '')
+        .replace(/\r\n/g, '\n')
+        .replace(/\r/g, '\n')
+        .split('\n')
+        .filter(line => line.trim().length > 0);
+
+    for (const line of lines) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        } catch {
+            continue;
+        }
+
+        result.rawEventCount += 1;
+        if (event.type === 'thread.started' && event.thread_id) {
+            result.threadId = String(event.thread_id);
+        }
+
+        if (event.type === 'turn.failed' && event.error?.message) {
+            result.error = String(event.error.message);
+        }
+
+        if (event.type === 'error' && event.message) {
+            result.error = String(event.message);
+        }
+
+        const item = event.item;
+        if (item?.type === 'agent_message' && typeof item.text === 'string') {
+            result.finalResponse = item.text;
+        } else if (item?.type === 'reasoning' && typeof item.text === 'string') {
+            result.summary = result.summary
+                ? `${result.summary}\n${item.text}`.trim()
+                : item.text.trim();
+        } else if (item?.type === 'file_change' && Array.isArray(item.changes)) {
+            for (const change of item.changes) {
+                const changePath = String(change?.path || '').trim();
+                if (changePath) {
+                    result.changedFiles.push({
+                        path: changePath,
+                        kind: String(change?.kind || ''),
+                        status: String(item.status || '')
+                    });
+                }
+            }
+        } else if (item?.type === 'command_execution') {
+            result.commandLogs.push({
+                id: String(item.id || ''),
+                command: String(item.command || ''),
+                status: String(item.status || ''),
+                exitCode: Number.isFinite(Number(item.exit_code)) ? Number(item.exit_code) : null,
+                output: truncateLog(item.aggregated_output)
+            });
+        }
+    }
+
+    if (!result.finalResponse && lines.length > 0) {
+        result.finalResponse = String(stdout || '').trim();
+    }
+
+    if (!result.error && stderr) {
+        result.error = String(stderr).trim();
+    }
+
+    return result;
+}
+
+function buildThreadOptions(body, workingDirectory) {
+    const prompt = String(body?.instruction || body?.prompt || '').trim();
+    const sandboxMode = normalizeSandbox(body?.sandbox || body?.sandboxMode, body?.intent || body?.nodeKind, prompt);
+    const approvalPolicy = normalizeApprovalPolicy(body?.approvalPolicy, sandboxMode);
+    const options = {
+        workingDirectory,
+        skipGitRepoCheck: true,
+        sandboxMode,
+        modelReasoningEffort: normalizeReasoningEffort(body?.reasoningEffort),
+        approvalPolicy
+    };
+
+    const model = String(body?.model || '').trim();
+    if (model) {
+        options.model = model;
+    }
+
+    if (body?.networkAccessEnabled !== undefined) {
+        options.networkAccessEnabled = Boolean(body.networkAccessEnabled);
+    }
+
+    const webSearchMode = String(body?.webSearchMode || '').trim().toLowerCase();
+    if (['disabled', 'cached', 'live'].includes(webSearchMode)) {
+        options.webSearchMode = webSearchMode;
+    }
+
+    return options;
+}
+
+function serializeThreadOptionsForStatus(options) {
+    return {
+        model: options?.model || null,
+        sandboxMode: API_SANDBOX_BY_SDK_VALUE[options?.sandboxMode] || options?.sandboxMode || null,
+        reasoningEffort: options?.modelReasoningEffort || null,
+        approvalPolicy: options?.approvalPolicy || null,
+        networkAccessEnabled: options?.networkAccessEnabled ?? null,
+        webSearchMode: options?.webSearchMode || null,
+        workingDirectory: options?.workingDirectory || null
+    };
+}
+
+async function checkSdkAvailability(packageRoot, sdkLoader = loadCodexSdk) {
+    const sdk = await sdkLoader();
+    return {
+        kind: PROVIDER_KIND.typeScriptSdk,
+        available: Boolean(sdk?.Codex),
+        version: safeReadPackageVersion(packageRoot, '@openai/codex-sdk'),
+        error: sdk?.Codex ? null : (cachedSdkLoadError || 'Codex SDK module did not export Codex.')
+    };
+}
+
+async function checkLegacyAvailability() {
+    const now = Date.now();
+    if (cachedLegacyAvailability && cachedLegacyAvailabilityExpiresAt > now) {
+        return cachedLegacyAvailability;
+    }
+
+    try {
+        const { stdout, stderr } = await execAsync('codex --version', {
+            timeout: 6000,
+            windowsHide: true,
+            maxBuffer: 512 * 1024
+        });
+        cachedLegacyAvailability = {
+            kind: PROVIDER_KIND.legacyExec,
+            available: true,
+            version: String(stdout || stderr || '').trim(),
+            error: null
+        };
+    } catch (err) {
+        cachedLegacyAvailability = {
+            kind: PROVIDER_KIND.legacyExec,
+            available: false,
+            version: null,
+            error: err?.message || String(err)
+        };
+    }
+
+    cachedLegacyAvailabilityExpiresAt = now + 30 * 1000;
+    return cachedLegacyAvailability;
+}
+
+function extractPrompt(body) {
+    const prompt = String(body?.instruction || body?.prompt || '').trim();
+    if (!prompt) {
+        const err = new Error('Codex prompt is required.');
+        err.statusCode = 400;
+        throw err;
+    }
+
+    return prompt;
+}
+
+function looksLikeCodexAuthenticationError(value) {
+    const text = String(value || '').toLowerCase();
+    return text.includes('invalid_refresh_token')
+        || text.includes('invalid refresh token')
+        || text.includes('login required')
+        || text.includes('not logged in')
+        || text.includes('please log out and sign in again')
+        || text.includes('could not parse your authentication token')
+        || text.includes('authrequired')
+        || text.includes('401 unauthorized');
+}
+
+function normalizeImageMimeType(value, fallback = 'image/png') {
+    const normalized = String(value || '').trim().toLowerCase();
+    return /^image\/[a-z0-9.+-]+$/.test(normalized) ? normalized : fallback;
+}
+
+function inferImageMimeType(buffer, fallback = 'image/png') {
+    if (!Buffer.isBuffer(buffer) || buffer.length < 4) {
+        return fallback;
+    }
+
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+        return 'image/png';
+    }
+    if (buffer[0] === 0xff && buffer[1] === 0xd8) {
+        return 'image/jpeg';
+    }
+    if (buffer.slice(0, 3).toString('ascii') === 'GIF') {
+        return 'image/gif';
+    }
+    if (buffer.length >= 12
+        && buffer.slice(0, 4).toString('ascii') === 'RIFF'
+        && buffer.slice(8, 12).toString('ascii') === 'WEBP') {
+        return 'image/webp';
+    }
+
+    return fallback;
+}
+
+function normalizeGeneratedImageBase64(value, hintedMimeType = '') {
+    const text = String(value || '').trim();
+    if (!text) {
+        return null;
+    }
+
+    const dataUrlMatch = text.match(/^data:(image\/[a-z0-9.+-]+);base64,([a-z0-9+/=\r\n]+)$/i);
+    const base64 = (dataUrlMatch ? dataUrlMatch[2] : text).replace(/\s+/g, '');
+    if (base64.length < 32 || !/^[a-z0-9+/]+={0,2}$/i.test(base64)) {
+        return null;
+    }
+
+    try {
+        const bytes = Buffer.from(base64, 'base64');
+        if (!bytes.length || bytes.length > MAX_GENERATED_IMAGE_BYTES) {
+            return null;
+        }
+        const mimeType = inferImageMimeType(
+            bytes,
+            normalizeImageMimeType(dataUrlMatch?.[1] || hintedMimeType));
+        return { imageBase64: bytes.toString('base64'), mimeType };
+    } catch {
+        return null;
+    }
+}
+
+function extractGeneratedImageFromEvent(value, depth = 0, hintedMimeType = '') {
+    if (value == null || depth > 10) {
+        return null;
+    }
+
+    if (typeof value === 'string') {
+        return value.startsWith('data:image/')
+            ? normalizeGeneratedImageBase64(value, hintedMimeType)
+            : null;
+    }
+
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const found = extractGeneratedImageFromEvent(entry, depth + 1, hintedMimeType);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    }
+
+    if (typeof value !== 'object') {
+        return null;
+    }
+
+    const localMimeType = normalizeImageMimeType(
+        value.mime_type || value.mimeType || value.content_type || value.contentType,
+        hintedMimeType || 'image/png');
+    for (const key of ['b64_json', 'image_base64', 'imageBase64', 'base64']) {
+        if (typeof value[key] === 'string') {
+            const found = normalizeGeneratedImageBase64(value[key], localMimeType);
+            if (found) {
+                return found;
+            }
+        }
+    }
+
+    for (const key of ['result', 'output', 'image', 'images', 'data', 'payload', 'item']) {
+        if (value[key] != null) {
+            const found = extractGeneratedImageFromEvent(value[key], depth + 1, localMimeType);
+            if (found) {
+                return found;
+            }
+        }
+    }
+
+    return null;
+}
+
+function imageExtensionForReference(reference) {
+    const fileNameExtension = path.extname(String(reference?.fileName || '')).toLowerCase();
+    if (['.png', '.jpg', '.jpeg', '.webp', '.gif'].includes(fileNameExtension)) {
+        return fileNameExtension === '.jpeg' ? '.jpg' : fileNameExtension;
+    }
+
+    const mimeType = normalizeImageMimeType(reference?.mimeType);
+    if (mimeType === 'image/jpeg') return '.jpg';
+    if (mimeType === 'image/webp') return '.webp';
+    if (mimeType === 'image/gif') return '.gif';
+    return '.png';
+}
+
+async function writeSdkImageReferences(runtimeHome, references) {
+    const normalized = Array.isArray(references)
+        ? references.slice(0, MAX_IMAGE_REFERENCE_COUNT)
+        : [];
+    if (!normalized.length) {
+        return { directory: '', paths: [] };
+    }
+
+    const root = path.join(runtimeHome, 'image-inputs');
+    const directory = path.join(root, crypto.randomUUID());
+    await fs.mkdir(directory, { recursive: true });
+    const paths = [];
+    let totalBytes = 0;
+
+    try {
+        for (let index = 0; index < normalized.length; index += 1) {
+            const reference = normalized[index];
+            const bytes = Buffer.from(String(reference?.base64 || ''), 'base64');
+            totalBytes += bytes.length;
+            if (!bytes.length || totalBytes > MAX_IMAGE_REFERENCE_BYTES) {
+                throw new Error('Codex SDK image references are empty or exceed the 40 MB request limit.');
+            }
+
+            const filePath = path.join(directory, `reference-${index + 1}${imageExtensionForReference(reference)}`);
+            await fs.writeFile(filePath, bytes);
+            paths.push(filePath);
+        }
+
+        return { directory, paths };
+    } catch (err) {
+        await fs.rm(directory, { recursive: true, force: true }).catch(() => {});
+        throw err;
+    }
+}
+
+async function cleanupSdkImageReferences(runtimeHome, directory) {
+    if (!directory) {
+        return;
+    }
+
+    const root = path.resolve(runtimeHome, 'image-inputs');
+    const target = path.resolve(directory);
+    if (!target.startsWith(`${root}${path.sep}`)) {
+        return;
+    }
+    await fs.rm(target, { recursive: true, force: true }).catch(() => {});
+}
+
+function buildSdkImagePrompt(body, referenceCount) {
+    const prompt = extractPrompt(body);
+    const action = String(body?.action || '').trim().toLowerCase() === 'edit' || referenceCount > 0
+        ? 'edit'
+        : 'generate';
+    const size = String(body?.size || '').trim();
+    const quality = String(body?.quality || '').trim();
+    return [
+        action === 'edit'
+            ? `Use the image generation tool to edit the ${referenceCount} attached reference image(s).`
+            : 'Use the image generation tool to create one new image.',
+        prompt,
+        size ? `Requested output size: ${size}.` : '',
+        quality ? `Requested quality: ${quality}.` : '',
+        'Return exactly one generated image. Do not answer with instructions or prose.'
+    ].filter(Boolean).join('\n\n');
+}
+
+async function listGeneratedImageCandidates(directory, minimumMtimeMs, depth = 0) {
+    if (depth > 4) {
+        return [];
+    }
+
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    const candidates = [];
+    for (const entry of entries) {
+        const fullPath = path.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            candidates.push(...await listGeneratedImageCandidates(fullPath, minimumMtimeMs, depth + 1));
+            continue;
+        }
+        if (!entry.isFile() || !/\.(png|jpe?g|webp|gif)$/i.test(entry.name)) {
+            continue;
+        }
+
+        const stat = await fs.stat(fullPath).catch(() => null);
+        if (stat && stat.size > 0 && stat.size <= MAX_GENERATED_IMAGE_BYTES && stat.mtimeMs >= minimumMtimeMs) {
+            candidates.push({ fullPath, mtimeMs: stat.mtimeMs });
+        }
+    }
+    return candidates;
+}
+
+async function recoverSdkGeneratedImage(runtimeHome, startedAtMs) {
+    const generatedRoot = path.join(runtimeHome, 'generated_images');
+    const minimumMtimeMs = startedAtMs - 15 * 1000;
+    for (let attempt = 0; attempt < 8; attempt += 1) {
+        const candidates = await listGeneratedImageCandidates(generatedRoot, minimumMtimeMs);
+        candidates.sort((left, right) => right.mtimeMs - left.mtimeMs);
+        if (candidates[0]) {
+            const bytes = await fs.readFile(candidates[0].fullPath);
+            return {
+                imageBase64: bytes.toString('base64'),
+                mimeType: inferImageMimeType(bytes)
+            };
+        }
+        await new Promise(resolve => setTimeout(resolve, 350));
+    }
+    return null;
+}
+
+export function createCodexRuntime(options) {
+    const packageRoot = options.packageRoot;
+    const resolveWorkingDirectory = options.resolveWorkingDirectory;
+    const getCurrentRuntime = options.getCurrentRuntime;
+    const getModelCatalog = options.getModelCatalog;
+    const log = typeof options.log === 'function' ? options.log : () => {};
+    const sdkLoader = typeof options.loadCodexSdk === 'function' ? options.loadCodexSdk : loadCodexSdk;
+    const prepareRuntimeHome = typeof options.ensureCodexRuntimeHome === 'function'
+        ? options.ensureCodexRuntimeHome
+        : ensureCodexRuntimeHome;
+    const childEnvFactory = typeof options.buildCodexChildEnv === 'function'
+        ? options.buildCodexChildEnv
+        : buildCodexChildEnv;
+
+    const threads = new Map();
+    const activeTurns = new Map();
+    let activeLoginPromise = null;
+
+    async function loginWithBundledCodex() {
+        if (typeof options.loginCodex === 'function') {
+            return options.loginCodex();
+        }
+
+        if (activeLoginPromise) {
+            return activeLoginPromise;
+        }
+
+        activeLoginPromise = (async () => {
+            await prepareRuntimeHome();
+            await runBundledCodexCommand(packageRoot, ['logout'], 15000).catch(() => null);
+            log('Codex SDK browser login start', { runtimeHome: resolveCodexRuntimeHome() });
+            const loginResult = await runBundledCodexCommand(packageRoot, ['login']);
+            log('Codex SDK browser login finish', {
+                success: loginResult.success,
+                exitCode: loginResult.exitCode,
+                error: loginResult.error || ''
+            });
+            return loginResult;
+        })().finally(() => {
+            activeLoginPromise = null;
+        });
+
+        return activeLoginPromise;
+    }
+
+    async function getCapabilities(options = {}) {
+        const [sdk, legacy, modelCatalog] = await Promise.all([
+            checkSdkAvailability(packageRoot, sdkLoader),
+            checkLegacyAvailability(),
+            getModelCatalog({ forceRefresh: Boolean(options.forceRefresh) })
+        ]);
+        const preferredProviderKind = sdk.available
+            ? PROVIDER_KIND.typeScriptSdk
+            : legacy.available
+                ? PROVIDER_KIND.legacyExec
+                : PROVIDER_KIND.unavailable;
+
+        return {
+            success: preferredProviderKind !== PROVIDER_KIND.unavailable,
+            preferredProviderKind,
+            providers: [
+                sdk,
+                {
+                    kind: PROVIDER_KIND.appServerJsonRpc,
+                    available: false,
+                    implemented: false,
+                    error: 'DTO scaffold only. Use TypeScriptSdk for LocalBridge execution.'
+                },
+                legacy
+            ],
+            sandboxModes: ['read_only', 'workspace_write', 'full_access'],
+            endpoints: [
+                'GET /api/codex/capabilities',
+                'POST /api/codex/thread/start',
+                'POST /api/codex/thread/run',
+                'POST /api/codex/thread/resume',
+                'POST /api/codex/thread/cancel',
+                'POST /api/codex/image/run',
+                'GET /api/codex/thread/{threadId}/status'
+            ],
+            runtime: getCurrentRuntime(),
+            models: modelCatalog.models || [],
+            modelCatalogSource: modelCatalog.source,
+            modelCatalogCommandSource: modelCatalog.commandSource || null,
+            modelCatalogUpdatedAt: modelCatalog.updatedAt,
+            modelCatalogRefreshAttemptedAt: modelCatalog.refreshAttemptedAt || null,
+            modelCatalogStale: modelCatalog.stale === true,
+            modelCatalogError: modelCatalog.error || null
+        };
+    }
+
+    async function resolveProvider(requestedProviderKind) {
+        const requested = normalizeProviderKind(requestedProviderKind);
+        const sdk = await checkSdkAvailability(packageRoot, sdkLoader);
+        const legacy = requested === PROVIDER_KIND.typeScriptSdk
+            ? null
+            : await checkLegacyAvailability();
+
+        if ((!requested || requested === PROVIDER_KIND.typeScriptSdk) && sdk.available) {
+            return PROVIDER_KIND.typeScriptSdk;
+        }
+
+        if ((!requested || requested === PROVIDER_KIND.legacyExec) && legacy?.available) {
+            return PROVIDER_KIND.legacyExec;
+        }
+
+        return PROVIDER_KIND.unavailable;
+    }
+
+    async function startThread(body = {}) {
+        const providerKind = await resolveProvider(body.providerKind || body.runtime);
+        const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
+        const threadOptions = buildThreadOptions(body, workingDirectory);
+        const now = new Date().toISOString();
+
+        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
+            const sdk = await sdkLoader();
+            await prepareRuntimeHome();
+            const codex = new sdk.Codex({
+                env: childEnvFactory(),
+                config: buildCodexSdkConfigOverrides()
+            });
+            const thread = codex.startThread(threadOptions);
+            const localThreadId = `local_${crypto.randomUUID()}`;
+            threads.set(localThreadId, {
+                providerKind,
+                thread,
+                createdAtUtc: now,
+                updatedAtUtc: now,
+                options: threadOptions,
+                officialThreadId: null,
+                lastStatus: 'created'
+            });
+
+            return makeEmptyResult({
+                success: true,
+                providerKind,
+                threadId: localThreadId,
+                status: 'created',
+                startedAtUtc: now,
+                completedAtUtc: now,
+                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
+            });
+        }
+
+        if (providerKind === PROVIDER_KIND.legacyExec) {
+            const localThreadId = `legacy_${crypto.randomUUID()}`;
+            threads.set(localThreadId, {
+                providerKind,
+                createdAtUtc: now,
+                updatedAtUtc: now,
+                options: threadOptions,
+                officialThreadId: localThreadId,
+                lastStatus: 'created'
+            });
+
+            return makeEmptyResult({
+                success: true,
+                providerKind,
+                threadId: localThreadId,
+                status: 'created',
+                startedAtUtc: now,
+                completedAtUtc: now,
+                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
+            });
+        }
+
+        return makeEmptyResult({
+            providerKind,
+            error: 'Codex local runtime is not available. Install LocalBridge dependencies or Codex CLI, then run codex login.'
+        });
+    }
+
+    async function getSdkThread(body, threadOptions) {
+        const requestedThreadId = String(body?.threadId || '').trim();
+        if (requestedThreadId && threads.has(requestedThreadId)) {
+            return {
+                key: requestedThreadId,
+                record: threads.get(requestedThreadId)
+            };
+        }
+
+        const sdk = await sdkLoader();
+        await prepareRuntimeHome();
+        const codex = new sdk.Codex({
+            env: childEnvFactory(),
+            config: buildCodexSdkConfigOverrides()
+        });
+        const officialId = requestedThreadId && !requestedThreadId.startsWith('local_')
+            ? requestedThreadId
+            : '';
+        const thread = officialId
+            ? codex.resumeThread(officialId, threadOptions)
+            : codex.startThread(threadOptions);
+        const key = officialId || `local_${crypto.randomUUID()}`;
+        const record = {
+            providerKind: PROVIDER_KIND.typeScriptSdk,
+            thread,
+            createdAtUtc: new Date().toISOString(),
+            updatedAtUtc: new Date().toISOString(),
+            options: threadOptions,
+            officialThreadId: officialId || null,
+            lastStatus: 'created'
+        };
+        threads.set(key, record);
+        return { key, record };
+    }
+
+    async function runSdkThread(body, workingDirectory, prompt, startedAtUtc) {
+        const threadOptions = buildThreadOptions(body, workingDirectory);
+        const { key, record } = await getSdkThread(body, threadOptions);
+        const turnId = `turn_${crypto.randomUUID()}`;
+        const abortController = new AbortController();
+        const activeKey = `${key}:${turnId}`;
+        activeTurns.set(activeKey, {
+            providerKind: PROVIDER_KIND.typeScriptSdk,
+            threadId: key,
+            turnId,
+            abortController,
+            startedAtUtc
+        });
+
+        const result = makeEmptyResult({
+            providerKind: PROVIDER_KIND.typeScriptSdk,
+            threadId: record.officialThreadId || key,
+            turnId,
+            status: 'running',
+            startedAtUtc,
+            completedAtUtc: '',
+            sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
+        });
+        let timeout = null;
+
+        try {
+            timeout = setTimeout(() => {
+                try {
+                    abortController.abort();
+                } catch {
+                    // Ignore duplicate aborts.
+                }
+            }, DEFAULT_TIMEOUT_MS);
+
+            log('Codex SDK run start', {
+                threadId: result.threadId,
+                turnId,
+                sandbox: result.sandboxMode,
+                cwd: workingDirectory
+            });
+
+            const outputSchema = normalizeOutputSchema(body.outputSchema || body.outputSchemaJson);
+            const { events } = await record.thread.runStreamed(prompt, {
+                outputSchema,
+                signal: abortController.signal
+            });
+
+            for await (const event of events) {
+                result.rawEventCount += 1;
+                if (result.rawEventCount <= MAX_EVENT_LOG) {
+                    record.lastEvent = event;
+                }
+
+                if (event.type === 'thread.started' && event.thread_id) {
+                    record.officialThreadId = String(event.thread_id);
+                    result.threadId = record.officialThreadId;
+                    threads.set(record.officialThreadId, record);
+                } else if (event.type === 'item.completed' || event.type === 'item.updated' || event.type === 'item.started') {
+                    collectItem(result, event.item, event.type);
+                } else if (event.type === 'turn.failed') {
+                    result.error = event.error?.message || 'Codex turn failed.';
+                    result.status = 'failed';
+                } else if (event.type === 'error') {
+                    result.error = event.message || 'Codex stream failed.';
+                    result.status = 'failed';
+                } else if (event.type === 'turn.completed') {
+                    result.status = 'completed';
+                }
+            }
+
+            if (!result.error && result.status !== 'failed') {
+                result.success = true;
+                result.status = result.status === 'running' ? 'completed' : result.status;
+            }
+
+            if (!result.finalResponse && result.success) {
+                result.finalResponse = result.summary;
+            }
+
+            if (!result.finalResponse && !result.error) {
+                result.error = 'Codex returned an empty response.';
+                result.status = 'failed';
+                result.success = false;
+            }
+        } catch (err) {
+            const aborted = abortController.signal.aborted;
+            result.error = aborted ? 'Codex turn was cancelled.' : (err?.message || String(err));
+            result.status = aborted ? 'cancelled' : 'failed';
+            result.success = false;
+        } finally {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            result.completedAtUtc = new Date().toISOString();
+            record.updatedAtUtc = result.completedAtUtc;
+            record.lastStatus = result.status;
+            record.lastResult = result;
+            activeTurns.delete(activeKey);
+        }
+
+        return result;
+    }
+
+    async function runLegacyExec(body, workingDirectory, prompt, startedAtUtc) {
+        const threadOptions = buildThreadOptions(body, workingDirectory);
+        const turnId = `turn_${crypto.randomUUID()}`;
+        const threadId = String(body.threadId || `legacy_${crypto.randomUUID()}`);
+        const abortController = new AbortController();
+        const activeKey = `${threadId}:${turnId}`;
+        activeTurns.set(activeKey, {
+            providerKind: PROVIDER_KIND.legacyExec,
+            threadId,
+            turnId,
+            abortController,
+            startedAtUtc
+        });
+
+        const tempDir = path.join(workingDirectory, TEMP_DIR);
+        const schema = normalizeOutputSchema(body.outputSchema || body.outputSchemaJson);
+        let schemaPath = null;
+        await prepareRuntimeHome();
+        const args = [
+            'exec',
+            '-',
+            '--skip-git-repo-check',
+            '--json',
+            '--disable',
+            'plugins',
+            '--disable',
+            'shell_snapshot',
+            '-s',
+            threadOptions.sandboxMode,
+            '--config',
+            `model_reasoning_effort=${threadOptions.modelReasoningEffort}`,
+            '--config',
+            'mcp_servers={}'
+        ];
+        if (threadOptions.model) {
+            args.push('-m', threadOptions.model);
+        }
+
+        if (schema) {
+            await fs.mkdir(tempDir, { recursive: true });
+            schemaPath = path.join(tempDir, `${crypto.randomUUID()}.schema.json`);
+            await fs.writeFile(schemaPath, JSON.stringify(schema), 'utf8');
+            args.push('--output-schema', schemaPath);
+        }
+
+        const result = makeEmptyResult({
+            providerKind: PROVIDER_KIND.legacyExec,
+            threadId,
+            turnId,
+            status: 'running',
+            startedAtUtc,
+            completedAtUtc: '',
+            sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
+        });
+
+        try {
+            const childResult = await new Promise((resolve) => {
+                const child = spawn('codex', args, {
+                    cwd: workingDirectory,
+                    env: childEnvFactory(),
+                    windowsHide: true,
+                    signal: abortController.signal
+                });
+                let stdout = '';
+                let stderr = '';
+                let settled = false;
+                const timeout = setTimeout(() => {
+                    try {
+                        abortController.abort();
+                    } catch {
+                        // Ignore duplicate aborts.
+                    }
+                    try {
+                        child.kill('SIGTERM');
+                    } catch {
+                        // Ignore if already exited.
+                    }
+                }, DEFAULT_TIMEOUT_MS);
+
+                const settle = (payload) => {
+                    if (settled) return;
+                    settled = true;
+                    clearTimeout(timeout);
+                    resolve(payload);
+                };
+
+                child.stdout?.on('data', chunk => {
+                    stdout += chunk.toString();
+                });
+                child.stderr?.on('data', chunk => {
+                    stderr += chunk.toString();
+                });
+                child.on('error', err => {
+                    settle({ exitCode: -1, stdout, stderr, error: err?.message || String(err) });
+                });
+                child.on('close', code => {
+                    settle({ exitCode: Number.isFinite(code) ? code : -1, stdout, stderr, error: '' });
+                });
+                child.stdin?.write(prompt);
+                child.stdin?.end();
+            });
+
+            const parsed = extractLegacyEvents(childResult.stdout, childResult.stderr);
+            result.threadId = parsed.threadId || threadId;
+            result.finalResponse = parsed.finalResponse;
+            result.summary = parsed.summary;
+            result.changedFiles = parsed.changedFiles;
+            result.commandLogs = parsed.commandLogs;
+            result.approvalEvents = parsed.approvalEvents;
+            result.rawEventCount = parsed.rawEventCount;
+            result.error = childResult.error || parsed.error;
+            result.success = childResult.exitCode === 0 && Boolean(result.finalResponse);
+            result.status = result.success ? 'completed' : 'failed';
+            if (!result.error && !result.success) {
+                result.error = parsed.error || 'Codex legacy exec returned an empty response.';
+            }
+        } catch (err) {
+            const aborted = abortController.signal.aborted;
+            result.error = aborted ? 'Codex turn was cancelled.' : (err?.message || String(err));
+            result.status = aborted ? 'cancelled' : 'failed';
+            result.success = false;
+        } finally {
+            result.completedAtUtc = new Date().toISOString();
+            activeTurns.delete(activeKey);
+            if (schemaPath) {
+                await fs.unlink(schemaPath).catch(() => {});
+            }
+            threads.set(result.threadId, {
+                providerKind: PROVIDER_KIND.legacyExec,
+                createdAtUtc: startedAtUtc,
+                updatedAtUtc: result.completedAtUtc,
+                options: threadOptions,
+                officialThreadId: result.threadId,
+                lastStatus: result.status,
+                lastResult: result
+            });
+        }
+
+        return result;
+    }
+
+    async function runThread(body = {}) {
+        const prompt = extractPrompt(body);
+        const startedAtUtc = new Date().toISOString();
+        const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
+        const providerKind = await resolveProvider(body.providerKind || body.runtime);
+
+        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
+            return runSdkThread(body, workingDirectory, prompt, startedAtUtc);
+        }
+
+        if (providerKind === PROVIDER_KIND.legacyExec) {
+            return runLegacyExec(body, workingDirectory, prompt, startedAtUtc);
+        }
+
+        return makeEmptyResult({
+            providerKind,
+            startedAtUtc,
+            completedAtUtc: new Date().toISOString(),
+            error: 'Codex local runtime is not available. TypeScript SDK and legacy codex exec are unavailable.'
+        });
+    }
+
+    async function runSdkImageOnce(body = {}) {
+        const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
+        const runtimeHome = await prepareRuntimeHome();
+        const sdk = await sdkLoader();
+        if (!sdk?.Codex) {
+            return {
+                success: false,
+                providerKind: PROVIDER_KIND.unavailable,
+                imageBase64: '',
+                mimeType: '',
+                error: cachedSdkLoadError || 'Codex TypeScript SDK is unavailable.',
+                threadId: '',
+                authenticationRequired: false,
+                loginOpened: false
+            };
+        }
+
+        const references = await writeSdkImageReferences(runtimeHome, body.referenceImages);
+        const prompt = buildSdkImagePrompt(body, references.paths.length);
+        const threadOptions = buildThreadOptions({
+            ...body,
+            sandbox: 'read_only',
+            approvalPolicy: 'on-request',
+            reasoningEffort: 'low',
+            networkAccessEnabled: true,
+            webSearchMode: 'disabled'
+        }, workingDirectory);
+        const startedAtMs = Date.now();
+        let threadId = '';
+        let error = '';
+        let generatedImage = null;
+
+        try {
+            const codex = new sdk.Codex({
+                env: childEnvFactory(),
+                config: buildCodexSdkConfigOverrides({
+                    features: { image_generation: true }
+                })
+            });
+            const thread = codex.startThread(threadOptions);
+            const input = [
+                { type: 'text', text: prompt },
+                ...references.paths.map(referencePath => ({ type: 'local_image', path: referencePath }))
+            ];
+            const { events } = await thread.runStreamed(input);
+
+            for await (const event of events) {
+                if (event?.type === 'thread.started' && event.thread_id) {
+                    threadId = String(event.thread_id);
+                } else if (event?.type === 'turn.failed') {
+                    error = event.error?.message || 'Codex SDK image turn failed.';
+                } else if (event?.type === 'error') {
+                    error = event.message || 'Codex SDK image stream failed.';
+                }
+
+                generatedImage ||= extractGeneratedImageFromEvent(event);
+            }
+        } catch (err) {
+            error = err?.message || String(err);
+        } finally {
+            await cleanupSdkImageReferences(runtimeHome, references.directory);
+        }
+
+        const authenticationRequired = looksLikeCodexAuthenticationError(error);
+        if (!authenticationRequired) {
+            generatedImage ||= await recoverSdkGeneratedImage(runtimeHome, startedAtMs);
+        }
+        if (generatedImage) {
+            return {
+                success: true,
+                providerKind: PROVIDER_KIND.typeScriptSdk,
+                imageBase64: generatedImage.imageBase64,
+                mimeType: generatedImage.mimeType,
+                error: '',
+                threadId,
+                authenticationRequired: false,
+                loginOpened: false
+            };
+        }
+
+        return {
+            success: false,
+            providerKind: PROVIDER_KIND.typeScriptSdk,
+            imageBase64: '',
+            mimeType: '',
+            error: error || 'Codex SDK completed without returning an image.',
+            threadId,
+            authenticationRequired,
+            loginOpened: false
+        };
+    }
+
+    async function runImage(body = {}) {
+        extractPrompt(body);
+        const firstResult = await runSdkImageOnce(body);
+        if (!firstResult.authenticationRequired) {
+            return firstResult;
+        }
+
+        const loginResult = await loginWithBundledCodex();
+        const loginSucceeded = loginResult === true || loginResult?.success === true;
+        if (!loginSucceeded) {
+            return {
+                ...firstResult,
+                loginOpened: true,
+                error: loginResult?.error
+                    || 'Codex sign-in was not completed. Finish the browser login and retry.'
+            };
+        }
+
+        const retryResult = await runSdkImageOnce(body);
+        return {
+            ...retryResult,
+            loginOpened: true,
+            authenticationRequired: retryResult.authenticationRequired
+        };
+    }
+
+    async function resumeThread(body = {}) {
+        const providerKind = await resolveProvider(body.providerKind || body.runtime);
+        const threadId = String(body.threadId || '').trim();
+        if (!threadId) {
+            const err = new Error('threadId is required.');
+            err.statusCode = 400;
+            throw err;
+        }
+
+        if (threads.has(threadId)) {
+            const record = threads.get(threadId);
+            record.lastStatus = 'resumed';
+            record.updatedAtUtc = new Date().toISOString();
+            return makeEmptyResult({
+                success: true,
+                providerKind: record.providerKind,
+                threadId,
+                status: 'resumed',
+                sandboxMode: API_SANDBOX_BY_SDK_VALUE[record.options?.sandboxMode] || record.options?.sandboxMode || ''
+            });
+        }
+
+        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
+            const workingDirectory = await resolveWorkingDirectory(body.workingDir || body.workingDirectory || '');
+            const threadOptions = buildThreadOptions(body, workingDirectory);
+            const sdk = await sdkLoader();
+            await prepareRuntimeHome();
+            const codex = new sdk.Codex({
+                env: childEnvFactory(),
+                config: buildCodexSdkConfigOverrides()
+            });
+            const thread = codex.resumeThread(threadId, threadOptions);
+            threads.set(threadId, {
+                providerKind,
+                thread,
+                createdAtUtc: new Date().toISOString(),
+                updatedAtUtc: new Date().toISOString(),
+                options: threadOptions,
+                officialThreadId: threadId,
+                lastStatus: 'resumed'
+            });
+            return makeEmptyResult({
+                success: true,
+                providerKind,
+                threadId,
+                status: 'resumed',
+                sandboxMode: API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode
+            });
+        }
+
+        return makeEmptyResult({
+            providerKind,
+            threadId,
+            error: 'Thread resume is only supported by the TypeScript SDK provider.'
+        });
+    }
+
+    function cancelThread(body = {}) {
+        const threadId = String(body.threadId || '').trim();
+        const turnId = String(body.turnId || '').trim();
+        const matches = [];
+        for (const [key, turn] of activeTurns.entries()) {
+            if (threadId && turn.threadId !== threadId) {
+                continue;
+            }
+            if (turnId && turn.turnId !== turnId) {
+                continue;
+            }
+            matches.push([key, turn]);
+        }
+
+        for (const [, turn] of matches) {
+            try {
+                turn.abortController.abort();
+            } catch {
+                // Ignore duplicate aborts.
+            }
+        }
+
+        return {
+            success: matches.length > 0,
+            cancelled: matches.length,
+            threadId,
+            turnId,
+            status: matches.length > 0 ? 'cancel-requested' : 'not-found'
+        };
+    }
+
+    function getThreadStatus(threadId) {
+        const id = String(threadId || '').trim();
+        const record = threads.get(id);
+        const active = Array.from(activeTurns.values())
+            .filter(turn => turn.threadId === id || record?.officialThreadId === turn.threadId)
+            .map(turn => ({
+                providerKind: turn.providerKind,
+                threadId: turn.threadId,
+                turnId: turn.turnId,
+                startedAtUtc: turn.startedAtUtc,
+                status: 'running'
+            }));
+
+        return {
+            success: Boolean(record || active.length > 0),
+            threadId: id,
+            providerKind: record?.providerKind || active[0]?.providerKind || PROVIDER_KIND.unavailable,
+            officialThreadId: record?.officialThreadId || null,
+            status: active.length > 0 ? 'running' : (record?.lastStatus || 'not-found'),
+            createdAtUtc: record?.createdAtUtc || null,
+            updatedAtUtc: record?.updatedAtUtc || null,
+            options: serializeThreadOptionsForStatus(record?.options),
+            activeTurns: active,
+            lastResult: record?.lastResult || null
+        };
+    }
+
+    return {
+        providerKinds: PROVIDER_KIND,
+        getCapabilities,
+        startThread,
+        runThread,
+        runImage,
+        resumeThread,
+        cancelThread,
+        getThreadStatus
+    };
+}