@foxden-app/foxclaw 0.2.0

package/dist/codex_app/client.js

@@ -0,0 +1,1230 @@
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { buildThreadDeepLink, openUrl } from './deeplink.js';
+export class CodexAppClient extends EventEmitter {
+    codexCliBin;
+    launchCommand;
+    autolaunch;
+    serverStatePath;
+    serverLogPath;
+    logger;
+    child = null;
+    socket = null;
+    requestId = 0;
+    pending = new Map();
+    desiredRunning = false;
+    reconnectTimer = null;
+    starting = null;
+    port = null;
+    connected = false;
+    userAgent = null;
+    constructor(codexCliBin, launchCommand, autolaunch, serverStatePath, serverLogPath, logger) {
+        super();
+        this.codexCliBin = codexCliBin;
+        this.launchCommand = launchCommand;
+        this.autolaunch = autolaunch;
+        this.serverStatePath = serverStatePath;
+        this.serverLogPath = serverLogPath;
+        this.logger = logger;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    getUserAgent() {
+        return this.userAgent;
+    }
+    getServerStatus() {
+        const state = this.readServerState();
+        const pid = this.child?.pid ?? state?.pid ?? null;
+        const port = this.port ?? state?.port ?? null;
+        return {
+            pid,
+            port,
+            running: pid !== null && isProcessAlive(pid),
+            managed: state !== null,
+        };
+    }
+    async start() {
+        this.desiredRunning = true;
+        if (this.connected)
+            return;
+        if (!this.starting) {
+            this.starting = this.startServer().finally(() => {
+                this.starting = null;
+            });
+        }
+        await this.starting;
+    }
+    async stop(options = {}) {
+        this.desiredRunning = false;
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        const socket = this.socket;
+        this.socket = null;
+        this.connected = false;
+        socket?.close();
+        if (options.terminateServer ?? true) {
+            await this.terminateServer();
+        }
+        else {
+            this.child = null;
+        }
+        this.rejectPending(new Error('Codex app bridge stopped'));
+    }
+    async restart() {
+        await this.stop({ terminateServer: true });
+        await this.start();
+    }
+    async listThreads(options) {
+        const result = await this.request('thread/list', {
+            limit: options.limit,
+            sortKey: 'updated_at',
+            searchTerm: options.searchTerm ?? null,
+            archived: options.archived ?? false,
+        });
+        const rows = Array.isArray(result.data) ? result.data : [];
+        return rows.map(mapThread);
+    }
+    async listLoadedThreads() {
+        const threadIds = [];
+        let cursor = null;
+        do {
+            const result = await this.request('thread/loaded/list', { cursor, limit: 100 });
+            const rows = Array.isArray(result?.data) ? result.data : [];
+            threadIds.push(...rows.filter((value) => typeof value === 'string'));
+            cursor = typeof result?.nextCursor === 'string' ? result.nextCursor : null;
+        } while (cursor);
+        return threadIds;
+    }
+    async readThread(threadId, includeTurns = false) {
+        const result = await this.request('thread/read', { threadId, includeTurns });
+        const thread = result.thread;
+        return thread ? mapThread(thread) : null;
+    }
+    async readThreadSnapshot(threadId) {
+        const result = await this.request('thread/read', { threadId, includeTurns: true });
+        const thread = result.thread;
+        return thread ? mapThreadSnapshot(thread) : null;
+    }
+    async startThread(options) {
+        const result = await this.request('thread/start', {
+            cwd: options.cwd,
+            approvalPolicy: options.approvalPolicy,
+            model: options.model,
+            modelProvider: null,
+            sandbox: options.sandboxMode,
+            config: null,
+            serviceName: null,
+            baseInstructions: null,
+            developerInstructions: null,
+            personality: null,
+            ephemeral: null,
+            experimentalRawEvents: true,
+            persistExtendedHistory: false,
+        });
+        return mapThreadSessionState(result);
+    }
+    async resumeThread(options) {
+        const result = await this.request('thread/resume', {
+            threadId: options.threadId,
+            cwd: options.cwd ?? null,
+            approvalPolicy: options.approvalPolicy ?? null,
+            baseInstructions: null,
+            developerInstructions: null,
+            config: null,
+            sandbox: options.sandboxMode ?? null,
+            model: options.model ?? null,
+            modelProvider: null,
+            personality: null,
+            experimentalRawEvents: true,
+            persistExtendedHistory: false,
+        });
+        return mapThreadSessionState(result);
+    }
+    async startTurn(options) {
+        const params = {
+            threadId: options.threadId,
+            input: options.input,
+            cwd: options.cwd,
+            approvalPolicy: options.approvalPolicy,
+            sandboxPolicy: mapSandboxPolicy(options.sandboxMode),
+            model: options.model,
+            effort: options.effort,
+            summary: null,
+            personality: null,
+            outputSchema: null,
+        };
+        if (options.serviceTier !== undefined) {
+            params.serviceTier = options.serviceTier;
+        }
+        if (options.collaborationMode) {
+            params.collaborationMode = options.collaborationMode;
+        }
+        const result = await this.request('turn/start', params);
+        return result.turn;
+    }
+    async steerTurn(threadId, expectedTurnId, input) {
+        const result = await this.request('turn/steer', { threadId, expectedTurnId, input });
+        return { turnId: String(result?.turnId ?? expectedTurnId) };
+    }
+    async forkThread(options) {
+        const params = {
+            threadId: options.threadId,
+            cwd: options.cwd,
+            approvalPolicy: options.approvalPolicy,
+            sandbox: options.sandboxMode,
+            model: options.model,
+            modelProvider: null,
+            threadSource: null,
+            ephemeral: false,
+        };
+        if (options.serviceTier !== undefined) {
+            params.serviceTier = options.serviceTier;
+        }
+        const result = await this.request('thread/fork', params);
+        return mapThreadSessionState(result);
+    }
+    async rollbackThread(threadId, numTurns) {
+        const result = await this.request('thread/rollback', { threadId, numTurns });
+        const thread = result?.thread;
+        return thread ? mapThreadSnapshot(thread) : null;
+    }
+    async setThreadName(threadId, name) {
+        await this.request('thread/name/set', { threadId, name });
+    }
+    async compactThread(threadId) {
+        await this.request('thread/compact/start', { threadId });
+    }
+    async getThreadGoal(threadId) {
+        const result = await this.request('thread/goal/get', { threadId });
+        return mapThreadGoal(result?.goal);
+    }
+    async setThreadGoal(options) {
+        const params = { threadId: options.threadId };
+        if (options.objective !== undefined) {
+            params.objective = options.objective;
+        }
+        if (options.status !== undefined) {
+            params.status = options.status;
+        }
+        if (options.tokenBudget !== undefined) {
+            params.tokenBudget = options.tokenBudget;
+        }
+        const result = await this.request('thread/goal/set', params);
+        const goal = mapThreadGoal(result?.goal);
+        if (!goal) {
+            throw new Error('thread/goal/set returned no goal');
+        }
+        return goal;
+    }
+    async clearThreadGoal(threadId) {
+        const result = await this.request('thread/goal/clear', { threadId });
+        return Boolean(result?.cleared);
+    }
+    async listThreadTurns(threadId, limit = 10) {
+        const result = await this.request('thread/turns/list', {
+            threadId,
+            cursor: null,
+            limit,
+            sortDirection: 'desc',
+            itemsView: 'summary',
+        });
+        const turns = Array.isArray(result?.data) ? result.data : [];
+        return turns.map(mapTurnSnapshot);
+    }
+    async archiveThread(threadId) {
+        await this.request('thread/archive', { threadId });
+    }
+    async unarchiveThread(threadId) {
+        const result = await this.request('thread/unarchive', { threadId });
+        const thread = result?.thread;
+        return thread ? mapThread(thread) : null;
+    }
+    async startReview(threadId, target, delivery = 'inline') {
+        const result = await this.request('review/start', { threadId, target, delivery });
+        return {
+            turnId: String(result?.turn?.id ?? ''),
+            reviewThreadId: String(result?.reviewThreadId ?? threadId),
+        };
+    }
+    async listModels() {
+        const models = [];
+        let cursor = null;
+        do {
+            const result = await this.request('model/list', { cursor, limit: 100, includeHidden: false });
+            const rows = Array.isArray(result.data) ? result.data : [];
+            models.push(...rows.map(mapModel));
+            cursor = typeof result.nextCursor === 'string' ? result.nextCursor : null;
+        } while (cursor);
+        return models;
+    }
+    async readAccount() {
+        const result = await this.request('account/read', { refreshToken: false });
+        const account = result?.account;
+        if (!account || typeof account !== 'object') {
+            return null;
+        }
+        return {
+            type: typeof account.type === 'string' ? account.type : 'unknown',
+            email: typeof account.email === 'string' ? account.email : null,
+            planType: typeof account.planType === 'string' ? account.planType : null,
+            requiresOpenaiAuth: Boolean(result?.requiresOpenaiAuth),
+        };
+    }
+    async startDeviceLogin() {
+        const result = await this.request('account/login/start', { type: 'chatgptDeviceCode' });
+        if (result?.type !== 'chatgptDeviceCode') {
+            throw new Error(`Unexpected login response: ${JSON.stringify(result)}`);
+        }
+        return {
+            type: 'chatgptDeviceCode',
+            loginId: String(result.loginId),
+            verificationUrl: String(result.verificationUrl),
+            userCode: String(result.userCode),
+        };
+    }
+    async cancelLogin(loginId) {
+        await this.request('account/login/cancel', { loginId });
+    }
+    async logoutAccount() {
+        await this.request('account/logout', undefined);
+    }
+    async sendAddCreditsNudgeEmail(creditType) {
+        await this.request('account/sendAddCreditsNudgeEmail', { creditType });
+    }
+    async readAccountRateLimits() {
+        const result = await this.request('account/rateLimits/read', undefined);
+        if (!result || typeof result !== 'object') {
+            return null;
+        }
+        return {
+            rateLimits: mapRateLimitSnapshot(result.rateLimits),
+            rateLimitsByLimitId: mapRateLimitsByLimitId(result.rateLimitsByLimitId),
+        };
+    }
+    async readEffectiveConfig(cwd) {
+        const result = await this.request('config/read', {
+            includeLayers: false,
+            cwd,
+        });
+        const config = result?.config ?? {};
+        return {
+            model: typeof config.model === 'string' ? config.model : null,
+            modelReasoningEffort: normalizeReasoningEffort(config.model_reasoning_effort),
+            planModeReasoningEffort: normalizeReasoningEffort(config.plan_mode_reasoning_effort),
+            developerInstructions: typeof config.developer_instructions === 'string' && config.developer_instructions.trim()
+                ? config.developer_instructions
+                : null,
+        };
+    }
+    async listCollaborationModes() {
+        const result = await this.request('collaborationMode/list', {});
+        const rows = Array.isArray(result?.data) ? result.data : [];
+        return rows.map(mapCollaborationModePreset);
+    }
+    async listSkills(cwd, forceReload = false) {
+        const result = await this.request('skills/list', {
+            cwds: cwd ? [cwd] : [],
+            forceReload,
+        });
+        const rows = Array.isArray(result?.data) ? result.data : [];
+        return rows.map(mapSkillsListEntry);
+    }
+    async writeSkillConfig(selector, enabled) {
+        await this.request('skills/config/write', {
+            name: selector.name ?? null,
+            path: selector.path ?? null,
+            enabled,
+        });
+    }
+    async listHooks(cwd) {
+        const result = await this.request('hooks/list', { cwds: cwd ? [cwd] : [] });
+        const rows = Array.isArray(result?.data) ? result.data : [];
+        return rows.map(mapHooksListEntry);
+    }
+    async listPlugins(cwd) {
+        const result = await this.request('plugin/list', {
+            cwds: cwd ? [cwd] : null,
+            marketplaceKinds: null,
+        });
+        const rows = Array.isArray(result?.marketplaces) ? result.marketplaces : [];
+        return rows.map(mapPluginMarketplace);
+    }
+    async readPlugin(pluginName, options = {}) {
+        const result = await this.request('plugin/read', {
+            pluginName,
+            marketplacePath: options.marketplacePath ?? null,
+            remoteMarketplaceName: options.remoteMarketplaceName ?? null,
+        });
+        const plugin = result?.plugin;
+        return plugin && typeof plugin === 'object' ? mapPluginDetail(plugin) : null;
+    }
+    async readPluginSkill(remoteMarketplaceName, remotePluginId, skillName) {
+        const result = await this.request('plugin/skill/read', { remoteMarketplaceName, remotePluginId, skillName });
+        return typeof result?.contents === 'string' ? result.contents : null;
+    }
+    async listApps(threadId, forceRefetch = false) {
+        const apps = [];
+        let cursor = null;
+        do {
+            const result = await this.request('app/list', { cursor, limit: 100, threadId: threadId ?? null, forceRefetch });
+            const rows = Array.isArray(result?.data) ? result.data : [];
+            apps.push(...rows.map(mapAppInfo));
+            cursor = typeof result?.nextCursor === 'string' ? result.nextCursor : null;
+        } while (cursor);
+        return apps;
+    }
+    async readConfig(cwd, includeLayers = true) {
+        const result = await this.request('config/read', { cwd, includeLayers });
+        return result && typeof result === 'object' ? result : {};
+    }
+    async readConfigRequirements() {
+        const result = await this.request('configRequirements/read', undefined);
+        const requirements = result?.requirements;
+        return requirements && typeof requirements === 'object' ? mapConfigRequirements(requirements) : null;
+    }
+    async listExperimentalFeatures() {
+        const features = [];
+        let cursor = null;
+        do {
+            const result = await this.request('experimentalFeature/list', { cursor, limit: 100 });
+            const rows = Array.isArray(result?.data) ? result.data : [];
+            features.push(...rows.map(mapExperimentalFeature));
+            cursor = typeof result?.nextCursor === 'string' ? result.nextCursor : null;
+        } while (cursor);
+        return features;
+    }
+    async readModelProviderCapabilities() {
+        const result = await this.request('modelProvider/capabilities/read', {});
+        return {
+            webSearch: Boolean(result?.webSearch),
+            imageGeneration: Boolean(result?.imageGeneration),
+            namespaceTools: Boolean(result?.namespaceTools),
+        };
+    }
+    async fuzzyFileSearch(query, roots) {
+        const result = await this.request('fuzzyFileSearch', {
+            query,
+            roots,
+            cancellationToken: null,
+        });
+        const files = Array.isArray(result?.files) ? result.files : [];
+        return files.map(mapFuzzyFileResult);
+    }
+    async listMcpServerStatus(detail = 'full') {
+        const rows = [];
+        let cursor = null;
+        do {
+            const result = await this.request('mcpServerStatus/list', { cursor, limit: 100, detail });
+            const data = Array.isArray(result?.data) ? result.data : [];
+            rows.push(...data.map(mapMcpServerStatus));
+            cursor = typeof result?.nextCursor === 'string' ? result.nextCursor : null;
+        } while (cursor);
+        return rows;
+    }
+    async reloadMcpServers() {
+        await this.request('config/mcpServer/reload', undefined);
+    }
+    async loginMcpServer(name) {
+        const result = await this.request('mcpServer/oauth/login', { name });
+        return String(result?.authorizationUrl ?? result?.authorization_url ?? '');
+    }
+    async readMcpResource(server, uri, threadId) {
+        const result = await this.request('mcpServer/resource/read', {
+            server,
+            uri,
+            threadId: threadId ?? null,
+        });
+        const contents = Array.isArray(result?.contents) ? result.contents : [];
+        return contents.map(mapMcpResourceContent);
+    }
+    async interruptTurn(threadId, turnId) {
+        await this.request('turn/interrupt', { threadId, turnId });
+    }
+    async revealThread(threadId) {
+        const url = buildThreadDeepLink(threadId);
+        await openUrl(url);
+    }
+    async respond(requestId, result) {
+        this.send({ jsonrpc: '2.0', id: requestId, result });
+    }
+    async respondError(requestId, message) {
+        this.send({ jsonrpc: '2.0', id: requestId, error: { code: -32000, message } });
+    }
+    async startServer() {
+        if (await this.attachPersistedServer()) {
+            return;
+        }
+        if (this.autolaunch) {
+            const launcher = spawn(this.launchCommand, { shell: true, detached: true, stdio: 'ignore' });
+            launcher.unref();
+        }
+        this.port = await reservePort();
+        const [stdoutFd, stderrFd] = this.openServerLogFiles();
+        let child;
+        try {
+            child = spawn(this.codexCliBin, ['app-server', '--listen', `ws://127.0.0.1:${this.port}`], {
+                detached: true,
+                stdio: ['ignore', stdoutFd, stderrFd],
+            });
+        }
+        finally {
+            fs.closeSync(stdoutFd);
+            fs.closeSync(stderrFd);
+        }
+        child.unref();
+        this.child = child;
+        if (!child.pid) {
+            this.child = null;
+            throw new Error('Failed to start codex app-server: child pid is unavailable');
+        }
+        this.writeServerState({
+            pid: child.pid,
+            port: this.port,
+            command: `${this.codexCliBin} app-server --listen ws://127.0.0.1:${this.port}`,
+            logPath: this.serverLogPath,
+            bridgePid: process.pid,
+            startedAt: new Date().toISOString(),
+        });
+        child.on('exit', (code, signal) => {
+            if (this.child !== child) {
+                return;
+            }
+            this.child = null;
+            if (child.pid) {
+                this.clearServerStateForPid(child.pid);
+            }
+            this.handleDisconnect({ code, signal, source: 'process-exit' });
+        });
+        child.on('error', (error) => {
+            if (this.child !== child) {
+                return;
+            }
+            this.child = null;
+            if (child.pid) {
+                this.clearServerStateForPid(child.pid);
+            }
+            this.handleDisconnect({ error: error.message, source: 'process-error' });
+        });
+        const spawnFailed = new Promise((_, reject) => {
+            child.once('error', reject);
+            child.once('exit', (code, signal) => {
+                reject(new Error(`codex app-server exited before WebSocket connection: code=${code ?? 'null'} signal=${signal ?? 'null'}`));
+            });
+        });
+        await Promise.race([this.connectWebSocket(), spawnFailed]);
+        await this.initialize();
+    }
+    async attachPersistedServer() {
+        const state = this.readServerState();
+        if (!state) {
+            return false;
+        }
+        if (!isProcessAlive(state.pid)) {
+            this.clearServerState();
+            return false;
+        }
+        this.port = state.port;
+        try {
+            await this.connectWebSocket();
+            await this.initialize();
+            this.logger.info('codex.app-server.attached', { pid: state.pid, port: state.port });
+            return true;
+        }
+        catch (error) {
+            const socket = this.socket;
+            this.socket = null;
+            this.connected = false;
+            socket?.close();
+            this.logger.warn('codex.app-server.attach_failed', {
+                pid: state.pid,
+                port: state.port,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            this.clearServerStateForPid(state.pid);
+            return false;
+        }
+    }
+    async connectWebSocket() {
+        const url = `ws://127.0.0.1:${this.port}`;
+        const started = Date.now();
+        while (Date.now() - started < 10_000) {
+            try {
+                await new Promise((resolve, reject) => {
+                    const ws = new WebSocket(url);
+                    const onError = (event) => {
+                        ws.close();
+                        reject(new Error(`WebSocket connect failed: ${String(event.type)}`));
+                    };
+                    ws.addEventListener('open', () => {
+                        this.socket = ws;
+                        this.connected = true;
+                        ws.addEventListener('message', message => this.handleMessage(String(message.data)));
+                        ws.addEventListener('close', () => {
+                            if (this.socket !== ws) {
+                                return;
+                            }
+                            this.socket = null;
+                            this.handleDisconnect({ code: 'ws-close', source: 'websocket-close' });
+                        });
+                        ws.addEventListener('error', err => {
+                            this.logger.warn('codex.ws.error', String(err.message ?? 'unknown'));
+                        });
+                        resolve();
+                    }, { once: true });
+                    ws.addEventListener('error', onError, { once: true });
+                });
+                this.emit('connected');
+                return;
+            }
+            catch {
+                await sleep(250);
+            }
+        }
+        throw new Error(`Timed out connecting to ${url}`);
+    }
+    async initialize() {
+        const result = await this.request('initialize', {
+            clientInfo: {
+                name: 'foxclaw',
+                title: 'FoxClaw',
+                version: '0.2.0',
+            },
+            capabilities: {
+                experimentalApi: true,
+                optOutNotificationMethods: [
+                    'codex/event/agent_reasoning_delta',
+                    'codex/event/reasoning_content_delta',
+                    'codex/event/reasoning_raw_content_delta',
+                    'codex/event/exec_command_output_delta',
+                ]
+            }
+        });
+        this.userAgent = result.userAgent ?? null;
+        this.send({ jsonrpc: '2.0', method: 'initialized' });
+    }
+    async request(method, params) {
+        if (!this.socket || !this.connected) {
+            await this.start();
+        }
+        const id = String(++this.requestId);
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            this.send({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+    send(payload) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN) {
+            throw new Error('codex app-server socket is not open');
+        }
+        this.socket.send(JSON.stringify(payload));
+    }
+    handleMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch (error) {
+            this.logger.warn('codex.message.parse_failed', { raw, error: String(error) });
+            return;
+        }
+        if ('id' in message && !('method' in message)) {
+            const pending = this.pending.get(String(message.id));
+            if (!pending)
+                return;
+            this.pending.delete(String(message.id));
+            if (message.error) {
+                pending.reject(new Error(message.error.message || 'JSON-RPC error'));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if ('id' in message && 'method' in message) {
+            this.emit('serverRequest', message);
+            return;
+        }
+        if ('method' in message) {
+            this.emit('notification', message);
+        }
+    }
+    handleDisconnect(meta) {
+        if (this.connected) {
+            this.connected = false;
+        }
+        this.rejectPending(new Error(`codex app-server disconnected: ${JSON.stringify(meta)}`));
+        this.emit('disconnected', meta);
+        if (this.desiredRunning) {
+            this.scheduleReconnect();
+        }
+    }
+    rejectPending(error) {
+        for (const { reject } of this.pending.values()) {
+            reject(error);
+        }
+        this.pending.clear();
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer || !this.desiredRunning)
+            return;
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            try {
+                await this.startServer();
+            }
+            catch (error) {
+                this.logger.error('codex.reconnect_failed', { error: String(error) });
+                this.scheduleReconnect();
+            }
+        }, 1500);
+    }
+    async terminateServer() {
+        const child = this.child;
+        const state = this.readServerState();
+        const pid = child?.pid ?? state?.pid ?? null;
+        this.child = null;
+        this.clearServerState();
+        if (pid === null || !isProcessAlive(pid)) {
+            return;
+        }
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch (error) {
+            this.logger.warn('codex.app-server.kill_failed', {
+                pid,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return;
+        }
+        const exited = await waitForProcessExit(pid, 3000);
+        if (!exited) {
+            this.logger.warn('codex.app-server.kill_timeout', { pid });
+        }
+    }
+    openServerLogFiles() {
+        fs.mkdirSync(path.dirname(this.serverLogPath), { recursive: true });
+        const stdoutFd = fs.openSync(this.serverLogPath, 'a');
+        try {
+            return [stdoutFd, fs.openSync(this.serverLogPath, 'a')];
+        }
+        catch (error) {
+            fs.closeSync(stdoutFd);
+            throw error;
+        }
+    }
+    readServerState() {
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.serverStatePath, 'utf8'));
+            if (typeof parsed.pid === 'number'
+                && Number.isInteger(parsed.pid)
+                && parsed.pid > 0
+                && typeof parsed.port === 'number'
+                && Number.isInteger(parsed.port)
+                && parsed.port > 0
+                && parsed.port <= 65535) {
+                return {
+                    pid: parsed.pid,
+                    port: parsed.port,
+                    command: typeof parsed.command === 'string' ? parsed.command : '',
+                    logPath: typeof parsed.logPath === 'string' ? parsed.logPath : this.serverLogPath,
+                    bridgePid: typeof parsed.bridgePid === 'number' ? parsed.bridgePid : 0,
+                    startedAt: typeof parsed.startedAt === 'string' ? parsed.startedAt : '',
+                };
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    writeServerState(state) {
+        fs.mkdirSync(path.dirname(this.serverStatePath), { recursive: true });
+        const tmp = `${this.serverStatePath}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(state, null, 2), 'utf8');
+        fs.renameSync(tmp, this.serverStatePath);
+    }
+    clearServerState() {
+        try {
+            fs.unlinkSync(this.serverStatePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                this.logger.warn('codex.app-server.state_clear_failed', {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    clearServerStateForPid(pid) {
+        const state = this.readServerState();
+        if (!state || state.pid !== pid) {
+            return;
+        }
+        this.clearServerState();
+    }
+}
+async function reservePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                reject(new Error('Failed to reserve TCP port'));
+                return;
+            }
+            const port = address.port;
+            server.close(() => resolve(port));
+        });
+        server.on('error', reject);
+    });
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const started = Date.now();
+    while (Date.now() - started < timeoutMs) {
+        if (!isProcessAlive(pid)) {
+            return true;
+        }
+        await sleep(100);
+    }
+    return !isProcessAlive(pid);
+}
+function mapThread(raw) {
+    return {
+        threadId: String(raw.id),
+        name: raw.name ? String(raw.name) : null,
+        preview: String(raw.preview || '(empty)'),
+        cwd: raw.cwd ? String(raw.cwd) : null,
+        modelProvider: raw.modelProvider ? String(raw.modelProvider) : null,
+        source: raw.source ? String(raw.source) : null,
+        path: raw.path ? String(raw.path) : null,
+        status: mapThreadStatus(raw.status),
+        updatedAt: Number(raw.updatedAt || 0),
+    };
+}
+function mapThreadSnapshot(raw) {
+    const base = mapThread(raw);
+    const activeFlags = Array.isArray(raw?.status?.activeFlags)
+        ? raw.status.activeFlags
+            .filter((entry) => typeof entry === 'string')
+        : [];
+    const turns = Array.isArray(raw?.turns)
+        ? raw.turns.map(mapTurnSnapshot)
+        : [];
+    return {
+        ...base,
+        activeFlags,
+        turns,
+    };
+}
+function mapThreadStatus(raw) {
+    const type = raw?.type;
+    if (type === 'active' || type === 'idle' || type === 'notLoaded' || type === 'systemError') {
+        return type;
+    }
+    return 'idle';
+}
+function mapThreadSessionState(raw) {
+    return {
+        thread: mapThread(raw.thread),
+        model: String(raw.model ?? ''),
+        modelProvider: String(raw.modelProvider ?? ''),
+        reasoningEffort: raw.reasoningEffort === null ? null : String(raw.reasoningEffort),
+        cwd: String(raw.cwd ?? ''),
+    };
+}
+function mapTurnSnapshot(raw) {
+    return {
+        turnId: String(raw?.id || ''),
+        status: String(raw?.status || 'unknown'),
+        error: raw?.error ? String(raw.error) : null,
+        items: Array.isArray(raw?.items) ? raw.items.map(mapTurnItemSnapshot) : [],
+        itemsView: typeof raw?.itemsView === 'string' ? raw.itemsView : null,
+        startedAt: numberOrNull(raw?.startedAt),
+        completedAt: numberOrNull(raw?.completedAt),
+        durationMs: numberOrNull(raw?.durationMs),
+    };
+}
+function mapTurnItemSnapshot(raw) {
+    return {
+        itemId: String(raw?.id || ''),
+        type: String(raw?.type || ''),
+        phase: raw?.phase ? String(raw.phase) : null,
+        text: raw?.text ? String(raw.text) : null,
+        command: raw?.command ? String(raw.command) : null,
+        status: raw?.status ? String(raw.status) : null,
+        aggregatedOutput: raw?.aggregatedOutput ? String(raw.aggregatedOutput) : null,
+    };
+}
+function mapModel(raw) {
+    const efforts = Array.isArray(raw.supportedReasoningEfforts)
+        ? raw.supportedReasoningEfforts
+            .map((entry) => entry?.reasoningEffort)
+            .filter((value) => typeof value === 'string')
+        : [];
+    const rawServiceTiers = Array.isArray(raw.serviceTiers)
+        ? raw.serviceTiers
+        : Array.isArray(raw.service_tiers)
+            ? raw.service_tiers
+            : [];
+    const serviceTiers = rawServiceTiers.length > 0
+        ? rawServiceTiers
+            .map((entry) => ({
+            id: typeof entry?.id === 'string' ? entry.id : '',
+            name: typeof entry?.name === 'string' ? entry.name : '',
+            description: typeof entry?.description === 'string' ? entry.description : '',
+        }))
+            .filter((entry) => entry.id.length > 0)
+        : [];
+    return {
+        id: String(raw.id),
+        model: String(raw.model),
+        displayName: String(raw.displayName || raw.model),
+        description: String(raw.description || ''),
+        isDefault: Boolean(raw.isDefault),
+        supportedReasoningEfforts: efforts,
+        defaultReasoningEffort: String(raw.defaultReasoningEffort),
+        serviceTiers,
+    };
+}
+function mapThreadGoal(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const status = normalizeThreadGoalStatus(raw.status);
+    return {
+        threadId: String(raw.threadId ?? raw.thread_id ?? ''),
+        objective: String(raw.objective ?? ''),
+        status,
+        tokenBudget: numberOrNull(raw.tokenBudget ?? raw.token_budget),
+        tokensUsed: numberOrNull(raw.tokensUsed ?? raw.tokens_used) ?? 0,
+        timeUsedSeconds: numberOrNull(raw.timeUsedSeconds ?? raw.time_used_seconds) ?? 0,
+        createdAt: numberOrNull(raw.createdAt ?? raw.created_at) ?? 0,
+        updatedAt: numberOrNull(raw.updatedAt ?? raw.updated_at) ?? 0,
+    };
+}
+function mapFuzzyFileResult(raw) {
+    return {
+        root: String(raw?.root ?? ''),
+        path: String(raw?.path ?? ''),
+        matchType: formatRawLabel(raw?.match_type ?? raw?.matchType),
+        fileName: String(raw?.file_name ?? raw?.fileName ?? ''),
+        score: numberOrNull(raw?.score) ?? 0,
+    };
+}
+function mapRateLimitsByLimitId(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const entries = Object.entries(raw)
+        .map(([key, value]) => [key, mapRateLimitSnapshot(value)])
+        .filter((entry) => entry[1] !== null);
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+}
+function mapCollaborationModePreset(raw) {
+    return {
+        name: String(raw?.name ?? ''),
+        mode: normalizeCollaborationMode(raw?.mode),
+        model: typeof raw?.model === 'string' ? raw.model : null,
+        reasoningEffort: normalizeReasoningEffort(raw?.reasoning_effort),
+    };
+}
+function mapSkillsListEntry(raw) {
+    const skills = Array.isArray(raw?.skills) ? raw.skills : [];
+    const errors = Array.isArray(raw?.errors) ? raw.errors : [];
+    return {
+        cwd: String(raw?.cwd ?? ''),
+        skills: skills.map(mapSkillMetadata),
+        errors: errors.map((entry) => formatRawError(entry)),
+    };
+}
+function mapSkillMetadata(raw) {
+    const iface = raw?.interface && typeof raw.interface === 'object' ? raw.interface : {};
+    return {
+        name: String(raw?.name ?? ''),
+        description: String(raw?.description ?? ''),
+        shortDescription: typeof raw?.shortDescription === 'string' ? raw.shortDescription : null,
+        path: String(raw?.path ?? ''),
+        scope: String(raw?.scope ?? ''),
+        enabled: Boolean(raw?.enabled),
+        displayName: typeof iface.displayName === 'string' ? iface.displayName : null,
+        defaultPrompt: typeof iface.defaultPrompt === 'string' ? iface.defaultPrompt : null,
+    };
+}
+function mapHooksListEntry(raw) {
+    const hooks = Array.isArray(raw?.hooks) ? raw.hooks : [];
+    const errors = Array.isArray(raw?.errors) ? raw.errors : [];
+    const warnings = Array.isArray(raw?.warnings) ? raw.warnings : [];
+    return {
+        cwd: String(raw?.cwd ?? ''),
+        hooks: hooks.map(mapHookMetadata),
+        errors: errors.map((entry) => ({
+            path: String(entry?.path ?? ''),
+            message: String(entry?.message ?? formatRawError(entry)),
+        })),
+        warnings: warnings.map((entry) => String(entry)),
+    };
+}
+function mapHookMetadata(raw) {
+    return {
+        key: String(raw?.key ?? ''),
+        eventName: formatRawLabel(raw?.eventName),
+        handlerType: formatRawLabel(raw?.handlerType),
+        enabled: Boolean(raw?.enabled),
+        trustStatus: formatRawLabel(raw?.trustStatus),
+        sourcePath: String(raw?.sourcePath ?? ''),
+        pluginId: typeof raw?.pluginId === 'string' ? raw.pluginId : null,
+        command: typeof raw?.command === 'string' ? raw.command : null,
+        statusMessage: typeof raw?.statusMessage === 'string' ? raw.statusMessage : null,
+    };
+}
+function mapPluginMarketplace(raw) {
+    const iface = raw?.interface && typeof raw.interface === 'object' ? raw.interface : {};
+    const plugins = Array.isArray(raw?.plugins) ? raw.plugins : [];
+    return {
+        name: String(raw?.name ?? ''),
+        displayName: typeof iface.displayName === 'string' ? iface.displayName : null,
+        path: typeof raw?.path === 'string' ? raw.path : null,
+        plugins: plugins.map(mapPluginSummary),
+    };
+}
+function mapPluginSummary(raw) {
+    const keywords = Array.isArray(raw?.keywords) ? raw.keywords : [];
+    return {
+        id: String(raw?.id ?? ''),
+        name: String(raw?.name ?? raw?.id ?? ''),
+        enabled: Boolean(raw?.enabled),
+        installed: Boolean(raw?.installed),
+        source: formatRawLabel(raw?.source),
+        availability: formatRawLabel(raw?.availability),
+        authPolicy: formatRawLabel(raw?.authPolicy),
+        installPolicy: formatRawLabel(raw?.installPolicy),
+        keywords: keywords.map((entry) => String(entry)),
+    };
+}
+function mapPluginSkillSummary(raw) {
+    return {
+        name: String(raw?.name ?? ''),
+        description: String(raw?.description ?? ''),
+        shortDescription: typeof raw?.shortDescription === 'string' ? raw.shortDescription : null,
+        enabled: Boolean(raw?.enabled),
+        path: typeof raw?.path === 'string' ? raw.path : null,
+    };
+}
+function mapPluginDetail(raw) {
+    const skills = Array.isArray(raw?.skills) ? raw.skills : [];
+    const hooks = Array.isArray(raw?.hooks) ? raw.hooks : [];
+    const apps = Array.isArray(raw?.apps) ? raw.apps : [];
+    const mcpServers = Array.isArray(raw?.mcpServers) ? raw.mcpServers : [];
+    return {
+        marketplaceName: String(raw?.marketplaceName ?? ''),
+        marketplacePath: typeof raw?.marketplacePath === 'string' ? raw.marketplacePath : null,
+        summary: mapPluginSummary(raw?.summary),
+        description: typeof raw?.description === 'string' ? raw.description : null,
+        skills: skills.map(mapPluginSkillSummary),
+        hooks: hooks.map((entry) => ({ key: String(entry?.key ?? ''), eventName: formatRawLabel(entry?.eventName) })),
+        apps: apps.map((entry) => ({
+            id: String(entry?.id ?? ''),
+            name: String(entry?.name ?? ''),
+            description: typeof entry?.description === 'string' ? entry.description : null,
+            needsAuth: Boolean(entry?.needsAuth),
+        })),
+        mcpServers: mcpServers.map((entry) => String(entry)),
+    };
+}
+function mapAppInfo(raw) {
+    const plugins = Array.isArray(raw?.pluginDisplayNames) ? raw.pluginDisplayNames : [];
+    return {
+        id: String(raw?.id ?? ''),
+        name: String(raw?.name ?? raw?.id ?? ''),
+        description: typeof raw?.description === 'string' ? raw.description : null,
+        isEnabled: raw?.isEnabled !== false,
+        isAccessible: Boolean(raw?.isAccessible),
+        installUrl: typeof raw?.installUrl === 'string' ? raw.installUrl : null,
+        distributionChannel: typeof raw?.distributionChannel === 'string' ? raw.distributionChannel : null,
+        pluginDisplayNames: plugins.map((entry) => String(entry)),
+    };
+}
+function mapExperimentalFeature(raw) {
+    return {
+        name: String(raw?.name ?? ''),
+        displayName: typeof raw?.displayName === 'string' ? raw.displayName : null,
+        enabled: Boolean(raw?.enabled),
+        defaultEnabled: Boolean(raw?.defaultEnabled),
+        stage: formatRawLabel(raw?.stage),
+        description: typeof raw?.description === 'string' ? raw.description : null,
+    };
+}
+function mapConfigRequirements(raw) {
+    return {
+        allowedApprovalPolicies: stringArrayOrNull(raw?.allowedApprovalPolicies),
+        allowedSandboxModes: stringArrayOrNull(raw?.allowedSandboxModes),
+        allowedWebSearchModes: stringArrayOrNull(raw?.allowedWebSearchModes),
+        enforceResidency: raw?.enforceResidency === null || raw?.enforceResidency === undefined ? null : formatRawLabel(raw.enforceResidency),
+        featureRequirements: raw?.featureRequirements && typeof raw.featureRequirements === 'object'
+            ? Object.fromEntries(Object.entries(raw.featureRequirements).map(([key, value]) => [key, Boolean(value)]))
+            : null,
+    };
+}
+function mapMcpServerStatus(raw) {
+    const tools = raw?.tools && typeof raw.tools === 'object' ? Object.keys(raw.tools) : [];
+    const resources = Array.isArray(raw?.resources) ? raw.resources : [];
+    const templates = Array.isArray(raw?.resourceTemplates) ? raw.resourceTemplates : [];
+    return {
+        name: String(raw?.name ?? ''),
+        authStatus: formatMcpAuthStatus(raw?.authStatus),
+        toolNames: tools.sort((left, right) => left.localeCompare(right)),
+        resourceUris: resources
+            .map((entry) => typeof entry?.uri === 'string' ? entry.uri : null)
+            .filter((entry) => entry !== null),
+        resourceTemplateUris: templates
+            .map((entry) => typeof entry?.uriTemplate === 'string'
+            ? entry.uriTemplate
+            : typeof entry?.uri_template === 'string'
+                ? entry.uri_template
+                : null)
+            .filter((entry) => entry !== null),
+    };
+}
+function mapMcpResourceContent(raw) {
+    return {
+        type: typeof raw?.text === 'string' ? 'text' : typeof raw?.blob === 'string' ? 'blob' : 'unknown',
+        text: typeof raw?.text === 'string' ? raw.text : null,
+        blob: typeof raw?.blob === 'string' ? raw.blob : null,
+        mimeType: typeof raw?.mimeType === 'string' ? raw.mimeType : null,
+        uri: typeof raw?.uri === 'string' ? raw.uri : null,
+    };
+}
+function formatMcpAuthStatus(raw) {
+    if (raw === null || raw === undefined) {
+        return 'unknown';
+    }
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (typeof raw?.status === 'string') {
+        return raw.status;
+    }
+    if (typeof raw?.type === 'string') {
+        return raw.type;
+    }
+    return JSON.stringify(raw);
+}
+function formatRawError(raw) {
+    if (raw instanceof Error) {
+        return raw.message;
+    }
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (raw && typeof raw === 'object' && 'message' in raw && typeof raw.message === 'string') {
+        return raw.message;
+    }
+    return JSON.stringify(raw);
+}
+function stringArrayOrNull(raw) {
+    return Array.isArray(raw) ? raw.map((entry) => formatRawLabel(entry)) : null;
+}
+function formatRawLabel(raw) {
+    if (raw === null || raw === undefined) {
+        return 'unknown';
+    }
+    if (typeof raw === 'string') {
+        return raw;
+    }
+    if (typeof raw === 'number' || typeof raw === 'boolean') {
+        return String(raw);
+    }
+    if (typeof raw === 'object') {
+        const keys = Object.keys(raw);
+        if (keys.length === 1) {
+            return keys[0];
+        }
+    }
+    return JSON.stringify(raw);
+}
+function normalizeCollaborationMode(value) {
+    return value === 'default' || value === 'plan' ? value : null;
+}
+function normalizeReasoningEffort(value) {
+    return typeof value === 'string' && ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'].includes(value)
+        ? value
+        : null;
+}
+function normalizeThreadGoalStatus(value) {
+    return value === 'paused' || value === 'budgetLimited' || value === 'complete'
+        ? value
+        : 'active';
+}
+function mapRateLimitSnapshot(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return {
+        limitId: typeof raw.limitId === 'string' ? raw.limitId : null,
+        limitName: typeof raw.limitName === 'string' ? raw.limitName : null,
+        primary: mapRateLimitWindow(raw.primary),
+        secondary: mapRateLimitWindow(raw.secondary),
+        credits: mapCreditsSnapshot(raw.credits),
+        planType: typeof raw.planType === 'string' ? raw.planType : null,
+        rateLimitReachedType: typeof raw.rateLimitReachedType === 'string' ? raw.rateLimitReachedType : null,
+    };
+}
+function mapRateLimitWindow(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    const usedPercent = Number(raw.usedPercent);
+    return {
+        usedPercent: Number.isFinite(usedPercent) ? usedPercent : 0,
+        windowDurationMins: numberOrNull(raw.windowDurationMins),
+        resetsAt: numberOrNull(raw.resetsAt),
+    };
+}
+function mapCreditsSnapshot(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return null;
+    }
+    return {
+        hasCredits: Boolean(raw.hasCredits),
+        unlimited: Boolean(raw.unlimited),
+        balance: raw.balance === null || raw.balance === undefined ? null : String(raw.balance),
+    };
+}
+function numberOrNull(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const numberValue = Number(value);
+    return Number.isFinite(numberValue) ? numberValue : null;
+}
+function mapSandboxPolicy(mode) {
+    if (mode === 'read-only') {
+        return { type: 'readOnly' };
+    }
+    if (mode === 'danger-full-access') {
+        return { type: 'dangerFullAccess' };
+    }
+    return { type: 'workspaceWrite' };
+}