mindexec-ai 0.2.385

package/codex-runtime.js

@@ -0,0 +1,1339 @@
+import { promises as fs, readFileSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { exec, execFile, spawn } from 'child_process';
+import { promisify } from 'util';
+import crypto from 'crypto';
+
+const execAsync = promisify(exec);
+const execFileAsync = promisify(execFile);
+
+const PROVIDER_KIND = Object.freeze({
+    fixtureReadOnly: 'FixtureReadOnly',
+    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 MAX_LOG_CHARS = 4000;
+const MAX_EVENT_LOG = 120;
+const TEMP_DIR = '.ai/codex';
+const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
+const CODEX_SOURCE_HOME = path.join(os.homedir(), '.codex');
+const CODEX_RUNTIME_HOME_ENV = 'MINDEXEC_CODEX_HOME';
+const CODEX_PATH_ENV = 'MINDEXEC_CODEX_PATH';
+const CODEX_USE_SOURCE_HOME_ENV = 'MINDEXEC_CODEX_USE_SOURCE_HOME';
+const DEFAULT_CODEX_RUNTIME_HOME = path.join(os.homedir(), '.mindexec', 'codex-runtime');
+const CODEX_RUNTIME_CONFIG_MARKER = '# Generated by MindExec LocalBridge for isolated AI node runs.';
+const CODEX_RUNTIME_AUTH_FILES = ['auth.json'];
+
+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 === 'fixture' || normalized === 'fixturereadonly' || normalized === 'fixture-readonly' || normalized === 'fixture_readonly' || normalized === 'test-fixture') {
+        return PROVIDER_KIND.fixtureReadOnly;
+    }
+
+    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 isEnabledEnv(value) {
+    return /^(1|true|yes|on)$/i.test(String(value || '').trim());
+}
+
+function isFixtureProviderEnabled() {
+    return isEnabledEnv(process.env.MINDEXEC_CODEX_FIXTURE_PROVIDER);
+}
+
+function unquoteTomlKey(value) {
+    const text = String(value || '').trim();
+    if (text.length >= 2 && ((text.startsWith('"') && text.endsWith('"')) || (text.startsWith("'") && text.endsWith("'")))) {
+        return text.slice(1, -1).replace(/\\(["\\])/g, '$1').trim();
+    }
+
+    return text;
+}
+
+function readConfiguredMcpServerNames() {
+    if (!isEnabledEnv(process.env.MINDEXEC_CODEX_DISABLE_SOURCE_MCP)) {
+        return [];
+    }
+
+    const names = new Set();
+    try {
+        const content = readFileSync(CODEX_CONFIG_PATH, 'utf8');
+        for (const rawLine of content.split(/\r?\n/)) {
+            const line = rawLine.trim();
+            const match = line.match(/^\[mcp_servers\.((?:"(?:[^"\\]|\\.)+"|'(?:[^'\\]|\\.)+'|[^\]\s]+))\]$/);
+            if (!match) {
+                continue;
+            }
+
+            const name = unquoteTomlKey(match[1]);
+            if (/^[A-Za-z0-9_-]+$/.test(name)) {
+                names.add(name);
+            }
+        }
+    } catch {
+        // Missing Codex config is fine; SDK auth still reports its own error if login is required.
+    }
+
+    for (const name of String(process.env.MINDEXEC_CODEX_DISABLED_MCP_SERVERS || 'cloudflare,supabase')
+        .split(',')
+        .map(item => item.trim())
+        .filter(Boolean)) {
+        if (/^[A-Za-z0-9_-]+$/.test(name)) {
+            names.add(name);
+        }
+    }
+
+    return Array.from(names).sort();
+}
+
+function buildCodexSdkConfigOverrides() {
+    const mcpServerNames = readConfiguredMcpServerNames();
+    if (mcpServerNames.length === 0) {
+        return {};
+    }
+
+    const mcpServers = {};
+    for (const name of mcpServerNames) {
+        mcpServers[name] = { enabled: false };
+    }
+
+    return { mcp_servers: mcpServers };
+}
+
+function resolveCodexRuntimeHome() {
+    if (isEnabledEnv(process.env[CODEX_USE_SOURCE_HOME_ENV])) {
+        return CODEX_SOURCE_HOME;
+    }
+
+    const configured = String(process.env[CODEX_RUNTIME_HOME_ENV] || '').trim();
+    return path.resolve(configured || DEFAULT_CODEX_RUNTIME_HOME);
+}
+
+function isUsingSourceCodexHome() {
+    return path.resolve(resolveCodexRuntimeHome()).toLowerCase() === path.resolve(CODEX_SOURCE_HOME).toLowerCase();
+}
+
+function resolveCodexPathOverride() {
+    const configured = String(process.env[CODEX_PATH_ENV] || '').trim();
+    return configured ? path.resolve(configured) : null;
+}
+
+async function copyCodexRuntimeFileIfPresent(fileName, runtimeHome) {
+    const source = path.join(CODEX_SOURCE_HOME, fileName);
+    const target = path.join(runtimeHome, fileName);
+    try {
+        const sourceStat = await fs.stat(source);
+        if (!sourceStat.isFile()) {
+            return false;
+        }
+
+        await fs.copyFile(source, target);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+function buildCodexRuntimeConfig(trustedDirectory = '') {
+    const lines = [
+        CODEX_RUNTIME_CONFIG_MARKER,
+        '# User MCP server definitions are intentionally not inherited here.',
+        '# LocalBridge passes model, sandbox, and reasoning options per run.'
+    ];
+
+    const resolvedTrustedDirectory = String(trustedDirectory || '').trim()
+        ? path.resolve(trustedDirectory)
+        : '';
+    if (resolvedTrustedDirectory) {
+        lines.push(
+            '',
+            `[projects.${JSON.stringify(resolvedTrustedDirectory)}]`,
+            'trust_level = "trusted"'
+        );
+    }
+
+    return `${lines.join('\n')}\n`;
+}
+
+async function ensureCodexRuntimeHome(trustedDirectory = '') {
+    const runtimeHome = resolveCodexRuntimeHome();
+    if (isUsingSourceCodexHome()) {
+        return runtimeHome;
+    }
+
+    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 });
+
+    for (const fileName of CODEX_RUNTIME_AUTH_FILES) {
+        await copyCodexRuntimeFileIfPresent(fileName, 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, buildCodexRuntimeConfig(trustedDirectory), 'utf8');
+    }
+
+    return runtimeHome;
+}
+
+function buildCodexChildEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            env[key] = value;
+        }
+    }
+
+    env.CODEX_HOME = resolveCodexRuntimeHome();
+    if (isUsingSourceCodexHome()) {
+        delete env.MINDEXEC_CODEX_ISOLATED_HOME;
+    } else {
+        env.MINDEXEC_CODEX_ISOLATED_HOME = '1';
+    }
+    return env;
+}
+
+function createCodexSdkClient(sdk) {
+    return new sdk.Codex({
+        codexPathOverride: resolveCodexPathOverride(),
+        env: buildCodexChildEnv(),
+        config: buildCodexSdkConfigOverrides()
+    });
+}
+
+function appendCodexIsolationConfigArgs(args) {
+    for (const name of readConfiguredMcpServerNames()) {
+        args.push('--config', `mcp_servers.${name}.enabled=false`);
+    }
+}
+
+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 'never';
+    }
+
+    return 'on-request';
+}
+
+function isPathInside(parentPath, candidatePath) {
+    const relativePath = path.relative(path.resolve(parentPath), path.resolve(candidatePath));
+    return relativePath === '' || (relativePath && !relativePath.startsWith('..') && !path.isAbsolute(relativePath));
+}
+
+function normalizeAdditionalDirectories(value, workingDirectory, sandboxMode) {
+    const resolvedWorkingDirectory = path.resolve(workingDirectory);
+    const candidates = sandboxMode === 'workspace-write'
+        ? [resolvedWorkingDirectory]
+        : [];
+
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const raw = String(item || '').trim();
+            if (!raw) {
+                continue;
+            }
+
+            const resolved = path.resolve(path.isAbsolute(raw)
+                ? raw
+                : path.join(resolvedWorkingDirectory, raw));
+            candidates.push(resolved);
+        }
+    }
+
+    const normalized = [];
+    for (const candidate of candidates) {
+        if (!isPathInside(resolvedWorkingDirectory, candidate)) {
+            continue;
+        }
+
+        if (!normalized.includes(candidate)) {
+            normalized.push(candidate);
+        }
+    }
+
+    return normalized;
+}
+
+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: [],
+        rawEventCount: 0,
+        ...overrides
+    };
+}
+
+function collectItem(result, item) {
+    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)
+        });
+        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 additionalDirectories = normalizeAdditionalDirectories(body?.additionalDirectories, workingDirectory, sandboxMode);
+    const options = {
+        workingDirectory,
+        skipGitRepoCheck: true,
+        sandboxMode,
+        modelReasoningEffort: normalizeReasoningEffort(body?.reasoningEffort),
+        approvalPolicy
+    };
+
+    if (additionalDirectories.length > 0) {
+        options.additionalDirectories = additionalDirectories;
+    }
+
+    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,
+        workingDirectory: options?.workingDirectory || null,
+        additionalDirectories: Array.isArray(options?.additionalDirectories)
+            ? [...options.additionalDirectories]
+            : [],
+        networkAccessEnabled: options?.networkAccessEnabled === undefined ? null : Boolean(options.networkAccessEnabled),
+        webSearchMode: options?.webSearchMode || null
+    };
+}
+
+async function checkSdkAvailability(packageRoot) {
+    const sdk = await loadCodexSdk();
+    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 execFileAsync(resolveCodexPathOverride() || '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;
+}
+
+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 threads = new Map();
+    const activeTurns = new Map();
+
+    async function getCapabilities() {
+        const fixtureEnabled = isFixtureProviderEnabled();
+        const [sdk, legacy, modelCatalog] = await Promise.all([
+            checkSdkAvailability(packageRoot),
+            checkLegacyAvailability(),
+            getModelCatalog()
+        ]);
+        const fixture = {
+            kind: PROVIDER_KIND.fixtureReadOnly,
+            available: fixtureEnabled,
+            implemented: true,
+            version: fixtureEnabled ? 'local-smoke' : null,
+            error: fixtureEnabled ? null : 'Enable MINDEXEC_CODEX_FIXTURE_PROVIDER=1 for local contract smokes only.'
+        };
+        const preferredProviderKind = fixtureEnabled
+            ? PROVIDER_KIND.fixtureReadOnly
+            : sdk.available
+            ? PROVIDER_KIND.typeScriptSdk
+            : legacy.available
+                ? PROVIDER_KIND.legacyExec
+                : PROVIDER_KIND.unavailable;
+
+        return {
+            success: preferredProviderKind !== PROVIDER_KIND.unavailable,
+            preferredProviderKind,
+            providers: [
+                fixture,
+                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',
+                'GET /api/codex/thread/{threadId}/status'
+            ],
+            runtime: getCurrentRuntime(),
+            models: modelCatalog.models || [],
+            modelCatalogSource: modelCatalog.source,
+            modelCatalogUpdatedAt: modelCatalog.updatedAt,
+            modelCatalogError: modelCatalog.error || null
+        };
+    }
+
+    async function resolveProvider(requestedProviderKind) {
+        const requested = normalizeProviderKind(requestedProviderKind);
+        if (isFixtureProviderEnabled() && (!requested || requested === PROVIDER_KIND.fixtureReadOnly)) {
+            return PROVIDER_KIND.fixtureReadOnly;
+        }
+        if (requested === PROVIDER_KIND.fixtureReadOnly) {
+            return PROVIDER_KIND.unavailable;
+        }
+
+        const sdk = await checkSdkAvailability(packageRoot);
+        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;
+        }
+
+        const fallbackLegacy = legacy || await checkLegacyAvailability();
+        if (requested === PROVIDER_KIND.typeScriptSdk && fallbackLegacy?.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.fixtureReadOnly) {
+            const localThreadId = `fixture_${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
+            });
+        }
+
+        if (providerKind === PROVIDER_KIND.typeScriptSdk) {
+            const sdk = await loadCodexSdk();
+            await ensureCodexRuntimeHome(workingDirectory);
+            const codex = createCodexSdkClient(sdk);
+            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 loadCodexSdk();
+        await ensureCodexRuntimeHome(threadOptions?.workingDirectory);
+        const codex = createCodexSdkClient(sdk);
+        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);
+                } 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 runFixtureThread(body, workingDirectory, prompt, startedAtUtc) {
+        const threadOptions = buildThreadOptions(body, workingDirectory);
+        const threadId = String(body.threadId || `fixture_${crypto.randomUUID()}`);
+        const turnId = `turn_${crypto.randomUUID()}`;
+        const sandboxMode = API_SANDBOX_BY_SDK_VALUE[threadOptions.sandboxMode] || threadOptions.sandboxMode;
+        const violations = [];
+
+        if (sandboxMode !== 'read_only') {
+            violations.push(`sandbox=${sandboxMode || 'missing'}`);
+        }
+        if (threadOptions.webSearchMode !== 'disabled') {
+            violations.push(`webSearchMode=${threadOptions.webSearchMode || 'missing'}`);
+        }
+        if (threadOptions.networkAccessEnabled !== false) {
+            violations.push(`networkAccessEnabled=${String(threadOptions.networkAccessEnabled)}`);
+        }
+        if (threadOptions.approvalPolicy !== 'on-request') {
+            violations.push(`approvalPolicy=${threadOptions.approvalPolicy || 'missing'}`);
+        }
+
+        const result = makeEmptyResult({
+            providerKind: PROVIDER_KIND.fixtureReadOnly,
+            threadId,
+            turnId,
+            status: violations.length > 0 ? 'failed' : 'completed',
+            startedAtUtc,
+            completedAtUtc: new Date().toISOString(),
+            sandboxMode,
+            rawEventCount: 1
+        });
+
+        if (violations.length > 0) {
+            result.error = `FixtureReadOnly refused unsafe Codex request: ${violations.join(', ')}`;
+            result.summary = 'The local fixture provider blocks non-read-only CodeMaster execution contracts.';
+        } else {
+            result.success = true;
+            result.summary = 'FixtureReadOnly validated the CodeMaster LocalBridge Codex handoff.';
+            result.finalResponse = [
+                'LocalBridge Codex fixture completed a read-only CodeMaster run.',
+                `Sandbox=${sandboxMode}; approval=${threadOptions.approvalPolicy}; networkAccess=${threadOptions.networkAccessEnabled}; webSearch=${threadOptions.webSearchMode}.`,
+                `WorkingDirectory=${workingDirectory}.`,
+                `InstructionChars=${prompt.length}; changedFiles=0; commandLogs=0.`
+            ].join('\n');
+        }
+
+        threads.set(threadId, {
+            providerKind: PROVIDER_KIND.fixtureReadOnly,
+            createdAtUtc: startedAtUtc,
+            updatedAtUtc: result.completedAtUtc,
+            options: threadOptions,
+            officialThreadId: threadId,
+            lastStatus: result.status,
+            lastResult: result
+        });
+
+        log('Codex fixture run complete', {
+            threadId,
+            turnId,
+            sandbox: sandboxMode,
+            cwd: workingDirectory,
+            success: result.success
+        });
+
+        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 ensureCodexRuntimeHome(workingDirectory);
+        const args = [
+            'exec',
+            '-',
+            '--skip-git-repo-check',
+            '--json',
+            '--disable',
+            'plugins',
+            '--disable',
+            'shell_snapshot',
+            '--cd',
+            workingDirectory,
+            '-s',
+            threadOptions.sandboxMode,
+            '--config',
+            `model_reasoning_effort=${threadOptions.modelReasoningEffort}`,
+            '--config',
+            `approval_policy="${threadOptions.approvalPolicy}"`
+        ];
+        appendCodexIsolationConfigArgs(args);
+
+        if (threadOptions.model) {
+            args.push('-m', threadOptions.model);
+        }
+
+        for (const directory of threadOptions.additionalDirectories || []) {
+            args.push('--add-dir', directory);
+        }
+
+        if (threadOptions.networkAccessEnabled !== undefined) {
+            args.push('--config', `sandbox_workspace_write.network_access=${Boolean(threadOptions.networkAccessEnabled)}`);
+        }
+
+        if (threadOptions.webSearchMode) {
+            args.push('--config', `web_search="${threadOptions.webSearchMode}"`);
+        }
+
+        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(resolveCodexPathOverride() || 'codex', args, {
+                    cwd: workingDirectory,
+                    env: buildCodexChildEnv(),
+                    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.fixtureReadOnly) {
+            return runFixtureThread(body, workingDirectory, prompt, startedAtUtc);
+        }
+
+        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 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 loadCodexSdk();
+            await ensureCodexRuntimeHome(workingDirectory);
+            const codex = createCodexSdkClient(sdk);
+            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,
+        resumeThread,
+        cancelThread,
+        getThreadStatus
+    };
+}